Crate decorum

Expand description

Making floating-point behave: total ordering, equivalence, hashing, constraints, error handling, and more for IEEE 754 floating-point representations.

Decorum provides APIs for extending IEEE 754 floating-point. This is primarily accomplished with proxy types that wrap primitive floating-point types and compose constraints and divergence to configure behavior. Decorum also provides numerous traits describing real numerics and IEEE 754 encoding.

§Proxy Types

Constrained types wrap primitive floating-point types and constrain the set of values that they can represent. These types use the same representation as primitives and in many cases can be used as drop-in replacements, in particular the Total type. Constrained supports numerous traits and APIs (including third-party integrations) and always provides a complete API for real numbers.

Constrained types and their constraints operate on three subsets of IEEE 754 floating-point values:

Subset	Example Member
real numbers	`3.1459`
infinities	`+Inf`
not-a-number	`NaN`

These subsets are reflected throughout APIs, in particular in traits concerning IEEE 754 encoding and constraints. Constraints describe which subsets are members of a proxy type and are composed with a divergence, which further describes the outputs and error behavior of operations.

These types can be configured to, for example, cause a panic in debugging builds whenever a NaN is encountered or enable structured error handling of extended real numbers where any NaN is interpreted as undefined and yields an explicit error value.

Constrained types and their components are provided by the proxy, constraint, and divergence modules. Numerous type definitions are also provided in the crate root:

Type Definition	Subsets
`Total`	real numbers, infinities, not-a-number
`ExtendedReal`	real numbers, infinities
`Real`	real numbers

§Equivalence and Ordering

The cmp module provides APIs for comparing floating-point representations as well as other partially ordered types. For example, it provides traits for intrinic comparisons of partially ordered types that propagate NaNs when used with floating-point representations. It also defines a non-standard total ordering for complete floating-point types:

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

Note that all NaN representations are considered equivalent in this relation. The Total proxy type uses this ordering.

§Hashing

The hash module provides traits for hashing floating-point representations. Hashing is consistent with the total ordering defined by the cmp module. Constrained types implement the standard Hash trait via this module and it also provides functions for hashing primitive floating-point types.

§Numeric Traits

The real module provides traits that describe real numbers and their approximation via floating-point representations. These traits describe the codomain of operations and respect the branching behavior of such functions. For example, many functions over real numbers have a range that includes non-reals (such as undefined). Additionally, these traits feature ergonomic improvements on similar traits in the crate ecosystem.

§Expressions

Expression types represent the output of computations using constrained Constrained types. They provide structured types that directly encode divergence (errors) as values. Unlike other branch types, Expression also supports the same numeric operations as Constrained types, so they can be used fluently in numeric expressions without matching or trying.

use decorum::constraint::IsReal;
use decorum::divergence::OrError;
use decorum::proxy::{Constrained, OutputFor};

type Real = Constrained<f64, IsReal<OrError>>;
type Expr = OutputFor<Real>;

fn f(x: Real, y: Real) -> Expr {
    let z = x + y;
    z / x
}

let z = f(Real::assert(3.0), Real::assert(4.0));
assert!(z.is_defined());

For finer control, the try_expression macro can be used to differentiate between expressions and defined results. When using a nightly Rust toolchain, the unstable Cargo feature also implements the unstable (at time of writing) Try trait for Expression so that the try operator ? may be used instead.

use decorum::constraint::IsReal;
use decorum::divergence::OrError;
use decorum::proxy::{OutputFor, Constrained};
use decorum::real::UnaryRealFunction;

type Real = Constrained<f64, IsReal<OrError>>;
type Expr = OutputFor<Real>;

fn f(x: Real, y: Real) -> Expr {
    x / y
}

let z = f(Real::PI, Real::ONE)?; // OK: `z` is `Real`.
let w = f(Real::PI, Real::ZERO)?; // Error: this returns `Expression::Undefined`.
// ...

Modules§

cmp: Ordering and comparisons of IEEE 754 floating-point and other partially ordered types.
constraint: Constraints on the set of IEEE 754 floating-point values that Constrained types may represent.
divergence: Error behavior and output types for fallible operations.
expression
hash: Hashing of IEEE 754 floating-point values.
prelude
proxy: IEEE 754 floating-point proxy types that apply ordering and configurable contraints and divergence.
real: Constants and functions over real numbers.

Macros§

try_expression: Unwraps an Expression or propagates its error.

Traits§

BaseEncoding: A type with an IEEE 754 floating-point representation that exposes its basic encoding.
InfinityEncoding: A type with an IEEE 754 floating-point representation that supports infinities.
NanEncoding: A type with an IEEE 754 floating-point representation that supports NaNs.
Primitive: A primitive IEEE 754 floating-point type.
ToCanonical: Converts IEEE 754 floating-point values to a canonicalized form.

Type Aliases§

E32: 32-bit IEEE 754 floating-point representation that must be an extended real (not NaN).
E64: 64-bit IEEE 754 floating-point representation that must be an extended real (not NaN).
ExtendedReal: IEEE 754 floating-point representation that must be an extended real.
NotNan: IEEE 754 floating-point representation that must not be NaN.
R32: 32-bit IEEE 754 floating-point representation that must be a real number.
R64: 64-bit IEEE 754 floating-point representation that must be a real number.
Real: IEEE 754 floating-point representation that must be a real number.
Total: IEEE 754 floating-point representation with non-standard total ordering and hashing.

Crate decorumCopy item path