//! Utilities for Rust numbers.
//!
//! These traits define useful properties, methods, associated
//! types, and trait bounds, and conversions for working with
//! numbers in generic code.
use core::{fmt, mem, ops};
#[cfg(feature = "f16")]
use crate::bf16::bf16;
#[cfg(feature = "f16")]
use crate::f16::f16;
#[cfg(all(not(feature = "std"), any(feature = "parse-floats", feature = "write-floats")))]
use crate::libm;
// AS PRIMITIVE
// ------------
/// Type that can be converted to [`primitive`] values with `as`.
///
/// [`primitive`]: https://doc.rust-lang.org/rust-by-example/primitives.html
pub trait AsPrimitive: Copy + PartialEq + PartialOrd + Send + Sync + Sized {
/// Convert the value to a [`u8`], as if by `value as u8`.
fn as_u8(self) -> u8;
/// Convert the value to a [`u16`], as if by `value as u16`.
fn as_u16(self) -> u16;
/// Convert the value to a [`u32`], as if by `value as u32`.
fn as_u32(self) -> u32;
/// Convert the value to a [`u64`], as if by `value as u64`.
fn as_u64(self) -> u64;
/// Convert the value to a [`u128`], as if by `value as u128`.
fn as_u128(self) -> u128;
/// Convert the value to a [`usize`], as if by `value as usize`.
fn as_usize(self) -> usize;
/// Convert the value to an [`i8`], as if by `value as i8`.
fn as_i8(self) -> i8;
/// Convert the value to an [`i16`], as if by `value as i16`.
fn as_i16(self) -> i16;
/// Convert the value to an [`i32`], as if by `value as i32`.
fn as_i32(self) -> i32;
/// Convert the value to an [`i64`], as if by `value as i64`.
fn as_i64(self) -> i64;
/// Convert the value to an [`i128`], as if by `value as i128`.
fn as_i128(self) -> i128;
/// Convert the value to an [`isize`], as if by `value as isize`.
fn as_isize(self) -> isize;
/// Convert the value to an [`f32`], as if by `value as f32`.
fn as_f32(self) -> f32;
/// Convert the value to an [`f64`], as if by `value as f64`.
fn as_f64(self) -> f64;
/// Convert the value from a [`u32`], as if by `value as _`.
fn from_u32(value: u32) -> Self;
/// Convert the value from a [`u64`], as if by `value as _`.
fn from_u64(value: u64) -> Self;
/// Convert the value to an [`struct@f16`], identical to `value as f16`
/// if [`struct@f16`] was a primitive type.
#[cfg(feature = "f16")]
fn as_f16(self) -> f16;
/// Convert the value to an [`struct@bf16`], identical to `value as bf16`
/// if [`struct@bf16`] was a primitive type.
#[cfg(feature = "f16")]
fn as_bf16(self) -> bf16;
}
macro_rules! as_primitive {
($($t:ty)*) => ($(
impl AsPrimitive for $t {
#[inline(always)]
fn as_u8(self) -> u8 {
self as u8
}
#[inline(always)]
fn as_u16(self) -> u16 {
self as u16
}
#[inline(always)]
fn as_u32(self) -> u32 {
self as u32
}
#[inline(always)]
fn as_u64(self) -> u64 {
self as u64
}
#[inline(always)]
fn as_u128(self) -> u128 {
self as u128
}
#[inline(always)]
fn as_usize(self) -> usize {
self as usize
}
#[inline(always)]
fn as_i8(self) -> i8 {
self as i8
}
#[inline(always)]
fn as_i16(self) -> i16 {
self as i16
}
#[inline(always)]
fn as_i32(self) -> i32 {
self as i32
}
#[inline(always)]
fn as_i64(self) -> i64 {
self as i64
}
#[inline(always)]
fn as_i128(self) -> i128 {
self as i128
}
#[inline(always)]
fn as_isize(self) -> isize {
self as isize
}
#[inline(always)]
fn as_f32(self) -> f32 {
self as f32
}
#[inline(always)]
fn as_f64(self) -> f64 {
self as f64
}
#[inline(always)]
fn from_u32(value: u32) -> Self {
value as Self
}
#[inline(always)]
fn from_u64(value: u64) -> Self {
value as Self
}
#[cfg(feature = "f16")]
#[inline(always)]
fn as_f16(self) -> f16 {
f16::from_f32(self as f32)
}
#[cfg(feature = "f16")]
#[inline(always)]
fn as_bf16(self) -> bf16 {
bf16::from_f32(self as f32)
}
}
)*)
}
as_primitive! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize f32 f64 }
#[cfg(feature = "f16")]
macro_rules! half_as_primitive {
($($t:ty)*) => ($(
impl AsPrimitive for $t {
#[inline(always)]
fn as_u8(self) -> u8 {
self.as_f32() as u8
}
#[inline(always)]
fn as_u16(self) -> u16 {
self.as_f32() as u16
}
#[inline(always)]
fn as_u32(self) -> u32 {
self.as_f32() as u32
}
#[inline(always)]
fn as_u64(self) -> u64 {
self.as_f32() as u64
}
#[inline(always)]
fn as_u128(self) -> u128 {
self.as_f32() as u128
}
#[inline(always)]
fn as_usize(self) -> usize {
self.as_f32() as usize
}
#[inline(always)]
fn as_i8(self) -> i8 {
self.as_f32() as i8
}
#[inline(always)]
fn as_i16(self) -> i16 {
self.as_f32() as i16
}
#[inline(always)]
fn as_i32(self) -> i32 {
self.as_f32() as i32
}
#[inline(always)]
fn as_i64(self) -> i64 {
self.as_f32() as i64
}
#[inline(always)]
fn as_i128(self) -> i128 {
self.as_f32() as i128
}
#[inline(always)]
fn as_isize(self) -> isize {
self.as_f32() as isize
}
#[inline(always)]
fn as_f32(self) -> f32 {
self.as_f32() as f32
}
#[inline(always)]
fn as_f64(self) -> f64 {
self.as_f32() as f64
}
#[inline(always)]
#[allow(clippy::as_underscore)] // reason="intentionally used in a generic sense"
fn from_u32(value: u32) -> Self {
Self::from_f32(value as _)
}
#[inline(always)]
fn from_u64(value: u64) -> Self {
_ = value;
unimplemented!()
}
#[inline(always)]
fn as_f16(self) -> f16 {
f16::from_f32(self.as_f32())
}
#[inline(always)]
fn as_bf16(self) -> bf16 {
bf16::from_f32(self.as_f32())
}
}
)*)
}
#[cfg(feature = "f16")]
half_as_primitive! { f16 bf16 }
// AS CAST
// -------
/// An interface for casting between machine scalars, as if `as` was used.
///
/// All values that the type can be cast to must be [`primitive`] values.
///
/// [`primitive`]: https://doc.rust-lang.org/rust-by-example/primitives.html
pub trait AsCast: AsPrimitive {
/// Creates a number from another value that can be converted into
/// a primitive via the [`AsPrimitive`] trait.
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::AsCast;
///
/// assert_eq!(u8::as_cast(256u16), 256u16 as u8); // 0
/// ```
fn as_cast<N: AsPrimitive>(n: N) -> Self;
}
/// Allows the high-level conversion of generic types as if `as` was used.
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::as_cast;
///
/// assert_eq!(as_cast::<u8, u16>(256u16), 256u16 as u8); // 0
/// ```
#[inline(always)]
pub fn as_cast<U: AsCast, T: AsCast>(t: T) -> U {
U::as_cast(t)
}
macro_rules! as_cast {
($($t:ty, $meth:ident ; )*) => ($(
impl AsCast for $t {
#[inline(always)]
#[allow(clippy::as_underscore)] // reason="intentional due to generic API"
fn as_cast<N: AsPrimitive>(n: N) -> $t {
n.$meth() as _
}
}
)*);
}
as_cast!(
u8, as_u8 ;
u16, as_u16 ;
u32, as_u32 ;
u64, as_u64 ;
u128, as_u128 ;
usize, as_usize ;
i8, as_i8 ;
i16, as_i16 ;
i32, as_i32 ;
i64, as_i64 ;
i128, as_i128 ;
isize, as_isize ;
f32, as_f32 ;
f64, as_f64 ;
);
#[cfg(feature = "f16")]
as_cast!(
f16, as_f16 ;
bf16, as_bf16 ;
);
// PRIMITIVE
// ---------
/// The base trait for all [`primitive`] types.
///
/// [`primitive`]: https://doc.rust-lang.org/rust-by-example/primitives.html
pub trait Primitive: 'static + fmt::Debug + fmt::Display + AsCast {}
macro_rules! primitive {
($($t:ty)*) => ($(
impl Primitive for $t {}
)*)
}
primitive! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize f32 f64 }
#[cfg(feature = "f16")]
primitive! { f16 bf16 }
// NUMBER
// ------
/// The base trait for all numbers (integers and floating-point numbers).
pub trait Number:
Default +
Primitive +
// Operations
ops::Add<Output=Self> +
ops::AddAssign +
ops::Div<Output=Self> +
ops::DivAssign +
ops::Mul<Output=Self> +
ops::MulAssign +
ops::Rem<Output=Self> +
ops::RemAssign +
ops::Sub<Output=Self> +
ops::SubAssign
{
/// If the number can hold negative values.
const IS_SIGNED: bool;
}
macro_rules! number_impl {
($($t:tt $is_signed:literal ; )*) => ($(
impl Number for $t {
const IS_SIGNED: bool = $is_signed;
}
)*)
}
number_impl! {
u8 false ;
u16 false ;
u32 false ;
u64 false ;
u128 false ;
usize false ;
i8 true ;
i16 true ;
i32 true ;
i64 true ;
i128 true ;
isize true ;
f32 true ;
f64 true ;
// f128 true
}
#[cfg(feature = "f16")]
number_impl! {
f16 true ;
bf16 true ;
}
// INTEGER
// -------
/// The base trait for all signed and unsigned [`integers`].
///
/// [`integers`]: https://en.wikipedia.org/wiki/Integer_(computer_science)
pub trait Integer:
// Basic
Number + Eq + Ord +
// Operations
ops::BitAnd<Output=Self> +
ops::BitAndAssign +
ops::BitOr<Output=Self> +
ops::BitOrAssign +
ops::BitXor<Output=Self> +
ops::BitXorAssign +
ops::Not<Output=Self> +
ops::Shl<Self, Output=Self> +
ops::Shl<i32, Output=Self> +
ops::ShlAssign<i32> +
ops::Shr<i32, Output=Self> +
ops::ShrAssign<i32> +
{
// CONSTANTS
/// A value equal to `0`.
const ZERO: Self;
/// A value equal to `1`.
const ONE: Self;
/// A value equal to `2`.
const TWO: Self;
/// The largest value that can be represented by this integer type.
///
/// See [`u32::MAX`].
const MAX: Self;
/// The smallest value that can be represented by this integer type.
///
/// See [`u32::MIN`].
const MIN: Self;
/// The size of this integer type in bits.
///
/// See [`u32::BITS`].
const BITS: usize;
// FUNCTIONS (INHERITED)
/// Returns the number of leading zeros in the binary representation
/// of `self`.
///
/// See [`u32::leading_zeros`].
fn leading_zeros(self) -> u32;
/// Returns the number of trailing zeros in the binary representation
/// of `self`.
///
/// See [`u32::trailing_zeros`].
fn trailing_zeros(self) -> u32;
/// Raises self to the power of `exp`, using exponentiation by squaring.
///
/// See [`u32::pow`].
fn pow(self, exp: u32) -> Self;
/// Checked exponentiation. Computes `self.pow(exp)`, returning
/// `None` if overflow occurred.
///
/// See [`u32::checked_pow`].
fn checked_pow(self, exp: u32) -> Option<Self>;
/// Raises self to the power of `exp`, using exponentiation by squaring.
///
/// Returns a tuple of the exponentiation along with a bool indicating
/// whether an overflow happened.
///
/// See [`u32::overflowing_pow`].
fn overflowing_pow(self, exp: u32) -> (Self, bool);
/// Checked integer addition. Computes `self + i`, returning `None` if
/// overflow occurred.
///
/// See [`u32::checked_add`].
fn checked_add(self, i: Self) -> Option<Self>;
/// Checked integer subtraction. Computes `self - i`, returning `None`
/// if overflow occurred.
///
/// See [`u32::checked_sub`].
fn checked_sub(self, i: Self) -> Option<Self>;
/// Checked integer multiplication. Computes `self * rhs`, returning `None`
/// if overflow occurred.
///
/// See [`u32::checked_mul`].
fn checked_mul(self, i: Self) -> Option<Self>;
/// Calculates `self + i`.
///
/// Returns a tuple of the addition along with a boolean indicating whether
/// an arithmetic overflow would occur. If an overflow would have occurred
/// then the wrapped value is returned. See [`u32::overflowing_add`].
fn overflowing_add(self, i: Self) -> (Self, bool);
/// Calculates `self - i`.
///
/// Returns a tuple of the addition along with a boolean indicating whether
/// an arithmetic overflow would occur. If an overflow would have occurred
/// then the wrapped value is returned. See [`u32::overflowing_sub`].
fn overflowing_sub(self, i: Self) -> (Self, bool);
/// Calculates `self * i`.
///
/// Returns a tuple of the addition along with a boolean indicating whether
/// an arithmetic overflow would occur. If an overflow would have occurred
/// then the wrapped value is returned. See [`u32::overflowing_mul`].
fn overflowing_mul(self, i: Self) -> (Self, bool);
/// Wrapping (modular) addition. Computes `self + i`, wrapping around at
/// the boundary of the type.
///
/// See [`u32::wrapping_add`].
fn wrapping_add(self, i: Self) -> Self;
/// Wrapping (modular) subtraction. Computes `self - i`, wrapping around at
/// the boundary of the type.
///
/// See [`u32::wrapping_sub`].
fn wrapping_sub(self, i: Self) -> Self;
/// Wrapping (modular) multiplication. Computes `self * i`, wrapping around at
/// the boundary of the type.
///
/// See [`u32::wrapping_mul`].
fn wrapping_mul(self, i: Self) -> Self;
/// Wrapping (modular) negation. Computes `-self`, wrapping around at
/// the boundary of the type.
///
/// See [`u32::wrapping_neg`].
fn wrapping_neg(self) -> Self;
/// Saturating integer addition. Computes `self + i`, saturating at the
/// numeric bounds instead of overflowing.
///
/// See [`u32::saturating_add`].
fn saturating_add(self, i: Self) -> Self;
/// Saturating integer subtraction. Computes `self - i`, saturating at the
/// numeric bounds instead of overflowing.
///
/// See [`u32::saturating_sub`].
fn saturating_sub(self, i: Self) -> Self;
/// Saturating integer multiplication. Computes `self * i`, saturating at
/// the numeric bounds instead of overflowing.
///
/// See [`u32::saturating_mul`].
fn saturating_mul(self, i: Self) -> Self;
/// Get the fast ceiling of the quotient from integer division.
///
/// The remainder may wrap to the numerical boundaries for the type.
/// See [`u32::div_ceil`].
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Integer;
///
/// assert_eq!(250u16.ceil_divmod(10), (25, 0));
/// assert_eq!(256u16.ceil_divmod(10), (26, -4));
/// assert_eq!(i32::MAX.ceil_divmod(-2), (-0x3FFFFFFE, 3));
///
/// // notice how `-1` wraps since `i32` cannot hold `i128::MAX`.
/// assert_eq!((i128::MAX - 1).ceil_divmod(i128::MAX), (1, -1));
/// ```
#[inline(always)]
fn ceil_divmod(self, y: Self) -> (Self, i32) {
let q = self / y;
let r = self % y;
match r == Self::ZERO {
true => (q, i32::as_cast(r)),
false => (q + Self::ONE, i32::as_cast(r) - i32::as_cast(y))
}
}
/// Get the fast ceiling of the quotient from integer division.
///
/// This is identical to [`u32::div_ceil`].
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Integer;
///
/// assert_eq!(250u16.ceil_div(10), 25);
/// assert_eq!(256u16.ceil_div(10), 26);
/// assert_eq!(i32::MAX.ceil_div(-2), -0x3FFFFFFE);
/// assert_eq!((i128::MAX - 1).ceil_div(i128::MAX), 1);
/// ```
#[inline(always)]
fn ceil_div(self, y: Self) -> Self {
self.ceil_divmod(y).0
}
/// Get the fast ceiling modulus from integer division.
///
/// The remainder is not guaranteed to be valid since it can
/// overflow if the remainder is not 0. See [`Self::ceil_divmod`].
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Integer;
///
/// assert_eq!(250u16.ceil_mod(10), 0);
/// assert_eq!(256u16.ceil_mod(10), -4);
/// assert_eq!(i32::MAX.ceil_mod(-2), 3);
///
/// // notice how `-1` wraps since `i32` cannot hold `i128::MAX`.
/// assert_eq!((i128::MAX - 1).ceil_mod(i128::MAX), -1);
/// ```
#[inline(always)]
fn ceil_mod(self, y: Self) -> i32 {
self.ceil_divmod(y).1
}
// PROPERTIES
/// Get the number of bits in a value.
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Integer;
///
/// assert_eq!(1u64.bit_length(), 1);
/// assert_eq!(2u64.bit_length(), 2);
/// assert_eq!(3u64.bit_length(), 2);
/// assert_eq!(16u64.bit_length(), 5);
/// ```
#[inline(always)]
fn bit_length(self) -> u32 {
Self::BITS as u32 - self.leading_zeros()
}
/// Returns true if the least-significant bit is odd.
#[inline(always)]
fn is_odd(self) -> bool {
self & Self::ONE == Self::ONE
}
/// Returns true if the least-significant bit is even.
#[inline(always)]
fn is_even(self) -> bool {
!self.is_odd()
}
/// Get the maximum number of digits before the slice will overflow.
///
/// This is effectively the `floor(log(2^BITS-1, radix))`, but we can
/// try to go a bit lower without worrying too much.
#[inline(always)]
fn overflow_digits(radix: u32) -> usize {
// this is heavily optimized for base10 and it's a way under estimate
// that said, it's fast and works.
if radix <= 16 {
mem::size_of::<Self>() * 2 - Self::IS_SIGNED as usize
} else {
// way under approximation but always works and is fast
mem::size_of::<Self>()
}
}
}
macro_rules! integer_impl {
($($t:tt)*) => ($(
impl Integer for $t {
const ZERO: $t = 0;
const ONE: $t = 1;
const TWO: $t = 2;
const MAX: $t = $t::MAX;
const MIN: $t = $t::MIN;
const BITS: usize = $t::BITS as usize;
#[inline(always)]
fn leading_zeros(self) -> u32 {
$t::leading_zeros(self)
}
#[inline(always)]
fn trailing_zeros(self) -> u32 {
$t::trailing_zeros(self)
}
#[inline(always)]
fn checked_add(self, i: Self) -> Option<Self> {
$t::checked_add(self, i)
}
#[inline(always)]
fn checked_sub(self, i: Self) -> Option<Self> {
$t::checked_sub(self, i)
}
#[inline(always)]
fn checked_mul(self, i: Self) -> Option<Self> {
$t::checked_mul(self, i)
}
#[inline(always)]
fn overflowing_add(self, i: Self) -> (Self, bool) {
$t::overflowing_add(self, i)
}
#[inline(always)]
fn overflowing_sub(self, i: Self) -> (Self, bool) {
$t::overflowing_sub(self, i)
}
#[inline(always)]
fn overflowing_mul(self, i: Self) -> (Self, bool) {
$t::overflowing_mul(self, i)
}
#[inline(always)]
fn wrapping_add(self, i: Self) -> Self {
$t::wrapping_add(self, i)
}
#[inline(always)]
fn wrapping_sub(self, i: Self) -> Self {
$t::wrapping_sub(self, i)
}
#[inline(always)]
fn wrapping_mul(self, i: Self) -> Self {
$t::wrapping_mul(self, i)
}
#[inline(always)]
fn wrapping_neg(self) -> Self {
$t::wrapping_neg(self)
}
#[inline(always)]
fn pow(self, exp: u32) -> Self {
Self::pow(self, exp)
}
#[inline(always)]
fn checked_pow(self, exp: u32) -> Option<Self> {
Self::checked_pow(self, exp)
}
#[inline(always)]
fn overflowing_pow(self, exp: u32) -> (Self, bool) {
Self::overflowing_pow(self, exp)
}
#[inline(always)]
fn saturating_add(self, i: Self) -> Self {
$t::saturating_add(self, i)
}
#[inline(always)]
fn saturating_sub(self, i: Self) -> Self {
$t::saturating_sub(self, i)
}
#[inline(always)]
fn saturating_mul(self, i: Self) -> Self {
$t::saturating_mul(self, i)
}
}
)*)
}
integer_impl! { u8 u16 u32 u64 u128 i8 i16 i32 i64 i128 usize isize }
// SIGNED INTEGER
// --------------
/// The trait for types that support [`signed`] integral operations, that is,
/// they can hold negative numbers.
///
/// [`signed`]: https://en.wikipedia.org/wiki/Integer_(computer_science)#Value_and_representation
pub trait SignedInteger: Integer + ops::Neg<Output = Self> {}
macro_rules! signed_integer_impl {
($($t:tt)*) => ($(
impl SignedInteger for $t {}
)*)
}
signed_integer_impl! { i8 i16 i32 i64 i128 isize }
// UNSIGNED INTEGER
// ----------------
/// The trait for types that support [`unsigned`] integral operations, that is,
/// they can only hold positive numbers.
///
/// [`unsigned`]: https://en.wikipedia.org/wiki/Integer_(computer_science)#Value_and_representation
pub trait UnsignedInteger: Integer {}
macro_rules! unsigned_integer_impl {
($($t:ty)*) => ($(
impl UnsignedInteger for $t {}
)*)
}
unsigned_integer_impl! { u8 u16 u32 u64 u128 usize }
// FLOAT
// -----
/// The trait for floating-point [`numbers`][`floats`].
///
/// Floating-point numbers are numbers that may contain a fraction
/// and are stored internally as the significant digits and an
/// exponent of base 2.
///
/// [`floats`]: https://en.wikipedia.org/wiki/Floating-point_arithmetic
#[cfg(any(feature = "parse-floats", feature = "write-floats"))]
pub trait Float: Number + ops::Neg<Output = Self> {
/// Unsigned type of the same size.
type Unsigned: UnsignedInteger;
// CONSTANTS
/// A value equal to `0`.
const ZERO: Self;
/// A value equal to `1`.
const ONE: Self;
/// A value equal to `2`.
const TWO: Self;
/// Largest finite value.
///
/// See [`f64::MAX`].
const MAX: Self;
/// Smallest finite value.
///
/// See [`f64::MIN`].
const MIN: Self;
/// Infinity (`∞`).
///
/// See [`f64::INFINITY`].
const INFINITY: Self;
/// Negative infinity (`−∞`).
///
/// See [`f64::NEG_INFINITY`].
const NEG_INFINITY: Self;
/// Not a Number (NaN).
///
/// See [`f64::NAN`].
const NAN: Self;
/// The size of this float type in bits.
///
/// Analogous to [`u32::BITS`].
const BITS: usize;
/// Bitmask to extract the sign from the float.
const SIGN_MASK: Self::Unsigned;
/// Bitmask to extract the biased exponent, including the hidden bit.
const EXPONENT_MASK: Self::Unsigned;
/// Bitmask to extract the hidden bit in the exponent, which is an
/// implicit 1 in the significant digits.
const HIDDEN_BIT_MASK: Self::Unsigned;
/// Bitmask to extract the mantissa (significant digits), excluding
/// the hidden bit.
const MANTISSA_MASK: Self::Unsigned;
/// Mask to determine if a full-carry occurred (1 in bit above hidden bit).
const CARRY_MASK: Self::Unsigned;
// PROPERTIES
// The following constants can be calculated as follows:
// - `INFINITY_BITS`: EXPONENT_MASK
// - `NEGATIVE_INFINITY_BITS`: INFINITY_BITS | SIGN_MASK
// - `EXPONENT_BIAS`: `2^(EXPONENT_SIZE-1) - 1 + MANTISSA_SIZE`
// - `DENORMAL_EXPONENT`: `1 - EXPONENT_BIAS`
// - `MAX_EXPONENT`: `2^EXPONENT_SIZE - 1 - EXPONENT_BIAS`
/// Positive infinity as bits.
const INFINITY_BITS: Self::Unsigned;
/// Positive infinity as bits.
const NEGATIVE_INFINITY_BITS: Self::Unsigned;
/// The number of bits in the exponent.
const EXPONENT_SIZE: i32;
/// Size of the significand (mantissa) without the hidden bit.
const MANTISSA_SIZE: i32;
/// Bias of the exponent. See [`exponent bias`].
///
/// [`exponent bias`]: https://en.wikipedia.org/wiki/Exponent_bias
const EXPONENT_BIAS: i32;
/// Exponent portion of a [`denormal`] float.
///
/// [`denormal`]: https://en.wikipedia.org/wiki/Subnormal_number
const DENORMAL_EXPONENT: i32;
/// Maximum (unbiased) exponent value in the float.
const MAX_EXPONENT: i32;
// FUNCTIONS (INHERITED)
// Re-export the to and from bits methods.
/// Raw transmutation to the unsigned integral type.
///
/// See [`f64::to_bits`].
fn to_bits(self) -> Self::Unsigned;
/// Raw transmutation from the unsigned integral type.
///
/// See [`f64::from_bits`].
fn from_bits(u: Self::Unsigned) -> Self;
/// Returns the natural logarithm of the number.
///
/// See [`f64::ln`].
fn ln(self) -> Self;
/// Returns the largest integer less than or equal to `self`.
///
/// See [`f64::floor`].
fn floor(self) -> Self;
/// Returns true if `self` has a positive sign, including `+0.0`,
/// NaNs with positive sign bit and positive infinity.
///
/// See [`f64::is_sign_positive`].
fn is_sign_positive(self) -> bool;
/// Returns true if `self` has a negative sign, including `-0.0`,
/// NaNs with negative sign bit and negative infinity.
///
/// See [`f64::is_sign_negative`].
fn is_sign_negative(self) -> bool;
/// Returns true if the float is [`denormal`].
///
/// Denormal (subnormal) numbers fall below the range of numbers
/// that can be stored as `mantissa * 2^exp`, and therefore
/// always have the minimum exponent.
///
/// [`denormal`]: https://en.wikipedia.org/wiki/Subnormal_number
#[inline(always)]
fn is_denormal(self) -> bool {
self.to_bits() & Self::EXPONENT_MASK == Self::Unsigned::ZERO
}
/// Returns true if the float is NaN, positive infinity, or negative
/// infinity.
#[inline(always)]
fn is_special(self) -> bool {
self.to_bits() & Self::EXPONENT_MASK == Self::EXPONENT_MASK
}
/// Returns true if the float is NaN.
#[inline(always)]
fn is_nan(self) -> bool {
self.is_special() && (self.to_bits() & Self::MANTISSA_MASK) != Self::Unsigned::ZERO
}
/// Returns true if the float is positive or negative infinity.
#[inline(always)]
fn is_inf(self) -> bool {
self.is_special() && (self.to_bits() & Self::MANTISSA_MASK) == Self::Unsigned::ZERO
}
/// Returns true if the float's least-significant mantissa bit is odd.
#[inline(always)]
fn is_odd(self) -> bool {
self.to_bits().is_odd()
}
/// Returns true if the float's least-significant mantissa bit is even.
#[inline(always)]
fn is_even(self) -> bool {
!self.is_odd()
}
/// Returns true if the float needs a negative sign when serializing it.
///
/// This is true if it's `-0.0` or it's below 0 and not NaN. But inf values
/// need the sign.
#[inline(always)]
fn needs_negative_sign(self) -> bool {
self.is_sign_negative() && !self.is_nan()
}
/// Get the unbiased exponent component from the float.
#[inline(always)]
fn exponent(self) -> i32 {
if self.is_denormal() {
return Self::DENORMAL_EXPONENT;
}
let bits = self.to_bits();
let biased_e = i32::as_cast((bits & Self::EXPONENT_MASK) >> Self::MANTISSA_SIZE).as_i32();
biased_e - Self::EXPONENT_BIAS
}
/// Get the mantissa (significand) component from float.
#[inline(always)]
fn mantissa(self) -> Self::Unsigned {
let bits = self.to_bits();
let s = bits & Self::MANTISSA_MASK;
if !self.is_denormal() {
s + Self::HIDDEN_BIT_MASK
} else {
s
}
}
/// Get next greater float.
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Float;
///
/// assert_eq!(1f32.next(), 1.0000001);
/// assert_eq!((-0.0f32).next(), 0.0); // +0.0
/// assert_eq!(0f32.next(), 1e-45);
/// ```
#[inline(always)]
fn next(self) -> Self {
let bits = self.to_bits();
if self.is_sign_negative() && self == Self::ZERO {
// -0.0
Self::ZERO
} else if bits == Self::INFINITY_BITS {
Self::from_bits(Self::INFINITY_BITS)
} else if self.is_sign_negative() {
Self::from_bits(bits.saturating_sub(Self::Unsigned::ONE))
} else {
Self::from_bits(bits.saturating_add(Self::Unsigned::ONE))
}
}
/// Get next greater float for a positive float.
///
/// Value must be >= 0.0 and < INFINITY.
#[inline(always)]
fn next_positive(self) -> Self {
debug_assert!(self.is_sign_positive() && !self.is_inf());
Self::from_bits(self.to_bits() + Self::Unsigned::ONE)
}
/// Get previous greater float, such that `self.prev().next() == self`.
///
/// # Examples
///
/// ```rust
/// use lexical_util::num::Float;
///
/// assert_eq!(1f32.prev(), 0.99999994);
/// assert_eq!(0.0f32.prev(), 0.0); // -0.0
/// assert_eq!((-0.0f32).prev(), -1e-45);
/// ```
#[inline(always)]
fn prev(self) -> Self {
let bits = self.to_bits();
if self.is_sign_positive() && self == Self::ZERO {
// +0.0
-Self::ZERO
} else if bits == Self::NEGATIVE_INFINITY_BITS {
Self::from_bits(Self::NEGATIVE_INFINITY_BITS)
} else if self.is_sign_negative() {
Self::from_bits(bits.saturating_add(Self::Unsigned::ONE))
} else {
Self::from_bits(bits.saturating_sub(Self::Unsigned::ONE))
}
}
/// Get previous greater float for a positive float.
/// Value must be > 0.0.
#[inline(always)]
fn prev_positive(self) -> Self {
debug_assert!(self.is_sign_positive() && self != Self::ZERO);
Self::from_bits(self.to_bits() - Self::Unsigned::ONE)
}
/// Round a positive number to even.
#[inline(always)]
fn round_positive_even(self) -> Self {
if self.mantissa().is_odd() {
self.next_positive()
} else {
self
}
}
/// Get the max of two finite numbers.
///
/// This assumes that both floats form a [`total ord`],
/// that is, `x < y` is always `y >= x`. Non-finite floats,
/// such as NaN, break this criteria, but finite floats enable
/// simpler (and faster) comparison criteria while remaining
/// accurate.
///
/// [`total ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
#[inline(always)]
fn max_finite(self, f: Self) -> Self {
debug_assert!(!self.is_special() && !f.is_special(), "max_finite self={} f={}", self, f);
if self < f {
f
} else {
self
}
}
/// Get the min of two finite numbers.
///
/// This assumes that both floats form a [`total ord`],
/// that is, `x < y` is always `y >= x`. Non-finite floats,
/// such as NaN, break this criteria, but finite floats enable
/// simpler (and faster) comparison criteria while remaining
/// accurate.
///
/// [`total ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
#[inline(always)]
fn min_finite(self, f: Self) -> Self {
debug_assert!(!self.is_special() && !f.is_special(), "min_finite self={} f={}", self, f);
if self < f {
self
} else {
f
}
}
}
/// Define the float literals.
#[cfg(any(feature = "parse-floats", feature = "write-floats"))]
macro_rules! float_literals {
($float:ty) => {
const ZERO: $float = 0.0;
const ONE: $float = 1.0;
const TWO: $float = 2.0;
const MAX: $float = <$float>::MAX;
const MIN: $float = <$float>::MIN;
const INFINITY: $float = <$float>::INFINITY;
const NEG_INFINITY: $float = <$float>::NEG_INFINITY;
const NAN: $float = <$float>::NAN;
const BITS: usize = mem::size_of::<$float>() * 8;
};
}
/// Define the float masks.
#[cfg(any(feature = "parse-floats", feature = "write-floats"))]
macro_rules! float_masks {
(
float =>
$float:ty,sign_mask =>
$sign:literal,exponent_mask =>
$exponent:literal,hidden_bit_mask =>
$hidden:literal,mantissa_mask =>
$mantissa:literal,
) => {
const SIGN_MASK: <$float>::Unsigned = $sign;
const EXPONENT_MASK: <$float>::Unsigned = $exponent;
const HIDDEN_BIT_MASK: <$float>::Unsigned = $hidden;
const MANTISSA_MASK: <$float>::Unsigned = $mantissa;
// The carry mask is always 1 bit above the hidden bit.
const CARRY_MASK: <$float>::Unsigned = $hidden << 1;
// Infinity is always every exponent bit set.
const INFINITY_BITS: <$float>::Unsigned = $exponent;
// Negative infinity is just infinity + sign.
const NEGATIVE_INFINITY_BITS: <$float>::Unsigned = $exponent | $sign;
};
}
// Due to missing specifics or types for the following float types,
// `Float` is not yet fully implemented for:
// - f128
#[cfg(feature = "f16")]
macro_rules! float_one {
($f:ident) => {
(($f::EXPONENT_BIAS - $f::MANTISSA_SIZE) as u16) << $f::MANTISSA_SIZE
};
}
#[cfg(feature = "f16")]
macro_rules! float_two {
($f:ident) => {
(($f::EXPONENT_BIAS - $f::MANTISSA_SIZE + 1) as u16) << $f::MANTISSA_SIZE
};
}
#[cfg(feature = "f16")]
macro_rules! float_max {
($f:ident) => {
($f::EXPONENT_MASK ^ $f::HIDDEN_BIT_MASK) | $f::MANTISSA_MASK
};
}
#[cfg(feature = "f16")]
macro_rules! float_min {
($f:ident) => {
$f::MAX.to_bits() | $f::SIGN_MASK
};
}
#[cfg(feature = "f16")]
macro_rules! float_nan {
($f:ident) => {
$f::EXPONENT_MASK | ($f::HIDDEN_BIT_MASK >> 1)
};
}
#[cfg(feature = "f16")]
impl Float for f16 {
type Unsigned = u16;
const ZERO: Self = Self::from_bits(0);
const ONE: Self = Self::from_bits(float_one!(Self));
const TWO: Self = Self::from_bits(float_two!(Self));
const MAX: Self = Self::from_bits(float_max!(Self));
const MIN: Self = Self::from_bits(float_min!(Self));
const INFINITY: Self = Self::from_bits(Self::INFINITY_BITS);
const NEG_INFINITY: Self = Self::from_bits(Self::NEGATIVE_INFINITY_BITS);
const NAN: Self = Self::from_bits(float_nan!(Self));
const BITS: usize = mem::size_of::<Self>() * 8;
float_masks!(
float => Self,
sign_mask => 0x8000,
exponent_mask => 0x7C00,
hidden_bit_mask => 0x0400,
mantissa_mask => 0x03FF,
);
const EXPONENT_SIZE: i32 = 5;
const MANTISSA_SIZE: i32 = 10;
const EXPONENT_BIAS: i32 = 15 + Self::MANTISSA_SIZE;
const DENORMAL_EXPONENT: i32 = 1 - Self::EXPONENT_BIAS;
const MAX_EXPONENT: i32 = 0x1F - Self::EXPONENT_BIAS;
#[inline(always)]
fn to_bits(self) -> u16 {
f16::to_bits(self)
}
#[inline(always)]
fn from_bits(u: u16) -> f16 {
f16::from_bits(u)
}
#[inline(always)]
fn ln(self) -> f16 {
f16::from_f32(self.as_f32().ln())
}
#[inline(always)]
fn floor(self) -> f16 {
f16::from_f32(self.as_f32().floor())
}
#[inline(always)]
fn is_sign_positive(self) -> bool {
self.to_bits() & Self::SIGN_MASK == 0
}
#[inline(always)]
fn is_sign_negative(self) -> bool {
!self.is_sign_positive()
}
}
#[cfg(feature = "f16")]
impl Float for bf16 {
type Unsigned = u16;
const ZERO: Self = Self::from_bits(0);
const ONE: Self = Self::from_bits(float_one!(Self));
const TWO: Self = Self::from_bits(float_two!(Self));
const MAX: Self = Self::from_bits(float_max!(Self));
const MIN: Self = Self::from_bits(float_min!(Self));
const INFINITY: Self = Self::from_bits(Self::INFINITY_BITS);
const NEG_INFINITY: Self = Self::from_bits(Self::NEGATIVE_INFINITY_BITS);
const NAN: Self = Self::from_bits(float_nan!(Self));
const BITS: usize = mem::size_of::<Self>() * 8;
float_masks!(
float => Self,
sign_mask => 0x8000,
exponent_mask => 0x7F80,
hidden_bit_mask => 0x0080,
mantissa_mask => 0x007F,
);
const EXPONENT_SIZE: i32 = 8;
const MANTISSA_SIZE: i32 = 7;
const EXPONENT_BIAS: i32 = 127 + Self::MANTISSA_SIZE;
const DENORMAL_EXPONENT: i32 = 1 - Self::EXPONENT_BIAS;
const MAX_EXPONENT: i32 = 0xFF - Self::EXPONENT_BIAS;
#[inline(always)]
fn to_bits(self) -> u16 {
bf16::to_bits(self)
}
#[inline(always)]
fn from_bits(u: u16) -> bf16 {
bf16::from_bits(u)
}
#[inline(always)]
fn ln(self) -> bf16 {
bf16::from_f32(self.as_f32().ln())
}
#[inline(always)]
fn floor(self) -> bf16 {
bf16::from_f32(self.as_f32().floor())
}
#[inline(always)]
fn is_sign_positive(self) -> bool {
self.to_bits() & Self::SIGN_MASK == 0
}
#[inline(always)]
fn is_sign_negative(self) -> bool {
!self.is_sign_positive()
}
}
#[cfg(any(feature = "parse-floats", feature = "write-floats"))]
impl Float for f32 {
type Unsigned = u32;
float_literals!(f32);
float_masks!(
float => Self,
sign_mask => 0x80000000,
exponent_mask => 0x7F800000,
hidden_bit_mask => 0x00800000,
mantissa_mask => 0x007FFFFF,
);
const EXPONENT_SIZE: i32 = 8;
const MANTISSA_SIZE: i32 = 23;
const EXPONENT_BIAS: i32 = 127 + Self::MANTISSA_SIZE;
const DENORMAL_EXPONENT: i32 = 1 - Self::EXPONENT_BIAS;
const MAX_EXPONENT: i32 = 0xFF - Self::EXPONENT_BIAS;
#[inline(always)]
fn to_bits(self) -> u32 {
f32::to_bits(self)
}
#[inline(always)]
fn from_bits(u: u32) -> f32 {
f32::from_bits(u)
}
#[inline(always)]
fn ln(self) -> f32 {
#[cfg(feature = "std")]
return f32::ln(self);
#[cfg(not(feature = "std"))]
return libm::logf(self);
}
#[inline(always)]
fn floor(self) -> f32 {
#[cfg(feature = "std")]
return f32::floor(self);
#[cfg(not(feature = "std"))]
return libm::floorf(self);
}
#[inline(always)]
fn is_sign_positive(self) -> bool {
f32::is_sign_positive(self)
}
#[inline(always)]
fn is_sign_negative(self) -> bool {
f32::is_sign_negative(self)
}
}
#[cfg(any(feature = "parse-floats", feature = "write-floats"))]
impl Float for f64 {
type Unsigned = u64;
float_literals!(f64);
float_masks!(
float => Self,
sign_mask => 0x8000000000000000,
exponent_mask => 0x7FF0000000000000,
hidden_bit_mask => 0x0010000000000000,
mantissa_mask => 0x000FFFFFFFFFFFFF,
);
const EXPONENT_SIZE: i32 = 11;
const MANTISSA_SIZE: i32 = 52;
const EXPONENT_BIAS: i32 = 1023 + Self::MANTISSA_SIZE;
const DENORMAL_EXPONENT: i32 = 1 - Self::EXPONENT_BIAS;
const MAX_EXPONENT: i32 = 0x7FF - Self::EXPONENT_BIAS;
#[inline(always)]
fn to_bits(self) -> u64 {
f64::to_bits(self)
}
#[inline(always)]
fn from_bits(u: u64) -> f64 {
f64::from_bits(u)
}
#[inline(always)]
fn ln(self) -> f64 {
#[cfg(feature = "std")]
return f64::ln(self);
#[cfg(not(feature = "std"))]
return libm::logd(self);
}
#[inline(always)]
fn floor(self) -> f64 {
#[cfg(feature = "std")]
return f64::floor(self);
#[cfg(not(feature = "std"))]
return libm::floord(self);
}
#[inline(always)]
fn is_sign_positive(self) -> bool {
f64::is_sign_positive(self)
}
#[inline(always)]
fn is_sign_negative(self) -> bool {
f64::is_sign_negative(self)
}
}
// #[cfg(feature = "f128")]
// impl Float for f128 {
// type Unsigned = u128;
// float_literals!(f128);
// float_masks!(
// float => Self,
// sign_mask => 0x80000000000000000000000000000000,
// exponent_mask => 0x7FFF0000000000000000000000000000,
// hidden_bit_mask => 0x00010000000000000000000000000000,
// mantissa_mask => 0x0000FFFFFFFFFFFFFFFFFFFFFFFFFFFF,
// );
// const EXPONENT_SIZE: i32 = 15;
// const MANTISSA_SIZE: i32 = 112;
// const EXPONENT_BIAS: i32 = 16383 + Self::MANTISSA_SIZE;
// const DENORMAL_EXPONENT: i32 = 1 - Self::EXPONENT_BIAS;
// const MAX_EXPONENT: i32 = 0x7FFF - Self::EXPONENT_BIAS;
// }
