protocol

# `ieee_754_fields_protocol`

IEEE 754 exact bit-field support library protocol. Intended to be implemented by parameterized objects such as `ieee_754_fields(Precision, ByteOrder)`.

Availability:
`logtalk_load(ieee_754(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-05-09
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `classify/2`

Classifies an IEEE 754 encoding source term as `zero`, `subnormal`, `normal`, `infinity`, or `not_a_number` for the selected precision and byte order. Supported source terms are `bytes(Bytes)` and `bits(Bits)`.

Compilation flags:
`static`
Template:
`classify(Source,Class)`
Mode and number of proofs:
`classify(++compound,--atom)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source term:
`domain_error(ieee_754_source,Source)`
`Source` does not contain a valid encoding for the selected object:
`domain_error(ieee_754_encoding,Source)`

### `fields/5`

Extracts the exact IEEE 754 sign bit, exponent bits, mantissa bits, and classification from a source term.

Compilation flags:
`static`
Template:
`fields(Source,Sign,ExponentBits,MantissaBits,Class)`
Mode and number of proofs:
`fields(++compound,--integer,--integer,--integer,--atom)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source term:
`domain_error(ieee_754_source,Source)`
`Source` does not contain a valid encoding for the selected object:
`domain_error(ieee_754_encoding,Source)`

### `finite_binary_rational/4`

Extracts the exact finite IEEE 754 value as `(-1)^Sign * Significand * 2^Exponent` from a source term. Zero encodings return a zero significand and exponent `0`.

Compilation flags:
`static`
Template:
`finite_binary_rational(Source,Sign,Significand,Exponent)`
Mode and number of proofs:
`finite_binary_rational(++compound,--integer,--integer,--integer)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source term:
`domain_error(ieee_754_source,Source)`
`Source` does not contain a valid encoding for the selected object:
`domain_error(ieee_754_encoding,Source)`
`Source` does not encode a finite IEEE 754 value:
`domain_error(ieee_754_finite_encoding,Source)`

### `nan_payload/2`

Extracts the raw NaN mantissa payload bits from a source term.

Compilation flags:
`static`
Template:
`nan_payload(Source,PayloadBits)`
Mode and number of proofs:
`nan_payload(++compound,--integer)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source term:
`domain_error(ieee_754_source,Source)`
`Source` does not contain a valid encoding for the selected object:
`domain_error(ieee_754_encoding,Source)`
`Source` does not encode a NaN value:
`domain_error(ieee_754_nan_encoding,Source)`

### `nan_kind/2`

Classifies a NaN source term as `quiet` or `signaling` using the exact IEEE 754 quiet/signaling discriminator bit for the selected precision.

Compilation flags:
`static`
Template:
`nan_kind(Source,Kind)`
Mode and number of proofs:
`nan_kind(++compound,--atom)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source term:
`domain_error(ieee_754_source,Source)`
`Source` does not contain a valid encoding for the selected object:
`domain_error(ieee_754_encoding,Source)`
`Source` does not encode a NaN value:
`domain_error(ieee_754_nan_encoding,Source)`

### `precision/1`

Returns the selected IEEE 754 precision. Expected values are `half`, `single`, or `double`.

Compilation flags:
`static`
Template:
`precision(Precision)`
Mode and number of proofs:
`precision(-atom)` - `one`

### `order/1`

Returns the selected byte order. Expected values are `big` or `little`.

Compilation flags:
`static`
Template:
`order(ByteOrder)`
Mode and number of proofs:
`order(-atom)` - `one`

### `byte_count/1`

Returns the number of bytes used by the selected precision.

Compilation flags:
`static`
Template:
`byte_count(ByteCount)`
Mode and number of proofs:
`byte_count(-integer)` - `one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)