SIUnit

Interface for defining, manipulating, and comparing SI and derived units.

The SIUnit API provides a comprehensive, type-safe interface for immutable physical unit definitions in the International System of Units (SI), including support for both SI base units and coherent derived units, as well as common non-SI units.

Functions

OCTypeID SIUnitGetTypeID(void)

SIUnitRef SIUnitCoherentUnitFromDimensionality(SIDimensionalityRef dimensionality)

SIUnitRef SIUnitDimensionlessAndUnderived(void)

SIDimensionalityRef SIUnitGetDimensionality(SIUnitRef theUnit)

Gets the physical dimensionality for a unit.

double SIUnitGetScaleToCoherentSI(SIUnitRef theUnit)

double SIUnitScaleToCoherentSIUnit(SIUnitRef theUnit)

OCStringRef SIUnitCopySymbol(SIUnitRef theUnit)

OCStringRef SIUnitCopyName(SIUnitRef theUnit)

OCStringRef SIUnitCopyPluralName(SIUnitRef theUnit)

cJSON *SIUnitCopyAsJSON(SIUnitRef unit, bool typed, OCStringRef *outError)

SIUnitRef SIUnitFromJSON(cJSON *json, OCStringRef *outError)

Creates an SIUnit from a cJSON object.

Parameters:

• json – A cJSON object that can be either:

  • Typed format: {“type”: “SIUnit”, “value”: “symbol”}

  • Untyped format: detailed JSON with dimensionality, scale, etc.

Returns:

An SIUnitRef, or NULL on failure. The returned object is a singleton and must not be released.

bool SIUnitEqual(SIUnitRef theUnit1, SIUnitRef theUnit2)

bool SIUnitIsSIUnit(SIUnitRef theUnit)

bool SIUnitIsCGSUnit(SIUnitRef theUnit)

bool SIUnitIsImperialUnit(SIUnitRef theUnit)

bool SIUnitIsAtomicUnit(SIUnitRef theUnit)

bool SIUnitIsPlanckUnit(SIUnitRef theUnit)

bool SIUnitIsConstant(SIUnitRef theUnit)

bool SIUnitAreEquivalentUnits(SIUnitRef theUnit1, SIUnitRef theUnit2)

bool SIUnitIsCoherentUnit(SIUnitRef theUnit)

bool SIUnitIsDimensionless(SIUnitRef theUnit)

double SIUnitConversion(SIUnitRef initialUnit, SIUnitRef finalUnit)

void SIUnitLibrarySetDefaultVolumeSystem(SIVolumeSystem system)

SIVolumeSystem SIUnitLibraryGetDefaultVolumeSystem(void)

void SIUnitLibrarySetImperialVolumes(bool value)

bool SIUnitLibraryGetImperialVolumes(void)

void SIUnitLibrariesShutdown(void)

OCArrayRef SIUnitCreateArrayOfUnitsForQuantity(OCStringRef quantity)

OCArrayRef SIUnitCreateArrayOfUnitsForDimensionality(SIDimensionalityRef theDim)

OCArrayRef SIUnitCreateArrayOfUnitsForSameReducedDimensionality(SIDimensionalityRef theDim)

OCArrayRef SIUnitCreateArrayOfConversionUnits(SIUnitRef theUnit)

OCArrayRef SIUnitCreateArrayOfEquivalentUnits(SIUnitRef theUnit)

OCMutableArrayRef SIUnitGetTokenSymbolsLib(void)

SIUnitRef SIUnitWithSymbol(OCStringRef symbol)

SIUnitRef SIUnitFindWithName(OCStringRef input)

SIUnitRef SIUnitFindEquivalentUnitWithShortestSymbol(SIUnitRef theUnit)

SIUnitRef SIUnitByReducing(SIUnitRef theUnit, double *unit_multiplier)

OCStringRef SIUnitCreateQuantityNameGuess(SIUnitRef theUnit)

SIUnitRef SIUnitByRaisingToPowerWithoutReducing(SIUnitRef input, int power, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByRaisingToPower(SIUnitRef input, int power, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByMultiplyingWithoutReducing(SIUnitRef theUnit1, SIUnitRef theUnit2, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByMultiplying(SIUnitRef theUnit1, SIUnitRef theUnit2, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByDividingWithoutReducing(SIUnitRef theUnit1, SIUnitRef theUnit2, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByDividing(SIUnitRef theUnit1, SIUnitRef theUnit2, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitByTakingNthRoot(SIUnitRef theUnit, int root, double *unit_multiplier, OCStringRef *error)

SIUnitRef SIUnitFromExpression(OCStringRef expression, double *unit_multiplier, OCStringRef *error)

OCMutableStringRef SIUnitCreateNormalizedExpression(OCStringRef expression)

Temporary normalization function for existing parser compatibility. TODO: Implement proper Unicode normalization.

bool SIUnitAreExpressionsEquivalent(OCStringRef expr1, OCStringRef expr2)

Temporary function for expression equivalence checking. TODO: Implement proper expression equivalence checking.

OCStringRef SIUnitCreateCleanedExpression(OCStringRef expression)

Creates a cleaned and normalized unit expression by grouping and sorting terms.

This function takes a unit expression string and returns a cleaned version where:

• Unicode characters are normalized

• Identical unit symbols are grouped together (powers combined)

• Terms are sorted alphabetically

• Expression is formatted in a canonical form

Unlike SIUnitCreateCleanedAndReducedExpression, this function does NOT perform algebraic cancellation between numerator and denominator terms.

Examples:

• ”m*kg*m” → “kg•m^2”

• ”kg*m/s/s” → “kg•m/s^2”

• ”m/kg*s” → “m•s/kg”

Note

The caller is responsible for releasing the returned string with OCRelease()

Parameters:

• expression – The input unit expression string to clean

Returns:

A cleaned unit expression string, or NULL on error

OCStringRef SIUnitCreateCleanedAndReducedExpression(OCStringRef expression)

Creates a cleaned, normalized, and algebraically reduced unit expression.

This function performs all the operations of SIUnitCreateCleanedExpression plus:

• Algebraic cancellation of identical terms between numerator and denominator

• Simplification to the most reduced form

Examples:

• ”m*kg/m” → “kg”

• ”m^2*s/m/s” → “m”

• ”kg*m*s^2/kg/m” → “s^2”

Note

The caller is responsible for releasing the returned string with OCRelease()

Parameters:

• expression – The input unit expression string to clean and reduce

Returns:

A cleaned and reduced unit expression string, or NULL on error

int SIUnitCountTokenSymbols(OCStringRef cleanedExpression)

OCMutableDictionaryRef SIUnitGetUnitsDictionaryLib(void)