SIScalar

Interface for representing and manipulating scalar quantities in the SI system.

Convert between SIScalarRef and cJSON representations.

The SIScalar API provides a comprehensive interface for scalar physical quantities in the International System of Units (SI), supporting both real and complex values.

Functions

OCTypeID SIScalarGetTypeID(void)

Returns the unique type identifier for SIScalar objects.

SIScalarRef SIScalarCreateCopy(SIScalarRef theScalar)

Creates a deep copy of a SIScalar object.

SIMutableScalarRef SIScalarCreateMutableCopy(SIScalarRef theScalar)

Creates a mutable deep copy of a SIScalar object.

cJSON *SIScalarCopyAsJSON(SIScalarRef scalar, bool typed, OCStringRef *outError)

SIScalarRef SIScalarCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an SIScalar from a cJSON object.

Parameters:

• json – A cJSON object that can be either:

  • Typed format: {“type”: “SIScalar”, “value”: {…}}

  • Untyped format: string representation

Returns:

An SIScalarRef, or NULL on failure. The caller is responsible for releasing the returned scalar.

SIScalarRef SIScalarCreateWithFloat(float input_value, SIUnitRef unit)

Creates an immutable SIScalar from a float value and SI unit.

SIMutableScalarRef SIScalarCreateMutableWithFloat(float input_value, SIUnitRef unit)

Creates a mutable SIScalar from a float value and SI unit.

SIScalarRef SIScalarCreateWithDouble(double input_value, SIUnitRef unit)

Creates an immutable SIScalar from a double value and SI unit.

SIMutableScalarRef SIScalarCreateMutableWithDouble(double input_value, SIUnitRef unit)

Creates a mutable SIScalar from a double value and SI unit.

SIScalarRef SIScalarCreateWithFloatComplex(float complex input_value, SIUnitRef unit)

Creates an immutable SIScalar from a float complex value and SI unit.

SIMutableScalarRef SIScalarCreateMutableWithFloatComplex(float complex input_value, SIUnitRef unit)

Creates a mutable SIScalar from a float complex value and SI unit.

SIScalarRef SIScalarCreateWithDoubleComplex(double complex input_value, SIUnitRef unit)

Creates an immutable SIScalar from a double complex value and SI unit.

SIMutableScalarRef SIScalarCreateMutableWithDoubleComplex(double complex input_value, SIUnitRef unit)

Creates a mutable SIScalar from a double complex value and SI unit.

SIScalarRef SIScalarCreateWithOCNumber(OCNumberRef number, SIUnitRef unit)

Creates an immutable SIScalar from an OCNumber value and SI unit.

SIScalarRef SIScalarCreateWithStringContainingSingleUnitFromLibrary(OCStringRef theString)

Creates a scalar from a string containing a single unit name.

OCArrayRef SIScalarCreateArrayFromMixedTypeArray(OCArrayRef numbers, OCStringRef *outError)

Creates an array of SIScalar objects from an array of OCNumber or SIScalar objects.

OCArrayRef SIScalarCreateArrayFromNumberArray(const void *values, OCNumberType type, OCIndex count, OCStringRef *outError)

Creates an array of SIScalar objects from a typed array of numeric values.

impl_SINumber SIScalarGetValue(SIScalarRef theScalar)

Retrieves the numeric value of a SIScalar instance.

void SIScalarSetFloatValue(SIMutableScalarRef theScalar, float value)

Sets the numeric value of a mutable scalar to a float.

void SIScalarSetDoubleValue(SIMutableScalarRef theScalar, double value)

Sets the numeric value of a mutable scalar to a double.

void SIScalarSetFloatComplexValue(SIMutableScalarRef theScalar, float complex value)

Sets the numeric value of a mutable scalar to a float complex.

void SIScalarSetDoubleComplexValue(SIMutableScalarRef theScalar, double complex value)

Sets the numeric value of a mutable scalar to a double complex.

void SIScalarSetNumericType(SIMutableScalarRef theScalar, SINumberType numericType)

Sets the numeric type indicator for a mutable scalar.

float SIScalarFloatValue(SIScalarRef theScalar)

Retrieves the scalar’s value as a float.

double SIScalarDoubleValue(SIScalarRef theScalar)

Retrieves the scalar’s value as a double.

float complex SIScalarFloatComplexValue(SIScalarRef theScalar)

Retrieves the scalar’s value as a float complex.

double complex SIScalarDoubleComplexValue(SIScalarRef theScalar)

Retrieves the scalar’s value as a double complex.

double SIScalarMagnitudeValue(SIScalarRef theScalar)

Computes the magnitude (absolute value) of the scalar.

double SIScalarArgumentValue(SIScalarRef theScalar)

Computes the argument (phase angle) of the scalar in radians.

float SIScalarFloatValueInUnit(SIScalarRef theScalar, SIUnitRef unit, bool *success)

Converts the scalar’s value to the specified unit and returns as float.

double SIScalarDoubleValueInUnit(SIScalarRef theScalar, SIUnitRef unit, bool *success)

Converts the scalar’s value to the specified unit and returns as double.

float complex SIScalarFloatComplexValueInUnit(SIScalarRef theScalar, SIUnitRef unit, bool *success)

Converts the scalar’s value to the specified unit and returns as float complex.

double complex SIScalarDoubleComplexValueInUnit(SIScalarRef theScalar, SIUnitRef unit, bool *success)

Converts the scalar’s value to the specified unit and returns as double complex.

float SIScalarFloatValueInCoherentUnit(SIScalarRef theScalar)

Converts the scalar’s value to its coherent SI unit and returns as float.

double SIScalarDoubleValueInCoherentUnit(SIScalarRef theScalar)

Converts the scalar’s value to its coherent SI unit and returns as double.

float complex SIScalarFloatComplexValueInCoherentUnit(SIScalarRef theScalar)

Converts the scalar’s value to its coherent SI unit and returns as float complex.

double complex SIScalarDoubleComplexValueInCoherentUnit(SIScalarRef theScalar)

Converts the scalar’s value to its coherent SI unit and returns as double complex.

SIScalarRef SIScalarCreateByConvertingToNumberType(SIScalarRef theScalar, SINumberType numericType)

Converts the numeric representation to a specified numeric type.

bool SIScalarTakeComplexPart(SIMutableScalarRef theScalar, complexPart part)

Replace the numeric value of a mutable scalar with one of its complex components.

SIScalarRef SIScalarCreateByTakingComplexPart(SIScalarRef theScalar, complexPart part)

Create a new SIScalar from a specified complex component of an existing scalar.

SIScalarRef SIScalarCreateFromExpression(OCStringRef string, OCStringRef *error)

Parse a numeric string with unit and create a SIScalar.

SIScalarRef SIScalarCreateByReducingUnit(SIScalarRef theScalar)

Create a new SIScalar with its unit exponents reduced to lowest integers.

bool SIScalarReduceUnit(SIMutableScalarRef theScalar)

Reduce a mutable scalar’s unit exponents in place to lowest integers.

bool SIScalarConvertToUnit(SIMutableScalarRef theScalar, SIUnitRef unit, OCStringRef *error)

Convert a mutable scalar’s value and unit to another compatible unit.

SIScalarRef SIScalarCreateByConvertingToUnit(SIScalarRef theScalar, SIUnitRef unit, OCStringRef *error)

Create a new SIScalar by converting to another unit of the same dimensionality.

bool SIScalarConvertToUnitWithString(SIMutableScalarRef theScalar, OCStringRef unitString, OCStringRef *error)

Create a new SIScalar by converting to another unit (given its string representation) of the same dimensionality.

SIScalarRef SIScalarCreateByConvertingToUnitWithString(SIScalarRef theScalar, OCStringRef unitString, OCStringRef *error)

Convert a mutable scalar’s value and unit to another compatible unit given the unit string.

bool SIScalarConvertToCoherentUnit(SIMutableScalarRef theScalar, OCStringRef *error)

Convert a mutable scalar to its coherent SI unit in place.

SIScalarRef SIScalarCreateByConvertingToCoherentUnit(SIScalarRef theScalar, OCStringRef *error)

Create a new SIScalar by converting to its coherent SI unit.

SIScalarRef SIScalarCreateByAdding(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by adding two scalars.

bool SIScalarAdd(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Adds another scalar into a mutable scalar in place.

SIScalarRef SIScalarCreateBySubtracting(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by subtracting one scalar from another.

bool SIScalarSubtract(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Subtracts a scalar from a mutable scalar in place.

SIScalarRef SIScalarCreateByMultiplyingWithoutReducingUnit(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by multiplying two scalars without simplifying the unit.

bool SIScalarMultiplyWithoutReducingUnit(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Multiplies a mutable scalar by another scalar without simplifying the unit.

SIScalarRef SIScalarCreateByMultiplying(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by multiplying two scalars.

bool SIScalarMultiply(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Multiplies a mutable scalar by another scalar in place.

SIScalarRef SIScalarCreateByDividingWithoutReducingUnit(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by dividing two scalars without simplifying the unit.

bool SIScalarDivideWithoutReducingUnit(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Divides a mutable scalar by another scalar in place without simplifying the unit.

SIScalarRef SIScalarCreateByDividing(SIScalarRef input1, SIScalarRef input2, OCStringRef *error)

Create a new SIScalar by dividing two scalars.

bool SIScalarDivide(SIMutableScalarRef target, SIScalarRef input2, OCStringRef *error)

Divides a mutable scalar by another scalar in place.

SIScalarRef SIScalarCreateByRaisingToPowerWithoutReducingUnit(SIScalarRef theScalar, int power, OCStringRef *error)

Create a new SIScalar by raising a scalar to a power without simplifying the unit.

bool SIScalarRaiseToAPowerWithoutReducingUnit(SIMutableScalarRef theScalar, int power, OCStringRef *error)

Raises a mutable scalar to a power without simplifying the unit in place.

SIScalarRef SIScalarCreateByRaisingToPower(SIScalarRef theScalar, int power, OCStringRef *error)

Create a new SIScalar by raising a scalar to a power.

bool SIScalarRaiseToAPower(SIMutableScalarRef theScalar, int power, OCStringRef *error)

Raises a mutable scalar to a power in place.

SIScalarRef SIScalarCreateByTakingAbsoluteValue(SIScalarRef theScalar, OCStringRef *error)

Create a new SIScalar by taking the absolute value.

bool SIScalarTakeAbsoluteValue(SIMutableScalarRef theScalar, OCStringRef *error)

Replaces a mutable scalar’s value with its absolute value in place.

SIScalarRef SIScalarCreateByGammaFunctionWithoutReducingUnit(SIScalarRef theScalar, OCStringRef *error)

Create a new SIScalar by applying the Gamma function without simplifying the unit.

SIScalarRef SIScalarCreateByTakingNthRoot(SIScalarRef theScalar, uint8_t root, OCStringRef *error)

Create a new SIScalar by taking the Nth root.

bool SIScalarTakeNthRoot(SIMutableScalarRef theScalar, uint8_t root, OCStringRef *error)

Replaces a mutable scalar’s value with its Nth root in place.

bool SIScalarTakeLog10(SIMutableScalarRef theScalar, OCStringRef *error)

Replaces a mutable scalar’s value with its base-10 logarithm in place.

SIScalarRef SIScalarCreateByZeroingPart(SIScalarRef theScalar, complexPart part)

Create a new SIScalar by zeroing a specified component of its value.

bool SIScalarZeroPart(SIMutableScalarRef theScalar, complexPart part)

Zeroes a specified component of a mutable scalar’s value in place.

bool SIScalarMultiplyByDimensionlessRealConstant(SIMutableScalarRef theScalar, double constant)

Multiplies a mutable scalar by a dimensionless real constant in place.

SIScalarRef SIScalarCreateByMultiplyingByDimensionlessRealConstant(SIScalarRef theScalar, double constant)

Create a new SIScalar by multiplying by a dimensionless real constant.

SIScalarRef SIScalarCreateByMultiplyingByDimensionlessComplexConstant(SIScalarRef theScalar, double complex constant)

Create a new SIScalar by multiplying by a dimensionless complex constant.

bool SIScalarMultiplyByDimensionlessComplexConstant(SIMutableScalarRef theScalar, double complex constant)

Multiplies a mutable scalar by a dimensionless complex constant in place.

SIScalarRef SIScalarCreateByConjugation(SIScalarRef theScalar)

Create a new SIScalar by taking the complex conjugate.

bool SIScalarConjugate(SIMutableScalarRef theScalar)

Conjugates a mutable scalar in place.

void SIScalarShow(SIScalarRef theScalar)

Prints a concise description of a scalar to the console.

OCStringRef SIScalarCreateStringValue(SIScalarRef theScalar)

Creates a string representation of a scalar including value and unit.

OCStringRef SIScalarCreateNumericStringValue(SIScalarRef theScalar)

Creates a string representation of only the numeric part of a scalar.

OCStringRef SIScalarCreateStringValueForPart(SIScalarRef theScalar, complexPart thePart)

Creates a string representation of a specific component of a scalar.

OCStringRef SIScalarCopyUnitSymbol(SIScalarRef theScalar)

Creates a string representation of only the unit of a scalar.

OCStringRef SIScalarCreateStringValueWithFormat(SIScalarRef theScalar, OCStringRef format)

Creates a formatted string representation of a scalar using a custom format.

OCStringRef SIScalarCreateNumericStringValueWithFormat(SIScalarRef theScalar, OCStringRef format)

Creates a formatted string of the numeric part using a custom format.

void SIScalarAddToArrayAsStringValue(SIScalarRef theScalar, OCMutableArrayRef array)

Appends the scalar’s value and unit as a string to a mutable array.

bool SIScalarIsReal(SIScalarRef theScalar)

Determines whether a scalar is a real number (imaginary part is zero).

bool SIScalarIsImaginary(SIScalarRef theScalar)

Determines whether a scalar is purely imaginary.

bool SIScalarIsComplex(SIScalarRef theScalar)

Determines whether a scalar has a non-zero imaginary component.

bool SIScalarIsZero(SIScalarRef theScalar)

Determines whether a scalar’s numeric value is exactly zero.

bool SIScalarIsInfinite(SIScalarRef theScalar)

Determines whether a scalar’s numeric value is infinite (±∞).

bool SIScalarIsRealNonNegativeInteger(SIScalarRef theScalar)

Determines whether a scalar is a real, non-negative integer.

bool SIScalarValidateProposedStringValue(SIScalarRef theScalar, OCStringRef proposedStringValue, OCStringRef *error)

Validates whether a proposed string represents a scalar with the same dimensionality.

bool SIScalarEqual(SIScalarRef input1, SIScalarRef input2)

Tests whether two scalars are equal in value, unit, and metadata.

OCComparisonResult SIScalarCompare(SIScalarRef scalar, SIScalarRef otherScalar)

Compares two scalars and returns an ordering result.

OCComparisonResult SIScalarCompareReduced(SIScalarRef theScalar, SIScalarRef theOtherScalar)

Compares two scalars in reduced units and returns an ordering result.

OCComparisonResult SIScalarCompareLoose(SIScalarRef theScalar, SIScalarRef theOtherScalar)

Performs a “loose” comparison between two scalars and returns an ordering result.

OCComparisonResult SIScalarCompareLooseReduced(SIScalarRef theScalar, SIScalarRef theOtherScalar)

Performs a “loose” comparison between two scalars in reduced units and returns an ordering result.

OCStringRef SIScalarCopyFormattingDescription(SIScalarRef scalar)

bool SIScalarBestConversionForQuantity(SIMutableScalarRef theScalar, OCStringRef quantity, OCStringRef *outError)

Pick the “best” SI unit for this scalar (so the mantissa is ~1-1000)

Parameters:

• theScalar – mutable scalar to rescale in-place

• quantity – a quantity name (e.g. “time”, “length”, …)

• outError – on failure, set to an OCStringRef describing the problem

Returns:

true on success, false (and *outError) otherwise

OCArrayRef SIScalarCreateArrayOfConversionQuantitiesScalarsAndStringValues(SIScalarRef theScalar, OCStringRef quantity, OCStringRef *outError)

For a given scalar, return an array of alternate-unit scalars and (optionally) string splits.

Parameters:

• theScalar – the input scalar

• quantity – if non-NULL, only units for that quantity

• outError – on failure, set to an OCStringRef

Returns:

an OCArray of SIScalarRef and OCStringRef entries

OCArrayRef SIScalarCreateArrayOfConversionQuantitiesAndUnits(SIScalarRef theScalar, OCStringRef quantity, OCStringRef *outError)

Like above, but just returns the units themselves.

Parameters:

• theScalar – the input scalar

• quantity – if non-NULL, only units for that quantity

• outError – on failure, set to an OCStringRef

Returns:

an OCArray of SIUnitRef entries