ProteoWizard
ParamTypes.hpp
Go to the documentation of this file.
1//
2// $Id$
3//
4//
5// Original author: Darren Kessner <darren@proteowizard.org>
6//
7// Copyright 2007 Spielberg Family Center for Applied Proteomics
8// Cedars-Sinai Medical Center, Los Angeles, California 90048
9//
10// Licensed under the Apache License, Version 2.0 (the "License");
11// you may not use this file except in compliance with the License.
12// You may obtain a copy of the License at
13//
14// http://www.apache.org/licenses/LICENSE-2.0
15//
16// Unless required by applicable law or agreed to in writing, software
17// distributed under the License is distributed on an "AS IS" BASIS,
18// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19// See the License for the specific language governing permissions and
20// limitations under the License.
21//
22
23
24#ifndef _PARAMTYPES_HPP_
25#define _PARAMTYPES_HPP_
26
27
30#include "cv.hpp"
31#include <iosfwd>
32#include <vector>
33#include <boost/shared_ptr.hpp>
34
35
36namespace pwiz {
37namespace data {
38
39
40using namespace pwiz::cv;
41
42
43/// represents a tag-value pair, where the tag comes from the controlled vocabulary
45{
46 CVID cvid;
47 std::string value;
48 CVID units;
49
50 CVParam(CVID _cvid, float _value, CVID _units = CVID_Unknown)
51 : cvid(_cvid),
52 value(boost::lexical_cast<std::string>(_value)),
53 units(_units)
54 {}
55
56 CVParam(CVID _cvid, double _value, CVID _units = CVID_Unknown)
57 : cvid(_cvid),
58 value(boost::lexical_cast<std::string>(_value)),
59 units(_units)
60 {}
61
62 CVParam(CVID _cvid, int _value, CVID _units = CVID_Unknown)
63 : cvid(_cvid),
64 value(boost::lexical_cast<std::string>(_value)),
65 units(_units)
66 {}
67
68 CVParam(CVID _cvid, long _value, CVID _units = CVID_Unknown)
69 : cvid(_cvid),
70 value(boost::lexical_cast<std::string>(_value)),
71 units(_units)
72 {}
73
74 CVParam(CVID _cvid, unsigned int _value, CVID _units = CVID_Unknown)
75 : cvid(_cvid),
76 value(boost::lexical_cast<std::string>(_value)),
77 units(_units)
78 {}
79
80 CVParam(CVID _cvid, unsigned long _value, CVID _units = CVID_Unknown)
81 : cvid(_cvid),
82 value(boost::lexical_cast<std::string>(_value)),
83 units(_units)
84 {}
85
86 CVParam(CVID _cvid, std::string _value, CVID _units = CVID_Unknown)
87 : cvid(_cvid),
88 value(_value),
89 units(_units)
90 {}
91
92 CVParam(CVID _cvid, const char* _value, CVID _units = CVID_Unknown)
93 : cvid(_cvid),
94 value(_value),
95 units(_units)
96 {}
97
98 /// special case for bool (no lexical_cast)
99 CVParam(CVID _cvid, bool _value, CVID _units = CVID_Unknown)
100 : cvid(_cvid), value(_value ? "true" : "false"), units(_units)
101 {}
102
103 /// constructor for non-valued CVParams
104 CVParam(CVID _cvid = CVID_Unknown)
105 : cvid(_cvid), units(CVID_Unknown)
106 {}
107
109
110 /// templated value access with type conversion
111 template<typename value_type>
112 value_type valueAs() const
113 {
114 return !value.empty() ? boost::lexical_cast<value_type>(value)
115 : boost::lexical_cast<value_type>(0);
116 }
117
118 /// convenience function to return string for the cvid
119 std::string name() const;
120
121 /// convenience function to return string for the units
122 std::string unitsName() const;
123
124 /// convenience function to return time in seconds (throws if units not a time unit)
125 double timeInSeconds() const;
126
127 /// convenience function to return value without scientific notation (throws if not a double)
128 std::string valueFixedNotation() const;
129
130 /// equality operator
131 bool operator==(const CVParam& that) const
132 {
133 return that.cvid==cvid && that.value==value && that.units==units;
134 }
135
136 /// inequality operator
137 bool operator!=(const CVParam& that) const
138 {
139 return !operator==(that);
140 }
141
142 bool empty() const {return cvid==CVID_Unknown && value.empty() && units==CVID_Unknown;}
143};
144
145
146/// functor for finding CVParam with specified exact CVID in a collection of CVParams:
147///
148/// vector<CVParam>::const_iterator it =
149/// find_if(params.begin(), params.end(), CVParamIs(MS_software));
150///
152{
153 CVParamIs(CVID cvid) : cvid_(cvid) {}
154 bool operator()(const CVParam& param) const {return param.cvid == cvid_;}
155 CVID cvid_;
156};
157
158
159/// functor for finding children of a specified CVID in a collection of CVParams:
160///
161/// vector<CVParam>::const_iterator it =
162/// find_if(params.begin(), params.end(), CVParamIsChildOf(MS_software));
163///
165{
166 CVParamIsChildOf(CVID cvid) : cvid_(cvid) {}
167 bool operator()(const CVParam& param) const {return cvIsA(param.cvid, cvid_);}
168 CVID cvid_;
169};
170
171
172/// special case for bool (no lexical_cast)
173/// (this has to be outside the class for gcc 3.4, inline for msvc)
174template<>
175inline bool CVParam::valueAs<bool>() const
176{
177 return value == "true";
178}
179
180
181PWIZ_API_DECL std::ostream& operator<<(std::ostream& os, const CVParam& param);
182
183
184/// Uncontrolled user parameters (essentially allowing free text). Before using these, one should verify whether there is an appropriate CV term available, and if so, use the CV term instead
186{
187 /// the name for the parameter.
188 std::string name;
189
190 /// the value for the parameter, where appropriate.
191 std::string value;
192
193 /// the datatype of the parameter, where appropriate (e.g.: xsd:float).
194 std::string type;
195
196 /// an optional CV parameter for the unit term associated with the value, if any (e.g. MS_electron_volt).
197 CVID units;
198
199 UserParam(const std::string& _name = "",
200 const std::string& _value = "",
201 const std::string& _type = "",
202 CVID _units = CVID_Unknown);
203
205
206 UserParam(const UserParam& other);
208
209 /// convenience function to return time in seconds (throws if units not a time unit)
210 double timeInSeconds() const;
211
212 /// Templated value access with type conversion
213 template<typename value_type>
214 value_type valueAs() const
215 {
216 return !value.empty() ? boost::lexical_cast<value_type>(value)
217 : boost::lexical_cast<value_type>(0);
218 }
219
220 /// returns true iff name, value, type, and units are all empty
221 bool empty() const;
222
223 /// returns true iff name, value, type, and units are all pairwise equal
224 bool operator==(const UserParam& that) const;
225
226 /// returns !(this==that)
227 bool operator!=(const UserParam& that) const;
228};
229
230
231// Special case for bool (outside the class for gcc 3.4, and inline for msvc)
232template<>
233inline bool UserParam::valueAs<bool>() const
234{
235 return value == "true";
236}
237
238
239struct ParamGroup;
240typedef boost::shared_ptr<ParamGroup> ParamGroupPtr;
241
242
243/// The base class for elements that may contain cvParams, userParams, or paramGroup references
245{
246 /// a collection of references to ParamGroups
247 std::vector<ParamGroupPtr> paramGroupPtrs;
248
249 /// a collection of controlled vocabulary terms
250 std::vector<CVParam> cvParams;
251
252 /// a collection of uncontrolled user terms
253 std::vector<UserParam> userParams;
254
255 /// finds cvid in the container:
256 /// - returns first CVParam result such that (result.cvid == cvid);
257 /// - if not found, returns CVParam(CVID_Unknown)
258 /// - recursive: looks into paramGroupPtrs
259 CVParam cvParam(CVID cvid) const;
260
261 /// finds child of cvid in the container:
262 /// - returns first CVParam result such that (result.cvid is_a cvid);
263 /// - if not found, CVParam(CVID_Unknown)
264 /// - recursive: looks into paramGroupPtrs
265 CVParam cvParamChild(CVID cvid) const;
266
267 /// finds cvid in the container:
268 /// - returns first CVParam result's value such that (result.cvid == cvid);
269 /// - if not found, returns the given default value
270 /// - recursive: looks into paramGroupPtrs
271 template<typename ValueT>
272 ValueT cvParamValueOrDefault(CVID cvid, ValueT defaultValue) const
273 {
274 CVParam p = cvParam(cvid);
275 return p.empty() ? defaultValue : p.valueAs<ValueT>();
276 }
277
278 /// finds child of cvid in the container:
279 /// - returns first CVParam result's value such that (result.cvid is_a cvid);
280 /// - if not found, returns the given default value
281 /// - recursive: looks into paramGroupPtrs
282 template<typename ValueT>
283 ValueT cvParamChildValueOrDefault(CVID cvid, ValueT defaultValue) const
284 {
285 CVParam p = cvParamChild(cvid);
286 return p.empty() ? defaultValue : p.valueAs<ValueT>();
287 }
288
289 /// finds all children of cvid in the container:
290 /// - returns all CVParam results such that (result.cvid is_a cvid);
291 /// - if not found, empty vector
292 /// - recursive: looks into paramGroupPtrs
293 std::vector<CVParam> cvParamChildren(CVID cvid) const;
294
295 /// returns true iff cvParams contains exact cvid (recursive)
296 bool hasCVParam(CVID cvid) const;
297
298 /// returns true iff cvParams contains a child (is_a) of cvid (recursive)
299 bool hasCVParamChild(CVID cvid) const;
300
301 /// finds UserParam with specified name
302 /// - returns UserParam() if name not found
303 /// - not recursive: looks only at local userParams
304 UserParam userParam(const std::string&) const;
305
306 /// set/add a CVParam (not recursive)
307 void set(CVID cvid, const std::string& value = "", CVID units = CVID_Unknown);
308
309 /// set/add a CVParam (not recursive)
310 void set(CVID cvid, double value, CVID units = CVID_Unknown);
311
312 /// set/add a CVParam (not recursive)
313 void set(CVID cvid, int value, CVID units = CVID_Unknown);
314
315 /// set/add a CVParam (not recursive)
316 template <typename value_type>
317 void set(CVID cvid, value_type value, CVID units = CVID_Unknown)
318 {
319 set(cvid, boost::lexical_cast<std::string>(value), units);
320 }
321
322 /// returns true iff the element contains no params or param groups
323 bool empty() const;
324
325 /// clears the collections
326 void clear();
327
328 /// returns true iff this and that have the exact same cvParams and userParams
329 /// - recursive: looks into paramGroupPtrs
330 bool operator==(const ParamContainer& that) const;
331
332 /// returns !(this==that)
333 bool operator!=(const ParamContainer& that) const;
334};
335
336
337/// special case for bool (outside the class for gcc 3.4, and inline for msvc)
338template<>
339inline void ParamContainer::set<bool>(CVID cvid, bool value, CVID units)
340{
341 set(cvid, (value ? "true" : "false"), units);
342}
343
344
345/// A collection of CVParam and UserParam elements that can be referenced from elsewhere in this mzML document by using the 'paramGroupRef' element in that location to reference the 'id' attribute value of this element.
347{
348 /// the identifier with which to reference this ReferenceableParamGroup.
349 std::string id;
350
351 ParamGroup(const std::string& _id = "");
352
353 /// returns true iff the element contains no params or param groups
354 bool empty() const;
355};
356
357
358} // namespace data
359} // namespace pwiz
360
361
362#endif // _PARAMTYPES_HPP_
T defaultValue()
#define PWIZ_API_DECL
Definition Export.hpp:32
CVID_Unknown
Definition cv.hpp:114
PWIZ_API_DECL bool cvIsA(CVID child, CVID parent)
returns true iff child IsA parent in the CV
std::ostream & operator<<(std::ostream &os, const Diff< object_type, config_type > &diff)
stream insertion of Diff results
Definition diff_std.hpp:200
boost::shared_ptr< ParamGroup > ParamGroupPtr
STL namespace.
represents a tag-value pair, where the tag comes from the controlled vocabulary
std::string valueFixedNotation() const
convenience function to return value without scientific notation (throws if not a double)
CVParam(CVID _cvid, std::string _value, CVID _units=CVID_Unknown)
std::string unitsName() const
convenience function to return string for the units
CVParam(CVID _cvid=CVID_Unknown)
constructor for non-valued CVParams
double timeInSeconds() const
convenience function to return time in seconds (throws if units not a time unit)
CVParam(CVID _cvid, bool _value, CVID _units=CVID_Unknown)
special case for bool (no lexical_cast)
CVParam(CVID _cvid, double _value, CVID _units=CVID_Unknown)
bool operator!=(const CVParam &that) const
inequality operator
CVParam(CVID _cvid, const char *_value, CVID _units=CVID_Unknown)
std::string name() const
convenience function to return string for the cvid
value_type valueAs() const
templated value access with type conversion
CVParam(CVID _cvid, int _value, CVID _units=CVID_Unknown)
CVParam(CVID _cvid, unsigned int _value, CVID _units=CVID_Unknown)
CVParam(CVID _cvid, unsigned long _value, CVID _units=CVID_Unknown)
CVParam(CVID _cvid, long _value, CVID _units=CVID_Unknown)
CVParam(CVID _cvid, float _value, CVID _units=CVID_Unknown)
bool operator==(const CVParam &that) const
equality operator
functor for finding children of a specified CVID in a collection of CVParams:
bool operator()(const CVParam &param) const
functor for finding CVParam with specified exact CVID in a collection of CVParams:
bool operator()(const CVParam &param) const
The base class for elements that may contain cvParams, userParams, or paramGroup references.
bool empty() const
returns true iff the element contains no params or param groups
void set(CVID cvid, const std::string &value="", CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
void set(CVID cvid, double value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
std::vector< ParamGroupPtr > paramGroupPtrs
a collection of references to ParamGroups
void set(CVID cvid, int value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
bool hasCVParamChild(CVID cvid) const
returns true iff cvParams contains a child (is_a) of cvid (recursive)
bool operator!=(const ParamContainer &that) const
returns !(this==that)
CVParam cvParam(CVID cvid) const
finds cvid in the container:
std::vector< CVParam > cvParams
a collection of controlled vocabulary terms
bool operator==(const ParamContainer &that) const
returns true iff this and that have the exact same cvParams and userParams
UserParam userParam(const std::string &) const
finds UserParam with specified name
std::vector< CVParam > cvParamChildren(CVID cvid) const
finds all children of cvid in the container:
void clear()
clears the collections
ValueT cvParamValueOrDefault(CVID cvid, ValueT defaultValue) const
finds cvid in the container:
std::vector< UserParam > userParams
a collection of uncontrolled user terms
CVParam cvParamChild(CVID cvid) const
finds child of cvid in the container:
bool hasCVParam(CVID cvid) const
returns true iff cvParams contains exact cvid (recursive)
void set(CVID cvid, value_type value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
ValueT cvParamChildValueOrDefault(CVID cvid, ValueT defaultValue) const
finds child of cvid in the container:
A collection of CVParam and UserParam elements that can be referenced from elsewhere in this mzML doc...
ParamGroup(const std::string &_id="")
std::string id
the identifier with which to reference this ReferenceableParamGroup.
bool empty() const
returns true iff the element contains no params or param groups
Uncontrolled user parameters (essentially allowing free text). Before using these,...
UserParam(const std::string &_name="", const std::string &_value="", const std::string &_type="", CVID _units=CVID_Unknown)
bool operator!=(const UserParam &that) const
returns !(this==that)
UserParam & operator=(const UserParam &rhs)
CVID units
an optional CV parameter for the unit term associated with the value, if any (e.g....
bool operator==(const UserParam &that) const
returns true iff name, value, type, and units are all pairwise equal
value_type valueAs() const
Templated value access with type conversion.
UserParam(const UserParam &other)
std::string value
the value for the parameter, where appropriate.
bool empty() const
returns true iff name, value, type, and units are all empty
std::string name
the name for the parameter.
double timeInSeconds() const
convenience function to return time in seconds (throws if units not a time unit)
std::string type
the datatype of the parameter, where appropriate (e.g.: xsd:float).