[][src]Crate decorum

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

cmp

Ordering and comparisons.

hash

Hashing.

Structs

ConstrainedFloat

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

Traits

Encoding

Floating-point encoding.

Float

Floating-point representations.

Infinite

Floating-point representations that expose infinities.

Nan

Floating-point representations that expose NaNs.

Primitive

Primitive floating-point types.

Real

Types that can represent real numbers.

ToCanonicalBits

Converts floating-point values into a canonicalized form.

Type Definitions

Finite

Floating-point representation that must be a real number.

N32

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

N64

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

NotNan

Floating-point representation that cannot be NaN.

R32

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

R64

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

Total

Floating-point representation with total ordering.