ProteoWizard
ParamTypes.hpp
Go to the documentation of this file.
1 //
2 // $Id: ParamTypes.hpp 4008 2012-10-16 17:16:55Z pcbrefugee $
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 
108  ~CVParam();
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 
204  ~UserParam();
205 
206  UserParam(const UserParam& other);
207  UserParam& operator=(const UserParam& rhs);
208 
209  /// Templated value access with type conversion
210  template<typename value_type>
211  value_type valueAs() const
212  {
213  return !value.empty() ? boost::lexical_cast<value_type>(value)
214  : boost::lexical_cast<value_type>(0);
215  }
216 
217  /// returns true iff name, value, type, and units are all empty
218  bool empty() const;
219 
220  /// returns true iff name, value, type, and units are all pairwise equal
221  bool operator==(const UserParam& that) const;
222 
223  /// returns !(this==that)
224  bool operator!=(const UserParam& that) const;
225 };
226 
227 
228 // Special case for bool (outside the class for gcc 3.4, and inline for msvc)
229 template<>
230 inline bool UserParam::valueAs<bool>() const
231 {
232  return value == "true";
233 }
234 
235 
236 struct ParamGroup;
237 typedef boost::shared_ptr<ParamGroup> ParamGroupPtr;
238 
239 
240 /// The base class for elements that may contain cvParams, userParams, or paramGroup references
242 {
243  /// a collection of references to ParamGroups
244  std::vector<ParamGroupPtr> paramGroupPtrs;
245 
246  /// a collection of controlled vocabulary terms
247  std::vector<CVParam> cvParams;
248 
249  /// a collection of uncontrolled user terms
250  std::vector<UserParam> userParams;
251 
252  /// finds cvid in the container:
253  /// - returns first CVParam result such that (result.cvid == cvid);
254  /// - if not found, returns CVParam(CVID_Unknown)
255  /// - recursive: looks into paramGroupPtrs
256  CVParam cvParam(CVID cvid) const;
257 
258  /// finds child of cvid in the container:
259  /// - returns first CVParam result such that (result.cvid is_a cvid);
260  /// - if not found, CVParam(CVID_Unknown)
261  /// - recursive: looks into paramGroupPtrs
262  CVParam cvParamChild(CVID cvid) const;
263 
264  /// finds all children of cvid in the container:
265  /// - returns all CVParam results such that (result.cvid is_a cvid);
266  /// - if not found, empty vector
267  /// - recursive: looks into paramGroupPtrs
268  std::vector<CVParam> cvParamChildren(CVID cvid) const;
269 
270  /// returns true iff cvParams contains exact cvid (recursive)
271  bool hasCVParam(CVID cvid) const;
272 
273  /// returns true iff cvParams contains a child (is_a) of cvid (recursive)
274  bool hasCVParamChild(CVID cvid) const;
275 
276  /// finds UserParam with specified name
277  /// - returns UserParam() if name not found
278  /// - not recursive: looks only at local userParams
279  UserParam userParam(const std::string&) const;
280 
281  /// set/add a CVParam (not recursive)
282  void set(CVID cvid, const std::string& value = "", CVID units = CVID_Unknown);
283 
284  /// set/add a CVParam (not recursive)
285  void set(CVID cvid, double value, CVID units = CVID_Unknown);
286 
287  /// set/add a CVParam (not recursive)
288  void set(CVID cvid, int value, CVID units = CVID_Unknown);
289 
290  /// set/add a CVParam (not recursive)
291  template <typename value_type>
292  void set(CVID cvid, value_type value, CVID units = CVID_Unknown)
293  {
294  set(cvid, boost::lexical_cast<std::string>(value), units);
295  }
296 
297  /// returns true iff the element contains no params or param groups
298  bool empty() const;
299 
300  /// clears the collections
301  void clear();
302 
303  /// returns true iff this and that have the exact same cvParams and userParams
304  /// - recursive: looks into paramGroupPtrs
305  bool operator==(const ParamContainer& that) const;
306 
307  /// returns !(this==that)
308  bool operator!=(const ParamContainer& that) const;
309 };
310 
311 
312 /// special case for bool (outside the class for gcc 3.4, and inline for msvc)
313 template<>
314 inline void ParamContainer::set<bool>(CVID cvid, bool value, CVID units)
315 {
316  set(cvid, (value ? "true" : "false"), units);
317 }
318 
319 
320 /// 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.
322 {
323  /// the identifier with which to reference this ReferenceableParamGroup.
324  std::string id;
325 
326  ParamGroup(const std::string& _id = "");
327 
328  /// returns true iff the element contains no params or param groups
329  bool empty() const;
330 };
331 
332 
333 } // namespace data
334 } // namespace pwiz
335 
336 
337 #endif // _PARAMTYPES_HPP_