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²’, 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 m²’. 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: These are the base units for the SI system. more...

Functions

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. more...
static auto CubicMeter() -> dip::Units constexpr: Cubic meter units (m³)
static auto CubicMillimeter() -> dip::Units constexpr: Cubic millimeter units (mm³)
static auto CubicPixel() -> dip::Units constexpr: Cubic pixel units (px³)
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.
static auto Giga() -> dip::Units constexpr: Dimensionless giga magnitude (G)
static auto Gigahertz() -> dip::Units constexpr: Gigahertz units (ns^-1)
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.
static auto Hertz() -> dip::Units constexpr: Hertz units (s^-1)
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.
static auto Kilo() -> dip::Units constexpr: Dimensionless kilo magnitude (k)
static auto Kilohertz() -> dip::Units constexpr: Kilohertz units (ms^-1)
static auto Kilometer() -> dip::Units constexpr: Kilometer units (km)
static auto Mega() -> dip::Units constexpr: Dimensionless mega magnitude (M)
static auto Megahertz() -> dip::Units constexpr: Megahertz units (μs^-1)
static auto Meter() -> dip::Units constexpr: Meter units (m)
static auto Micro() -> dip::Units constexpr: Dimensionless micro magnitude (μ)
static auto Micrometer() -> dip::Units constexpr: Micrometer units (μm)
static auto Milli() -> dip::Units constexpr: Dimensionless milli magnitude (m)
static auto Millimeter() -> dip::Units constexpr: Millimeter units (mm)
static auto Millisecond() -> dip::Units constexpr: Millisecond units (ms)
static auto Nano() -> dip::Units constexpr: Dimensionless nano magnitude (n)
static auto Nanometer() -> dip::Units constexpr: Nanometer units (nm)
static auto Pixel() -> dip::Units constexpr: Pixel units (px)
auto Power(dip::sint8 power) -> dip::Units& constexpr: Elevates this to the power p.
static auto Radian() -> dip::Units constexpr: Radian units (rad)
static auto Second() -> dip::Units constexpr: Second units (s)
static auto SquareMeter() -> dip::Units constexpr: Square meter units (m²)
static auto SquareMicrometer() -> dip::Units constexpr: Square micrometer units (μm²)
static auto SquareMillimeter() -> dip::Units constexpr: Square millimeter units (mm²)
static auto SquarePixel() -> dip::Units constexpr: Square pixel units (px²)
auto String() const -> dip::String: Cast physical units to a string representation, using only ASCII characters. more...
auto StringUnicode() const -> dip::String: Cast physical units to a string representation, using Unicode characters (UTF-8 encoded). more...
void swap(dip::Units& other) noexcept: Swaps the values of this and other.
auto Thousands() const -> dip::sint constexpr: Returns the power associated with dip::Units::BaseUnits::THOUSANDS, corresponding to a given SI prefix.

Operators

auto operator bool() const -> bool explicit constexpr: Units tests false if they’re dimensionless.
auto operator!=(dip::Units const& rhs) const -> bool constexpr: Compares two units objects.
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.

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

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.

dip::Units& Power( dip::sint8 power) constexpr

Elevates this to the power p.

bool HasSameDimensions( dip::Units const& other) const constexpr

Compares two units objects. This differs from the == operator in that km and μm test equal. That is, the SI prefix is ignored.

bool IsDimensionless( ) const constexpr

Test to see if the units are dimensionless (has no units).

bool IsPhysical( ) const constexpr

Test to see if the units are physical. Units that involve pixels are not physical, and neither are dimensionless units.

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::sint Thousands( ) const constexpr

Returns the power associated with dip::Units::BaseUnits::THOUSANDS, corresponding to a given SI prefix.

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.

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 dip::Units Nano( ) constexpr

Dimensionless nano magnitude (n)

static dip::Units Micro( ) constexpr

Dimensionless micro magnitude (μ)

static dip::Units Milli( ) constexpr

Dimensionless milli magnitude (m)

static dip::Units Kilo( ) constexpr

Dimensionless kilo magnitude (k)

static dip::Units Mega( ) constexpr

Dimensionless mega magnitude (M)

static dip::Units Giga( ) constexpr

Dimensionless giga magnitude (G)

static dip::Units Meter( ) constexpr

Meter units (m)

static dip::Units SquareMeter( ) constexpr

Square meter units (m²)

static dip::Units CubicMeter( ) constexpr

Cubic meter units (m³)

static dip::Units Nanometer( ) constexpr

Nanometer units (nm)

static dip::Units Micrometer( ) constexpr

Micrometer units (μm)

static dip::Units Millimeter( ) constexpr

Millimeter units (mm)

static dip::Units Kilometer( ) constexpr

Kilometer units (km)

static dip::Units SquareMicrometer( ) constexpr

Square micrometer units (μm²)

static dip::Units SquareMillimeter( ) constexpr

Square millimeter units (mm²)

static dip::Units CubicMillimeter( ) constexpr

Cubic millimeter units (mm³)

static dip::Units Second( ) constexpr

Second units (s)

static dip::Units Millisecond( ) constexpr

Millisecond units (ms)

static dip::Units Hertz( ) constexpr

Hertz units (s^-1)

static dip::Units Kilohertz( ) constexpr

Kilohertz units (ms^-1)

static dip::Units Megahertz( ) constexpr

Megahertz units (μs^-1)

static dip::Units Gigahertz( ) constexpr

Gigahertz units (ns^-1)

static dip::Units Radian( ) constexpr

Radian units (rad)

static dip::Units Pixel( ) constexpr

Pixel units (px)

static dip::Units SquarePixel( ) constexpr

Square pixel units (px²)

static dip::Units CubicPixel( ) constexpr

Cubic pixel units (px³)

dip::Units& operator*=( dip::Units const& other) constexpr

Multiplies two units objects.

dip::Units& operator/=( dip::Units const& other) constexpr

Divides two units objects.

bool operator==( dip::Units const& rhs) const constexpr

Compares two units objects.

bool operator!=( dip::Units const& rhs) const constexpr