logo
Expand description

Making floating-point behave: ordering, equivalence, hashing, and constraints for floating-point types.

Decorum provides traits that describe types using floating-point representations and provides proxy types that wrap primitive floating-point types. Proxy types implement a total ordering and constraints on the classes of values that they may represent.

Floating-Point Classes

Traits, proxy types, and constraints are based on three classes or subsets of floating-point values:

ClassTrait
real numberReal
infinityInfinite
not-a-numberNan

Primitive floating-point values directly expose IEEE-754 and therefore the complete set of values (and traits). Proxy types implement traits that are compatible with their constraints, so types that disallow NaNs do not implement the Nan trait, for example.

Proxy Types

Proxy types wrap primitive floating-point types and constrain the classes of values that they can represent:

TypeAliasesTrait ImplementationsDisallowed Values
TotalEncoding + Real + Infinite + Nan + Float
NotNanN32, N64Encoding + Real + InfiniteNaN
FiniteR32, R64Encoding + RealNaN, -INF, +INF

The NotNan and Finite types disallow values that represent NaN, $\infin$, and $-\infin$. Operations that emit values that violate these constraints will panic. The Total type applies no constraints and exposes all classes of floating-point values.

Total Ordering

The following total ordering is implemented by all proxy types and is provided by traits in the cmp module:

$$-\infin<\cdots<0<\cdots<\infin<\text{NaN}$$

Note that all zero and NaN representations are considered equivalent. See the cmp module documentation for more details.

Equivalence

Floating-point NaNs have numerous representations and are incomparable. Decorum considers all NaN representations equal to all other NaN representations and any and all NaN representations are unequal to non-NaN values.

See the cmp module documentation for more details.

Modules

Ordering and comparisons.

Hashing.

Structs

Floating-point proxy that provides a total ordering, equivalence, hashing, and constraints.

Traits

Floating-point encoding.

Floating-point representations.

Floating-point representations that expose infinities.

Floating-point representations that expose NaNs.

Primitive floating-point types.

Types that can represent real numbers.

Converts floating-point values into a canonicalized form.

Type Definitions

Floating-point representation that must be a real number.

32-bit floating-point representation that cannot be NaN.

64-bit floating-point representation that cannot be NaN.

Floating-point representation that cannot be NaN.

32-bit floating-point representation that must be a real number.

64-bit floating-point representation that must be a real number.

Floating-point representation with total ordering.