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 
36 namespace pwiz {
37 namespace data {
38 
39 
40 using 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)
174 template<>
175 inline bool CVParam::valueAs<bool>() const
176 {
177  return value == "true";
178 }
179 
180 
181 PWIZ_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)
232 template<>
233 inline bool UserParam::valueAs<bool>() const
234 {
235  return value == "true";
236 }
237 
238 
239 struct ParamGroup;
240 typedef 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)
338 template<>
339 inline 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_
pwiz::data::UserParam
Uncontrolled user parameters (essentially allowing free text). Before using these,...
Definition: ParamTypes.hpp:186
pwiz::data::CVParam::valueFixedNotation
std::string valueFixedNotation() const
convenience function to return value without scientific notation (throws if not a double)
pwiz::data::CVParam::operator!=
bool operator!=(const CVParam &that) const
inequality operator
Definition: ParamTypes.hpp:137
pwiz::data::UserParam::type
std::string type
the datatype of the parameter, where appropriate (e.g.: xsd:float).
Definition: ParamTypes.hpp:194
pwiz::data::ParamContainer::set
void set(CVID cvid, double value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
pwiz::data::CVParam::empty
bool empty() const
Definition: ParamTypes.hpp:142
pwiz::data::CVParamIsChildOf::CVParamIsChildOf
CVParamIsChildOf(CVID cvid)
Definition: ParamTypes.hpp:166
pwiz::data::ParamContainer::clear
void clear()
clears the collections
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, unsigned int _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:74
pwiz
Definition: ChromatogramList_Filter.hpp:36
pwiz::cv
Definition: cv.hpp:108
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, float _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:50
pwiz::data::ParamContainer::userParams
std::vector< UserParam > userParams
a collection of uncontrolled user terms
Definition: ParamTypes.hpp:253
pwiz::data::ParamContainer::operator!=
bool operator!=(const ParamContainer &that) const
returns !(this==that)
pwiz::data::UserParam::operator==
bool operator==(const UserParam &that) const
returns true iff name, value, type, and units are all pairwise equal
pwiz::msdata::id::value
PWIZ_API_DECL std::string value(const std::string &id, const std::string &name)
convenience function to extract a named value from an id string
pwiz::data::CVParam::timeInSeconds
double timeInSeconds() const
convenience function to return time in seconds (throws if units not a time unit)
pwiz::data::UserParam::valueAs
value_type valueAs() const
Templated value access with type conversion.
Definition: ParamTypes.hpp:214
pwiz::data::CVParamIsChildOf
functor for finding children of a specified CVID in a collection of CVParams:
Definition: ParamTypes.hpp:165
pwiz::data::UserParam::units
CVID units
an optional CV parameter for the unit term associated with the value, if any (e.g....
Definition: ParamTypes.hpp:197
pwiz::data::ParamGroup::empty
bool empty() const
returns true iff the element contains no params or param groups
boost
Definition: DateTime.hpp:41
PWIZ_API_DECL
#define PWIZ_API_DECL
Definition: Export.hpp:32
optimized_lexical_cast.hpp
pwiz::data::CVParam::~CVParam
~CVParam()
pwiz::data::UserParam::operator=
UserParam & operator=(const UserParam &rhs)
pwiz::data::CVParamIs::CVParamIs
CVParamIs(CVID cvid)
Definition: ParamTypes.hpp:153
pwiz::data::ParamContainer::cvParamValueOrDefault
ValueT cvParamValueOrDefault(CVID cvid, ValueT defaultValue) const
finds cvid in the container:
Definition: ParamTypes.hpp:272
pwiz::data::UserParam::operator!=
bool operator!=(const UserParam &that) const
returns !(this==that)
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid=CVID_Unknown)
constructor for non-valued CVParams
Definition: ParamTypes.hpp:104
pwiz::data::ParamGroup
A collection of CVParam and UserParam elements that can be referenced from elsewhere in this mzML doc...
Definition: ParamTypes.hpp:347
pwiz::data::operator<<
std::ostream & operator<<(std::ostream &os, const Diff< object_type, config_type > &diff)
stream insertion of Diff results
Definition: diff_std.hpp:200
pwiz::data::CVParam::valueAs
value_type valueAs() const
templated value access with type conversion
Definition: ParamTypes.hpp:112
Export.hpp
pwiz::data::ParamGroupPtr
boost::shared_ptr< ParamGroup > ParamGroupPtr
Definition: ParamTypes.hpp:239
pwiz::data::CVParam::unitsName
std::string unitsName() const
convenience function to return string for the units
pwiz::data::ParamGroup::id
std::string id
the identifier with which to reference this ReferenceableParamGroup.
Definition: ParamTypes.hpp:349
pwiz::data::ParamContainer::empty
bool empty() const
returns true iff the element contains no params or param groups
pwiz::data::ParamContainer::operator==
bool operator==(const ParamContainer &that) const
returns true iff this and that have the exact same cvParams and userParams
pwiz::data::CVParam::units
CVID units
Definition: ParamTypes.hpp:48
pwiz::data::ParamContainer::userParam
UserParam userParam(const std::string &) const
finds UserParam with specified name
pwiz::data::UserParam::UserParam
UserParam(const std::string &_name="", const std::string &_value="", const std::string &_type="", CVID _units=CVID_Unknown)
pwiz::data::UserParam::UserParam
UserParam(const UserParam &other)
pwiz::data::ParamContainer::cvParam
CVParam cvParam(CVID cvid) const
finds cvid in the container:
CVID_Unknown
CVID_Unknown
Definition: cv.hpp:114
pwiz::data::ParamContainer
The base class for elements that may contain cvParams, userParams, or paramGroup references.
Definition: ParamTypes.hpp:245
pwiz::data::ParamContainer::hasCVParamChild
bool hasCVParamChild(CVID cvid) const
returns true iff cvParams contains a child (is_a) of cvid (recursive)
pwiz::data::CVParamIs::operator()
bool operator()(const CVParam &param) const
Definition: ParamTypes.hpp:154
pwiz::data::CVParam::value
std::string value
Definition: ParamTypes.hpp:47
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, int _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:62
pwiz::data::ParamContainer::hasCVParam
bool hasCVParam(CVID cvid) const
returns true iff cvParams contains exact cvid (recursive)
pwiz::data::CVParamIs::cvid_
CVID cvid_
Definition: ParamTypes.hpp:155
pwiz::data::UserParam::value
std::string value
the value for the parameter, where appropriate.
Definition: ParamTypes.hpp:191
pwiz::data::ParamContainer::cvParamChildren
std::vector< CVParam > cvParamChildren(CVID cvid) const
finds all children of cvid in the container:
pwiz::data::CVParamIsChildOf::cvid_
CVID cvid_
Definition: ParamTypes.hpp:168
pwiz::data::CVParamIs
functor for finding CVParam with specified exact CVID in a collection of CVParams:
Definition: ParamTypes.hpp:152
pwiz::data::ParamContainer::set
void set(CVID cvid, value_type value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
Definition: ParamTypes.hpp:317
defaultValue
T defaultValue()
Definition: BinaryDataTest.cpp:33
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, unsigned long _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:80
pwiz::data::ParamContainer::cvParamChild
CVParam cvParamChild(CVID cvid) const
finds child of cvid in the container:
pwiz::data::ParamContainer::set
void set(CVID cvid, int value, CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
pwiz::data::CVParamIsChildOf::operator()
bool operator()(const CVParam &param) const
Definition: ParamTypes.hpp:167
pwiz::cv::cvIsA
PWIZ_API_DECL bool cvIsA(CVID child, CVID parent)
returns true iff child IsA parent in the CV
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, double _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:56
pwiz::data::CVParam::name
std::string name() const
convenience function to return string for the cvid
boost::lexical_cast
toType lexical_cast(const std::string &str, bool &success)
Definition: optimized_lexical_cast.hpp:70
pwiz::data::CVParam::operator==
bool operator==(const CVParam &that) const
equality operator
Definition: ParamTypes.hpp:131
pwiz::data::ParamContainer::set
void set(CVID cvid, const std::string &value="", CVID units=CVID_Unknown)
set/add a CVParam (not recursive)
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, const char *_value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:92
pwiz::data::UserParam::empty
bool empty() const
returns true iff name, value, type, and units are all empty
pwiz::data::ParamContainer::paramGroupPtrs
std::vector< ParamGroupPtr > paramGroupPtrs
a collection of references to ParamGroups
Definition: ParamTypes.hpp:247
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, long _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:68
pwiz::data::CVParam::cvid
CVID cvid
Definition: ParamTypes.hpp:46
pwiz::data::UserParam::timeInSeconds
double timeInSeconds() const
convenience function to return time in seconds (throws if units not a time unit)
pwiz::data::ParamContainer::cvParamChildValueOrDefault
ValueT cvParamChildValueOrDefault(CVID cvid, ValueT defaultValue) const
finds child of cvid in the container:
Definition: ParamTypes.hpp:283
pwiz::data::UserParam::~UserParam
~UserParam()
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, bool _value, CVID _units=CVID_Unknown)
special case for bool (no lexical_cast)
Definition: ParamTypes.hpp:99
pwiz::data::CVParam
represents a tag-value pair, where the tag comes from the controlled vocabulary
Definition: ParamTypes.hpp:45
pwiz::data::CVParam::CVParam
CVParam(CVID _cvid, std::string _value, CVID _units=CVID_Unknown)
Definition: ParamTypes.hpp:86
cv.hpp
pwiz::data::operator==
bool operator==(const SampleDatum< abscissa_type, ordinate_type > &a, const SampleDatum< abscissa_type, ordinate_type > &b)
Definition: SampleDatum.hpp:52
pwiz::data::UserParam::name
std::string name
the name for the parameter.
Definition: ParamTypes.hpp:188
pwiz::data::ParamGroup::ParamGroup
ParamGroup(const std::string &_id="")
pwiz::data::ParamContainer::cvParams
std::vector< CVParam > cvParams
a collection of controlled vocabulary terms
Definition: ParamTypes.hpp:250