Lib.rs

This is a comprehensive Rust implementation of a 256-bit floating-point type (f256) with extensive functionality for arithmetic and various mathematical operations.

From Wikipedia:

"In its 2008 revision, the IEEE 754 standard specifies a binary256 format among the interchange formats (it is not a basic format), as having:

    Sign bit: 1 bit
    Exponent width: 19 bits
    Significand precision: 237 bits (236 explicitly stored)

The format is written with an implicit lead bit with value 1 unless the exponent is all zeros. Thus only 236 bits of the significand appear in the memory format, but the total precision is 237 bits (approximately 71 decimal digits: log₁₀(2²³⁷) ≈ 71.344). The bits are laid out as follows:

Exponent encoding

The octuple-precision binary floating-point exponent is encoded using an offset binary representation, with the zero offset being 262143; also known as exponent bias in the IEEE 754 standard.

    Eₘᵢₙ = −262142
    Eₘₐₓ = 262143
    Exponent bias = 3FFFF₁₆ = 262143

Thus, as defined by the offset binary representation, in order to get the true exponent the offset of 262143 has to be subtracted from the stored exponent.

The stored exponents 00000₁₆ and 7FFFF₁₆ are interpreted specially.

The minimum strictly positive (subnormal) value is 2⁻²⁶²³⁷⁸ ≈ 10⁻⁷⁸⁹⁸⁴ and has a precision of only one bit. The minimum positive normal value is 2⁻²⁶²¹⁴² ≈ 2.4824 × 10⁻⁷⁸⁹¹³. The maximum representable value is 2²⁶²¹⁴⁴ − 2²⁶¹⁹⁰⁷ ≈ 1.6113 × 10⁷⁸⁹¹³.

Key features include:

Core Implementation

• Binary Encoding: Uses a 256-bit representation compliant with IEEE floating point standard
• Special Values: Proper handling of NaN, infinity, and zero
• Precision: Supports subnormal numbers and full precision arithmetic

Arithmetic Operations

• Basic arithmetic: +, -, *, /
• Comparison operators: ==, !=, <, >, <=, >=
• Negation: Neg trait implementation
• Division with Euclidean remainder: div_euclid, rem_euclid

Elementary Functions

• Exponentiation: powf, powi, exp, exp_m1, exp2
• Logarithms: ln, log2, log10, ln_1p, log
• Trigonometric functions: sin, cos, tan, asin, acos, atan
• Roots: sqrt, cbrt

Utility Functions

• Conversion: Proper conversion from / into strings and basic numerical types
• Classification: is_normal, is_subnormal, is_special, is_integer
• Mathematical Functions: ulp (unit in last place), next_up, next_down

Key Constants

• ZERO, ONE, TWO, MIN_POSITIVE, MIN_GT_ZERO, MAX, MIN
• INFINITY, NEG_INFINITY, NAN
• EPSILON, PI, E

Advanced Features

• Precision Handling: Proper rounding for all operations
• Subnormal Support: Correct handling of very small numbers
• Overflow/Underflow: Appropriate behavior for extreme values
• Special Cases: NaN propagation, infinity arithmetic

Getting started

Add f256 to your Cargo.toml:

[dependencies]
f256 = "0.7"

Crate features

By default, only the feature std is enabled.

Ecosystem

• std - Printing and some tests depend on this feature. Besides that, support for conversion to string and formatting is provided by using crate alloc so that this functionality is also available in non-standard environments.

Optional dependencies

• num-traits - When enabled, the trait num-traits::Num is implemented for f256.