Physical dimensions module
#include "diplib.h"
dip::Units class

Encapsulates the concepts of physical units, using SI units.

Reference

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 10³. Thus, a value of 1 here corresponds to the ‘k’ prefix, 3 with ‘G’, and -2 with ‘μ‘. Note that for ‘mm^{2’, 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 (m²)
static auto CubicMeter() -> dip::Units constexpr: Cubic meter units (m³)
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 (μm²)
static auto SquareMillimeter() -> dip::Units constexpr: Square millimeter units (mm²)
static auto CubicMillimeter() -> dip::Units constexpr: Cubic millimeter units (mm³)
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 (px²)
static auto CubicPixel() -> dip::Units constexpr: Cubic pixel units (px³)

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.