UnitOfMeasure.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/common/UnitOfMeasure.h
22 
23  \brief A class for representing a unit of measure.
24 */
25 
26 #ifndef __TERRALIB_COMMON_INTERNAL_UNITOFMEASURE_H
27 #define __TERRALIB_COMMON_INTERNAL_UNITOFMEASURE_H
28 
29 // TerraLib
30 #include "Config.h"
31 #include "Enums.h"
32 
33 // STL
34 #include <vector>
35 #include <string>
36 
37 // Boost
38 #include <boost/shared_ptr.hpp>
39 
40 namespace te
41 {
42  namespace common
43  {
44  /*!
45  \class UnitOfMeasure
46 
47  \brief A class to represent units of measure.
48 
49  The use of a unit of measure is meant to encompass the means by which a
50  measured value is tied explicitly to its unit of measure.
51 
52  Units of measure can be Base or Derived. Base units are well-defined units
53  which by convention are regarded as dimensionally independent. There is only
54  one Base Unit per type of measure.
55 
56  Derived units are those formed by combining base units according to the algebraic
57  relations linking the corresponding quantities.
58 
59  Units have an unique numerical identification, an oficial name, a symbol, the
60  type of measures that they refer to and an optional description. Derived Units
61  also have the identification of its Base Unit and 4 factors to relate them,
62  using the following formula:
63 
64  \code
65  Y = (AX + B) / (CX + D)
66  \endcode
67 
68  where Y is the measure in the derived unit and X is measure in base unit.
69 
70  \ingroup common
71 
72  \sa UnitsOfMeasureManager
73  */
75  {
76  public:
77 
78  /*!
79  \brief Creates a new base unit of measure.
80 
81  \param id Unique identification number.
82  \param name Unit official name.
83  \param symbol Unit symbol.
84  \param type Unit type of measure.
85  \param description Unit description (by default empty).
86  */
87  UnitOfMeasure(unsigned int id, const std::string& name, const std::string& symbol,
88  MeasureType type, const std::string& description = "");
89 
90  /*!
91  \brief Creates a new derived unit of measure.
92 
93  \param id Unit unique identification number for a unit of measure.
94  \param name Unit official name.
95  \param symbol Unit symbol.
96  \param type Unit type of measure
97  \param baseUnitId Identification of the base unit from which this is derived of.
98  \param A A factor in the conversion formula.
99  \param B B factor in the conversion formula.
100  \param C C factor in the conversion formula.
101  \param D D factor in the conversion formula.
102  \param description Unit description (by default empty).
103 
104  \note (C + D) can not be zero.
105  */
106  UnitOfMeasure(unsigned int id, const std::string& name, const std::string& symbol,
107  MeasureType type, unsigned int baseUnitId,
108  double A, double B = 0.0, double C = 0.0, double D = 1.0,
109  const std::string& description = "");
110 
111  /*! \brief Destructor. */
112  ~UnitOfMeasure();
113 
114  /*!
115  \brief Returns the unit of measure identification.
116 
117  \return The unit of measure identification.
118  */
119  unsigned int getId() const;
120 
121  /*!
122  \brief Returns the unit of measure oficial name.
123 
124  \return The unit of measure oficial name.
125  */
126  const std::string& getName() const;
127 
128  /*!
129  \brief Sets the unit of measure description.
130 
131  \param description The unit of measure description.
132  */
133  void setDescription(const std::string& description);
134 
135  /*!
136  \brief Returns the unit of measure description.
137 
138  \return The unit of measure description.
139  */
140  const std::string& getDescription() const;
141 
142  /*!
143  \brief Returns the unit of measure symbol.
144 
145  \return The unit of measure symbol (e.g. kg, m or km).
146  */
147  const std::string& getSymbol() const;
148 
149  /*!
150  \brief Returns the unit of measure type.
151 
152  \return The unit of measure type.
153  */
154  MeasureType getType() const;
155 
156  /*! \brief Returns true if this is a base unit; otherwise returns false. */
157  bool isBaseUnit() const;
158 
159  /*!
160  \brief Returns the base unit id from which this unit derives of.
161 
162  \return The base unit id from which this unit derives of.
163  */
164  const unsigned int getBaseUnitId() const;
165 
166  /*!
167  \brief Returns the conversion factors to convert the unit to its base unit.
168 
169  \param A To return the A factor in the conversion formula (output).
170  \param B To return the B factor in the conversion formula (output).
171  \param C To return the C factor in the conversion formula (output).
172  \param D To return the D factor in the conversion formula (output).
173 
174  \note If this is a base unit, the return values are A=1, B=0, C=0 and D=1.
175  */
176  void getConversionFactors(double& A, double& B, double& C, double& D) const;
177 
178  /*!
179  \brief Returns a multiplicative value to convert the unit to its base unit.
180 
181  The retuned value is calculated as (A + B)/(C + D) rounded to a double.
182 
183  \return A multiplicative value to convert the unit to its base unit.
184 
185  \note If this is a base unit, the returned value is 1.0.
186  */
187  double getConversionValue() const;
188 
189  /*!
190  \brief Returns the WKT description of a unit of measure.
191 
192  \return The WKT description of a unit of measure.
193  */
194  std::string getWKT() const;
195 
196  private:
197 
198  unsigned int m_id; //!< Unique identification number for a unit of measure.
199  std::string m_name; //!< unit of measure name according to SI.
200  std::string m_symbol; //!< Unit symbol.
201  MeasureType m_type; //!< Unit type of measure.
202  std::string m_description; //!< unit of measure description.
203 
204  unsigned int m_baseUnitId; //!< Unique identification number of the base unit to which a conversion operation is provided.
205 
206  double m_a;
207  double m_b;
208  double m_c;
209  double m_d;
210 
211  }; // end class
212 
213  typedef boost::shared_ptr<UnitOfMeasure> UnitOfMeasurePtr;
214  } // end namespace common
215 } // end namespace te
216 
217 #endif // __TERRALIB_COMMON_INTERNAL_UNITOFMEASURE_H
218 
Configuration flags for the TerraLib Common Runtime module.
unsigned int m_baseUnitId
Unique identification number of the base unit to which a conversion operation is provided.
std::string m_symbol
Unit symbol.
unsigned int m_id
Unique identification number for a unit of measure.
MeasureType m_type
Unit type of measure.
URI C++ Library.
#define TECOMMONEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:65
General enumerations.
boost::shared_ptr< UnitOfMeasure > UnitOfMeasurePtr
std::string m_description
unit of measure description.
MeasureType
Defines the possible types of unit of measurements.
Definition: Enums.h:76
A class to represent units of measure.
Definition: UnitOfMeasure.h:74
std::string m_name
unit of measure name according to SI.