OCNumber

group OCNumber

Numerical value representation using OCType-compatible objects.

Note

Ownership follows CoreFoundation conventions: The caller owns any OCNumberRef returned from functions with “Create” in the name, and must call OCRelease() when done.

Convenience Constructors

Create OCNumberRefs for native types.

OCNumberRef OCNumberCreateWithUInt8(uint8_t value)
OCNumberRef OCNumberCreateWithUInt16(uint16_t value)
OCNumberRef OCNumberCreateWithUInt32(uint32_t value)
OCNumberRef OCNumberCreateWithUInt64(unsigned long value)
OCNumberRef OCNumberCreateWithSInt8(int8_t value)
OCNumberRef OCNumberCreateWithSInt16(int16_t value)
OCNumberRef OCNumberCreateWithSInt32(int32_t value)
OCNumberRef OCNumberCreateWithSInt64(int64_t value)
OCNumberRef OCNumberCreateWithInt(int value)
OCNumberRef OCNumberCreateWithLong(long value)
OCNumberRef OCNumberCreateWithOCIndex(OCIndex index)
OCNumberRef OCNumberCreateWithFloat(float value)
OCNumberRef OCNumberCreateWithDouble(double value)
OCNumberRef OCNumberCreateWithFloatComplex(float _Complex value)
OCNumberRef OCNumberCreateWithDoubleComplex(double _Complex value)

Try-get Accessors

Functions to read back C values if type matches.

bool OCNumberTryGetUInt8(OCNumberRef n, uint8_t *out)

Try extract uint8_t.

bool OCNumberTryGetSInt8(OCNumberRef n, int8_t *out)

Try extract int8_t.

bool OCNumberTryGetUInt16(OCNumberRef n, uint16_t *out)

Try extract uint16_t.

bool OCNumberTryGetSInt16(OCNumberRef n, int16_t *out)

Try extract int16_t.

bool OCNumberTryGetUInt32(OCNumberRef n, uint32_t *out)

Try extract uint32_t.

bool OCNumberTryGetSInt32(OCNumberRef n, int32_t *out)

Try extract int32_t.

bool OCNumberTryGetUInt64(OCNumberRef n, unsigned long *out)

Try extract uint64_t.

bool OCNumberTryGetSInt64(OCNumberRef n, int64_t *out)

Try extract int64_t.

bool OCNumberTryGetFloat32(OCNumberRef n, float *out)

Try extract float (32-bit).

bool OCNumberTryGetFloat64(OCNumberRef n, double *out)

Try extract double (64-bit).

bool OCNumberTryGetComplex64(OCNumberRef n, float _Complex *out)

Try extract complex float (32-bit).

bool OCNumberTryGetComplex128(OCNumberRef n, double _Complex *out)

Try extract complex double (64-bit).

bool OCNumberTryGetFloat(OCNumberRef n, float *out)

Alias for TryGetFloat32.

bool OCNumberTryGetDouble(OCNumberRef n, double *out)

Alias for TryGetFloat64.

bool OCNumberTryGetFloatComplex(OCNumberRef n, float _Complex *out)

Alias for TryGetComplex64.

bool OCNumberTryGetDoubleComplex(OCNumberRef n, double _Complex *out)

Alias for TryGetComplex128.

bool OCNumberTryGetInt(OCNumberRef n, int *out)

Try extract int native size.

bool OCNumberTryGetLong(OCNumberRef n, long *out)

Try extract long native size.

bool OCNumberTryGetOCIndex(OCNumberRef n, OCIndex *out)

Try extract OCIndex native size.

OCArrayRef OCNumberCreateArrayFromData(OCDataRef data, OCNumberType type, OCStringRef *outError)

Create an OCArray of OCNumbers from binary data.

Interprets the binary data in the OCData as an array of values of the specified OCNumberType and creates an OCArray containing OCNumber objects for each value.

Parameters:

  • data – The OCData containing binary data to convert

  • type – The OCNumberType specifying how to interpret the binary data

  • outError – Optional pointer to receive error message on failure

Returns:

New OCArrayRef containing OCNumbers, or NULL on error (caller must release)

OCDataRef OCNumberCreateDataFromArray(OCArrayRef array, OCNumberType type, OCStringRef *outError)

Create binary data from an OCArray of OCNumbers.

Converts an OCArray containing OCNumber objects into binary data by extracting the values and packing them consecutively in memory according to the specified type. All OCNumbers in the array must be of the specified type.

Parameters:

  • array – The OCArray containing OCNumber objects to convert

  • type – The OCNumberType that all numbers in the array must match

  • outError – Optional pointer to receive error message on failure

Returns:

New OCDataRef containing binary data, or NULL on error (caller must release)

Defines

kOCNumberTypeInvalid

Enums

enum OCNumberType

Enumerates the specific numeric data types that an OCNumber object can represent.

Values:

enumerator kOCNumberSInt8Type

Signed 8-bit integer.

enumerator kOCNumberSInt16Type

Signed 16-bit integer.

enumerator kOCNumberSInt32Type

Signed 32-bit integer.

enumerator kOCNumberSInt64Type

Signed 64-bit integer.

enumerator kOCNumberFloat32Type

32-bit float.

enumerator kOCNumberFloat64Type

64-bit float (double).

enumerator kOCNumberUInt8Type

Unsigned 8-bit integer.

enumerator kOCNumberUInt16Type

Unsigned 16-bit integer.

enumerator kOCNumberUInt32Type

Unsigned 32-bit integer.

enumerator kOCNumberUInt64Type

Unsigned 64-bit integer.

enumerator kOCNumberComplex64Type

Complex float.

enumerator kOCNumberComplex128Type

Complex double.

Functions

const char *OCNumberGetTypeName(OCNumberType type)

Returns the canonical string name for a given OCNumberType.

Parameters:

  • type – The OCNumberType enum value.

Returns:

The string name (e.g., “int32”, “float64”), or NULL if invalid.

OCNumberType OCNumberTypeFromName(const char *name)

Returns the OCNumberType enum value for a given string name.

Parameters:

  • name – The string name (e.g., “int32”, “float64”).

Returns:

The corresponding OCNumberType, or -1 if unrecognized.

OCTypeID OCNumberGetTypeID(void)

The OCTypeID for OCNumber.

Returns the unique OCTypeID for OCNumber.

Returns:

The OCTypeID for the OCNumber type.

OCNumberRef OCNumberCreate(OCNumberType type, void *value)

Create a new OCNumber of given type from raw pointer to value.

Parameters:

  • type – Numeric type tag.

  • value – Pointer to matching C value.

Returns:

New OCNumberRef or NULL on error.

OCNumberType OCNumberGetType(OCNumberRef number)

Get the stored type of an OCNumber.

Parameters:

  • number – An OCNumberRef.

Returns:

Stored OCNumberType or -1 if NULL.

OCStringRef OCNumberCreateStringValue(OCNumberRef number)

Create string representation of a number.

Parameters:

  • number – An OCNumberRef.

Returns:

OCStringRef (caller must release).

OCNumberRef OCNumberCreateWithStringValue(OCNumberType type, const char *stringValue)

Create OCNumber from string and type.

Parameters:

  • type – Target OCNumberType.

  • stringValue – Null-terminated C string.

Returns:

OCNumberRef or NULL on parse error.

OCStringRef OCNumberCopyFormattingDesc(OCNumberRef number)

Copy a human-readable description of the number.

Parameters:

  • number – An OCNumberRef.

Returns:

OCStringRef (caller must release).

bool OCNumberGetValue(OCNumberRef number, OCNumberType type, void *valuePtr)

Extract raw value if types match.

Parameters:

  • number – An OCNumberRef.

  • type – Expected type.

  • valuePtr – Pointer to output buffer.

Returns:

true on success, false on NULL or type mismatch.

int OCNumberTypeSize(OCNumberType type)

Size in bytes of numeric type.

Parameters:

  • type – OCNumberType.

Returns:

Byte size or 0 if invalid.

cJSON *OCNumberCopyAsJSON(OCNumberRef number, bool typed, OCStringRef *outError)

Serialize an OCNumber to JSON using unified complex number format.

JSON Serialization Formats:

UNTYPED MODE (typed=false):

  • Complex numbers: [real, imag] (array of 2 numbers)

  • Non-complex numbers: <number> (JSON number)

  • Note: 64-bit integers may lose precision when converted to JSON numbers

TYPED MODE (typed=true):

  • All types: {“type”: “OCNumber”, “numeric_type”: “<type>”, “value”:

}

  • Complex types: value = [real, imag] (array of 2 numbers)

  • 64-bit integers: value = “<string>” (string for precision)

  • Other types: value = <number> (JSON number)

Examples:

  • Complex64 untyped: [1.0, 2.0]

  • Complex64 typed: {“type”: “OCNumber”, “numeric_type”: “complex64”, “value”: [1.0, 2.0]}

  • Float64 untyped: 3.14159

  • Float64 typed: {“type”: “OCNumber”, “numeric_type”: “float64”, “value”: 3.14159}

  • UInt64 typed: {“type”: “OCNumber”, “numeric_type”: “uint64”, “value”: “18446744073709551615”}

This unified format ensures:

  • Complex numbers use consistent [real, imag] format across all contexts

  • Untyped mode is unambiguous (array = complex, number = real)

  • Size efficiency for bulk complex data serialization

  • Precision preservation for 64-bit integers in typed mode

  • Compatibility with scientific computing array formats

JSON Serialization Format:

TYPED MODE:

  • All types: {“type”: “OCNumber”, “numeric_type”: “<type>”, “value”:

}

  • Complex: value = [real, imag] (array of 2 numbers)

  • Non-complex: value = <number> (JSON number)

  • 64-bit ints: value = “<string>” (string for precision)

UNTYPED MODE:

  • Complex: [real, imag] (array of 2 numbers)

  • Non-complex: <number> (JSON number)

  • 64-bit ints: <number> (JSON number, may lose precision)

Examples:

  • Complex64 typed: {“type”: “OCNumber”, “numeric_type”: “complex64”, “value”: [1.0, 2.0]}

  • Complex64 untyped: [1.0, 2.0]

  • Float64 typed: {“type”: “OCNumber”, “numeric_type”: “float64”, “value”: 3.14}

  • Float64 untyped: 3.14

Parameters:

  • number – An OCNumberRef to serialize.

  • typed – Whether to include type information in the serialization.

  • outError – Optional pointer to receive error information if serialization fails.

  • number – The OCNumber to serialize

  • typed – If true, include type information; if false, serialize value only

Returns:

cJSON object on success (caller responsible), or cJSON null on failure.

Returns:

cJSON object representing the serialized number, or NULL on error

OCNumberRef OCNumberCreateFromJSON(cJSON *json, OCNumberType type, OCStringRef *outError)

Deserialize from untyped JSON using unified format.

Supports the unified complex number format:

  • JSON number → Non-complex OCNumber (type must be specified)

  • JSON array of 2 numbers → Complex OCNumber (type must be complex64/128)

  • JSON string → Any type via string parsing (backward compatibility)

Deserialize from untyped JSON using unified format.

Handles the unified complex number format:

  • JSON number → Non-complex OCNumber (type must be specified)

  • JSON array of 2 numbers → Complex OCNumber (type must specify complex64/128)

  • JSON string → Any type via string parsing (for backward compatibility)

Parameters:

  • json – A cJSON value (number, array of 2, or string).

  • type – Expected OCNumberType.

  • outError – Optional pointer to receive an error string on failure.

  • json – JSON value (number, array of 2, or string)

  • type – Expected OCNumber type

  • outError – Error message if operation fails

Returns:

New OCNumberRef or NULL on failure.

Returns:

OCNumber instance or NULL on error

OCNumberRef OCNumberCreateFromJSONTyped(cJSON *json, OCStringRef *outError)

Create an OCNumberRef from a typed JSON object using unified format.

Parses a JSON object with type information using the unified format: {“type”: “OCNumber”, “numeric_type”: “<type>”, “value”:

}

Where

format depends on numeric_type:

  • Complex types (complex64/128): [real, imag] (array of 2 numbers)

  • 64-bit integers (uint64/sint64): “<string>” (string for precision)

  • Other numeric types: <number> (JSON number)

Also supports legacy “subtype” field for backward compatibility.

Create an OCNumberRef from a typed JSON object using unified format.

Expected format: {“type”: “OCNumber”, “numeric_type”: “<type>”, “value”:

} Where

depends on the numeric_type:

  • Complex types: [real, imag] (array of 2 numbers)

  • 64-bit integers: “<string>” (string for precision)

  • Other types: <number> (JSON number)

Also supports legacy “subtype” field for backward compatibility.

Parameters:

  • json – A cJSON object with type, numeric_type, and value fields.

  • outError – Optional pointer to receive an error string on failure.

  • json – JSON object with type information

  • outError – Error message if operation fails

Returns:

A newly allocated OCNumberRef, or NULL on failure.

Returns:

OCNumber instance or NULL on error