Datatype coercion

Values can be converted between some datatypes using exess_coerce().

This is particularly useful for reducing the number of datatypes that the application needs to explicitly handle.

enum ExessCoercionFlag

Coercion flags.

These values are ORed together to enable different kinds of lossy conversion in exess_coerce().

enumerator EXESS_LOSSLESS

Only do lossless datatype coercions. A lossless coercion is when the value has been perfectly preserved in the target datatype, and coercing it back will result in the same value.

For some datatype combinations this will always be the case, for example from short to long. For others it will depend on the value, for example only the numbers 0 and 1 coerce to boolean without loss.

enumerator EXESS_REDUCE_PRECISION

Allow datatype coercions that reduce the precision of values. This allows coercions that are lossy only in terms of precision, so the resulting value is approximately equal to the original value. Specifically, this allows coercing double to float.

enumerator EXESS_ROUND

Allow datatype coercions that round to the nearest integer. This allows coercing floating point numbers to integers by rounding to the nearest integer, with halfway cases rounding towards even (the default IEEE-754 rounding order).

enumerator EXESS_TRUNCATE

Allow datatype coercions that truncate significant parts of values. This allows coercions that lose data beyond simple precision loss. Specifically, this allows coercing any number to boolean, datetime to date, and datetime to time.

typedef uint32_t ExessCoercionFlags

Bitwise OR of ExessCoercionFlag values.

ExessVariant exess_coerce(ExessVariant value, ExessDatatype datatype, ExessCoercionFlags coercions)

Coerce a value to another datatype if possible.

Parameters

• value – Value to coerce.

• datatype – Datatype to convert to.

• coercions – Enabled coercion flags. If this is ExessCoercionFlag.EXESS_LOSSLESS (zero), then ExessStatus.EXESS_SUCCESS is only returned if the resulting value can be coerced back to the original type without any loss of data. Otherwise, the lossy coercions enabled by the set bits will be attempted.

Returns

ExessStatus.EXESS_SUCCESS on successful conversion, ExessStatus.EXESS_OUT_OF_RANGE if the value is outside the range of the target type, ExessStatus.EXESS_WOULD_REDUCE_PRECISION, ExessStatus.EXESS_WOULD_ROUND, or ExessStatus.EXESS_WOULD_TRUNCATE if the required coercion is not enabled, or ExessStatus.EXESS_UNSUPPORTED if conversion between the types is not supported at all.