Crate decorum

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:

Class	Trait
real number	`Real`
infinity	`Infinite`
not-a-number	`Nan`

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:

Type	Aliases	Trait Implementations	Disallowed Values
`Total`		`Encoding + Real + Infinite + Nan + Float`
`NotNan`	`N32`, `N64`	`Encoding + Real + Infinite`	`NaN`
`Finite`	`R32`, `R64`	`Encoding + Real`	`NaN`, `-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.