SIQuantity

Declares the SIQuantity interface for representing and manipulating physical quantities.

SIQuantity provides an abstract interface for physical quantities, associating a value (of a specific element type) with a unit and dimensionality. The API is CoreFoundation-style, with explicit memory management and reference counting.

SIQuantity objects are immutable by default; use SIMutableQuantityRef for mutable variants.

This interface supports querying and manipulating the unit, dimensionality, and element type of a quantity, as well as type and dimensionality comparisons.

Author

Philip Grandinetti

Defines

kSINumberTypeInvalid

Enums

enum complexPart

Parts of a complex number.

Values:

enumerator kSIRealPart

Real part of complex number.

enumerator kSIImaginaryPart

Imaginary part of complex number.

enumerator kSIMagnitudePart

Magnitude part of complex number.

enumerator kSIArgumentPart

Argument part of complex number.

enum SINumberType

valid number types for SIQuantity.

Values:

enumerator kSINumberFloat32Type
enumerator kSINumberFloat64Type
enumerator kSINumberComplex64Type
enumerator kSINumberComplex128Type

Functions

SIUnitRef SIQuantityGetUnit(SIQuantityRef quantity)

Returns the quantity’s unit.

Parameters:

  • quantity – The quantity.

Returns:

A SIUnit object.

bool SIQuantitySetUnit(SIMutableQuantityRef quantity, SIUnitRef unit)

Sets the quantity’s unit.

Parameters:

  • quantity – The quantity.

  • unit – The unit.

OCStringRef SIQuantityCopyUnitSymbol(SIQuantityRef quantity)
SIDimensionalityRef SIQuantityGetUnitDimensionality(SIQuantityRef quantity)

Returns the quantity’s dimensionality.

Parameters:

  • quantity – The quantity.

Returns:

A SIDimensionality object.

SINumberType SIQuantityGetNumericType(SIQuantityRef quantity)

Returns the type used by a quantity to store its values.

Parameters:

  • quantity – The quantity.

Returns:

The numeric type. Possible values are kSINumberFloatType, kSINumberDoubleType, kSINumberFloatComplexType, and kSINumberDoubleComplexType.

int SIQuantityElementSize(SIQuantityRef quantity)

Returns size (in bytes) of a quantity element.

Parameters:

  • quantity – The quantity.

Returns:

The size.

bool SIQuantityHasNumericType(SIQuantityRef quantity, SINumberType numericType)

Tests if quantity has a specific numeric type.

Parameters:

  • quantity – The quantity.

  • numericType – The numeric type.

Returns:

True or false.

bool SIQuantityIsComplexType(SIQuantityRef theQuantity)

Tests if quantity has a complex element type.

Parameters:

  • theQuantity – The quantity.

Returns:

True or false.

bool SIQuantityHasDimensionality(SIQuantityRef quantity, SIDimensionalityRef theDimensionality)

Tests if quantity has a specific dimensionality.

Parameters:

  • quantity – The quantity.

  • theDimensionality – The dimensionality.

Returns:

True or false.

bool SIQuantityHasSameDimensionality(SIQuantityRef input1, SIQuantityRef input2)

Determines if two quantities have the same dimensionality exponents.

Parameters:

  • input1 – The first quantity.

  • input2 – The second quantity.

Returns:

True or false.

bool SIQuantityHasSameReducedDimensionality(SIQuantityRef input1, SIQuantityRef input2)

Determines if two quantities have the same reduced dimensionality exponents.

Parameters:

  • input1 – The first quantity.

  • input2 – The second quantity.

Returns:

True or false.

bool SIQuantityValidateMixedArrayForDimensionality(OCArrayRef array, SIDimensionalityRef dimensionality, OCStringRef *outError)

Validates that all elements in an array have compatible dimensionality.

Parameters:

  • array – Array containing OCNumber or SIScalar objects.

  • dimensionality – Target dimensionality to validate against.

  • outError – Pointer to store error message if validation fails.

Returns:

True if all elements have compatible dimensionality, false otherwise.

SINumberType SIQuantityLargerNumericType(SIQuantityRef input1, SIQuantityRef input2)

Returns larger numeric type for the two input quantities.

Parameters:

  • input1 – The first SIQuantity.

  • input2 – The second SIQuantity.

Returns:

The larger SINumberType of the two quantities.

SINumberType SIQuantitySmallerNumericType(SIQuantityRef input1, SIQuantityRef input2)

Returns smaller numeric type for the two input quantities.

Parameters:

  • input1 – The first SIQuantity.

  • input2 – The second SIQuantity.

Returns:

The smaller SINumberType of the two quantities.

SINumberType SIQuantityBestNumericType(SIQuantityRef input1, SIQuantityRef input2)

Returns the best numeric type for the two input quantities.

Returns the best numeric type for the two input quantities which loses no precision when the quantities are combined in any way: add, subtract, multiply, divide. Input numeric types and outputs are:

(float and float) => float

(float and double) => double

(float and float complex) => float complex

(float and double complex) => double complex

(double and double) => double

(double and float complex) => double complex

(double and double complex) => double complex

(float complex and float complex) => float complex

(float complex and double complex) => double complex

(double complex and double complex) => double complex

Parameters:

  • input1 – The first SIQuantity.

  • input2 – The second SIQuantity.

Returns:

The best SINumberType from the two quantities.