Coercion

Coercing values to different datatypes.

typedef uint32_t ExessCoercions

Bitwise OR of ExessCoercion flags.

If this is zero, then only lossless coercions will be performed. 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.

enum ExessCoercion

Coercion flags.

These values are ORed together to enable different kinds of lossy conversion.

enumerator EXESS_APPROXIMATE

Allow 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 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 coercions that truncate significant parts of values.

Specifically, this allows coercing any number to boolean, and dateTime to date or time.

ExessResult exess_coerce_value(ExessCoercions coercions, ExessDatatype in_datatype, size_t in_size, const void *in, ExessDatatype out_datatype, size_t out_size, void *out)

Coerce a value to another datatype if possible.

Parameters:

  • coercions – Enabled coercion flags. If this is 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.

  • in_datatype – Datatype of in.

  • in_size – Size of in in bytes.

  • in – Input value to coerce.

  • out_datatype – Datatype to convert to.

  • out_size – Size of out in bytes.

  • out – Coerced value on success.

Returns:

The count of bytes written, and a status: ExessStatus.EXESS_SUCCESS on successful conversion, ExessStatus.EXESS_OUT_OF_RANGE if the value is outside the range of the target type, ExessStatus.EXESS_LOSS if the required coercion isn’t enabled, or ExessStatus.EXESS_UNSUPPORTED if conversion between the types isn’t supported at all.