# `ieee_754`

The `ieee_754` library is a support package for parsing and generating IEEE 754 floating-point encodings shared by binary interchange libraries such as `message_pack`, `avro`, `protobuf`, `cbor`, and `wkt_wkb`.

## Loading

To load all entities in this library, load the `loader.lgt` file:

    | ?- logtalk_load(ieee_754(loader)).

## Testing

To test this library predicates, load the `tester.lgt` file:

    | ?- logtalk_load(ieee_754(tester)).

## Object model

The library provides two parameterized implementation objects:

    `ieee_754(Precision, ByteOrder, NaNRepresentation)`

`ieee_754_fields(Precision, ByteOrder)`

with the following parameter values:

- `Precision`: `half`, `single`, or `double`

- `ByteOrder`: `big` or `little`

- `NaNRepresentation`: `canonical` or `payloads`

The parameterization keeps format-specific policy out of the shared core. Advanced callers can use `ieee_754_fields` to inspect exact sign, exponent, mantissa, finite binary-rational decompositions, and NaN payload bits without going through backend float values.

## Value representation

The intended term representation is:

- finite values: backend Prolog floats

- positive infinity: `@infinity`

- negative infinity: `@negative_infinity`

- canonical NaN: `@not_a_number`

- payload-preserving NaN values: `not_a_number(Bytes)`

The `not_a_number(Bytes)` representation is only intended to be accepted and produced by objects configured with `NaNRepresentation = payloads`.

Under the `payloads` policy, decoding a canonical quiet NaN should still yield `@not_a_number`. Non-canonical NaN encodings should decode to `not_a_number(Bytes)` using canonical byte order for the selected precision.

The high-level `ieee_754/3` object API deliberately abstracts away the IEEE 754 quiet-versus-signaling NaN distinction. In `canonical` mode, all NaN encodings decode to `@not_a_number`. In `payloads` mode, the designated canonical quiet NaN encoding decodes to `@not_a_number` while all other NaN encodings decode to `not_a_number(Bytes)` for roundtrip preservation. Callers that need exact NaN inspection should use `ieee_754_fields/2` object API.

## Public API

The high-level value API is defined in `ieee_754_protocol.lgt` and consists of:

- `parse/2` Decodes `bytes(Bytes)` or `bits(Bits)` into a value term.

- `generate/2` Encodes a value term into `bytes(Bytes)` or `bits(Bits)`.

- `generate/3` Encodes a value term to a byte list with an open tail for difference-list based binary generators.

- `valid/1` Checks whether a term is a valid value representation for the selected object.

- `exactly_representable/1` Checks whether a term can be encoded and decoded in the selected precision without loss of value information.

- `precision/1` Returns the selected precision.

- `order/1` Returns the selected byte order.

- `nan_representation/1` Returns the selected NaN representation policy.

- `byte_count/1` Returns the number of bytes used by the selected precision.

The low-level exact field API is defined in `ieee_754_fields_protocol.lgt` and consists of:

- `classify/2` Classifies `bytes(Bytes)` or `bits(Bits)` as `zero`, `subnormal`, `normal`, `infinity`, or `not_a_number`.

- `fields/5` Extracts the exact sign bit, exponent bits, mantissa bits, and class.

- `finite_binary_rational/4` Extracts finite encodings as exact `(-1)^Sign * Significand * 2^Exponent` terms.

- `nan_payload/2` Extracts the raw NaN mantissa payload bits.

- `nan_kind/2` Classifies a NaN encoding as `quiet` or `signaling`.

- `precision/1` Returns the selected precision.

- `order/1` Returns the selected byte order.

- `byte_count/1` Returns the number of bytes used by the selected precision.

## Semantics

The intended shared semantics are:

- finite encoding rounds according to the selected IEEE 754 precision

- `exactly_representable/1` succeeds only when no value information is lost

- signed zero is preserved when supported by the backend Prolog compiler

- infinities and NaN values are represented independently from backend float syntax

- subnormal values are supported for all selected precisions

- payload-preserving NaN decoding is available when explicitly requested

- the `ieee_754_fields` API works from exact encodings and therefore does not depend on backend float decomposition behavior

- exact quiet/signaling NaN inspection is exposed by `ieee_754_fields/2` instead of the high-level value codec API