dip::Units class

Encapsulates the concepts of physical units, using SI units.

It is possible to multiply or divide units, and raise to arbitrary integer powers with the class method Power. To associate a magnitude to the units, see the class dip::PhysicalQuantity.

Note that radian (dip::Units::BaseUnits::ANGLE), though dimensionless, is treated as a specific unit here. Also, mass is measured in grams, rather than kilograms, because it simplifies writing prefixes (we presume the Kg won’t be used much in DIPlib…).

Prefixes are recorded with the dip::Units::BaseUnits::THOUSANDS value. It indicates how often to multiply by 103. Thus, a value of 1 here corresponds to the ‘k’ prefix, 3 with ‘G’, and -2 with ‘μ‘. Note that for ‘mm2’, the value for length is 2, and that for thousands is -2. If thousands were -1, the units would have to be formatted as ‘10-3 m2^’. dip::Units::AdjustThousands adjusts this power so that it can always be formatted with an SI prefix, returning a magnitude that can be handled elsewhere (the dip::PhysicalQuantity class uses this feature).

The dip::Units::BaseUnits::PIXEL value is for non-physical quantities, which typically represent a magnitude with unknown or arbitrary units. For example, dip::MeasurementTool uses it when an image has no pixel size. dip::Units::IsPhysical tests whether there are pixel units present or not.

Constructors, destructors, assignment and conversion operators

Units() defaulted constexpr noexcept
A default-constructed Units is dimensionless.
Units(dip::Units::BaseUnits bu, dip::sint8 power = 1) explicit constexpr
Construct a Units for a specific unit.
Units(dip::String const& string)
Construct a Units from a string representation of units. The string representation should be as produced by dip::Units::String, except that ‘u’ and ‘μ’ are synonyms.

Enums

enum class BaseUnits: uint8{ THOUSANDS, LENGTH, MASS, TIME, CURRENT, TEMPERATURE, LUMINOUSINTENSITY, ANGLE, PIXEL }
These are the base units for the SI system.

Functions

auto Power(dip::sint8 power) -> dip::Units& constexpr
Elevates this to the power p.
auto HasSameDimensions(dip::Units const& other) const -> bool constexpr
Compares two units objects. This differs from the == operator in that km and μm test equal. That is, the SI prefix is ignored.
auto IsDimensionless() const -> bool constexpr
Test to see if the units are dimensionless (has no units).
auto IsPhysical() const -> bool constexpr
Test to see if the units are physical. Units that involve pixels are not physical, and neither are dimensionless units.
auto AdjustThousands(dip::sint power = 0) -> dip::sint constexpr
Adjusts the power of the thousands, so that we can use an SI prefix with the first unit to be written out.
auto Thousands() const -> dip::sint constexpr
Returns the power associated with dip::Units::BaseUnits::THOUSANDS, corresponding to a given SI prefix.
auto String() const -> dip::String
Cast physical units to a string representation, using only ASCII characters.
auto StringUnicode() const -> dip::String
Cast physical units to a string representation, using Unicode characters (UTF-8 encoded).
void FromString(dip::String const& string)
Sets this to the units represented by the string. This function recognizes more strings than what the constructor recognizes.
void swap(dip::Units& other) noexcept
Swaps the values of this and other.
static auto Nano() -> dip::Units constexpr
Dimensionless nano magnitude (n)
static auto Micro() -> dip::Units constexpr
Dimensionless micro magnitude (μ)
static auto Milli() -> dip::Units constexpr
Dimensionless milli magnitude (m)
static auto Kilo() -> dip::Units constexpr
Dimensionless kilo magnitude (k)
static auto Mega() -> dip::Units constexpr
Dimensionless mega magnitude (M)
static auto Giga() -> dip::Units constexpr
Dimensionless giga magnitude (G)
static auto Meter() -> dip::Units constexpr
Meter units (m)
static auto SquareMeter() -> dip::Units constexpr
Square meter units (m2)
static auto CubicMeter() -> dip::Units constexpr
Cubic meter units (m3)
static auto Nanometer() -> dip::Units constexpr
Nanometer units (nm)
static auto Micrometer() -> dip::Units constexpr
Micrometer units (μm)
static auto Millimeter() -> dip::Units constexpr
Millimeter units (mm)
static auto Kilometer() -> dip::Units constexpr
Kilometer units (km)
static auto SquareMicrometer() -> dip::Units constexpr
Square micrometer units (μm2)
static auto SquareMillimeter() -> dip::Units constexpr
Square millimeter units (mm2)
static auto CubicMillimeter() -> dip::Units constexpr
Cubic millimeter units (mm3)
static auto Second() -> dip::Units constexpr
Second units (s)
static auto Millisecond() -> dip::Units constexpr
Millisecond units (ms)
static auto Hertz() -> dip::Units constexpr
Hertz units (s-1)
static auto Kilohertz() -> dip::Units constexpr
Kilohertz units (ms-1)
static auto Megahertz() -> dip::Units constexpr
Megahertz units (μs-1)
static auto Gigahertz() -> dip::Units constexpr
Gigahertz units (ns-1)
static auto Radian() -> dip::Units constexpr
Radian units (rad)
static auto Pixel() -> dip::Units constexpr
Pixel units (px)
static auto SquarePixel() -> dip::Units constexpr
Square pixel units (px2)
static auto CubicPixel() -> dip::Units constexpr
Cubic pixel units (px3)

Operators

auto operator*=(dip::Units const& other) -> dip::Units& constexpr
Multiplies two units objects.
auto operator/=(dip::Units const& other) -> dip::Units& constexpr
Divides two units objects.
auto operator==(dip::Units const& rhs) const -> bool constexpr
Compares two units objects.
auto operator!=(dip::Units const& rhs) const -> bool constexpr
Compares two units objects.
auto operator bool() const -> bool explicit constexpr
Units tests false if they’re dimensionless.

Enum documentation

enum class BaseUnits: uint8

These are the base units for the SI system.

Enumerators
THOUSANDS = 0 prefix
LENGTH = 1 m
MASS = 2 g (should be Kg, but this is easier when working with prefixes)
TIME = 3 s
CURRENT = 4 A
TEMPERATURE = 5 K
LUMINOUSINTENSITY = 6 cd
ANGLE = 7 rad (though really dimensionless)
PIXEL = 8 px (units to use when the image has no dimension information)

Function documentation

dip::sint AdjustThousands(dip::sint power = 0) constexpr

Adjusts the power of the thousands, so that we can use an SI prefix with the first unit to be written out.

The return value is a number of thousands, which are taken out of the units and should be handled by the caller. The input power is the number of thousands that the caller would like to include into the units.

dip::String String() const

Cast physical units to a string representation, using only ASCII characters.

No attempt is (yet?) made to produce derived SI units or to translate to different units.

Calling the dip::Units::Units constructor on the output of this function yields this.

dip::String StringUnicode() const

Cast physical units to a string representation, using Unicode characters (UTF-8 encoded).

If Unicode support was disabled during compilation, this function does the same as dip::Units::String.

No attempt is (yet?) made to produce derived SI units or to translate to different units.

Calling the dip::Units::Units constructor on the output of this function yields this.