malachite_float/

lib.rs

// Copyright © 2026 Mikhail Hogrefe
//
// This file is part of Malachite.
//
// Malachite is free software: you can redistribute it and/or modify it under the terms of the GNU
// Lesser General Public License (LGPL) as published by the Free Software Foundation; either version
// 3 of the License, or (at your option) any later version. See <https://www.gnu.org/licenses/>.

//! This crate defines [`Float`]s, which are arbitrary-precision floating-point numbers.
//!
//! [`Float`]s are not yet feature-complete, but the functions that are implemented are thoroughly
//! tested and documented.
//!
//! # Complexity conventions
//! Functions in this crate are documented with worst-case time and additional-memory bounds,
//! following the conventions described in the `malachite-base`
//! [docs](https://docs.rs/malachite-base/latest/malachite_base/#complexity-conventions).
//!
//! # Demos and benchmarks
//! This crate comes with a `bin` target that can be used for running demos and benchmarks.
//! - Almost all of the public functions in this crate have an associated demo. Running a demo
//!   shows you a function's behavior on a large number of inputs. For example, to demo [`Float`]
//!   addition, you can use the following command:
//!   ```text
//!   cargo run --features bin_build --release -- -l 10000 -m exhaustive -d demo_float_add
//!   ```
//!   This command uses the `exhaustive` mode, which generates every possible input, generally
//!   starting with the simplest input and progressing to more complex ones. Another mode is
//!   `random`. The `-l` flag specifies how many inputs should be generated.
//! - You can use a similar command to run benchmarks. The following command benchmarks various
//!   [`Float`] addition implementations:
//!   ```text
//!   cargo run --features bin_build --release -- -l 1000000 -m random -b \
//!       benchmark_float_add_algorithms -o add-bench.gp
//!   ```
//!   This creates a file called add-bench.gp. You can use gnuplot to create an SVG from it like
//!   so:
//!   ```text
//!   gnuplot -e "set terminal svg; l \"add-bench.gp\"" > add-bench.svg
//!   ```
//!
//! The list of available demos and benchmarks is not documented anywhere; you must find them by
//! browsing through
//! [`bin_util/demo_and_bench`](https://github.com/mhogrefe/malachite/tree/master/malachite-float/src/bin_util/demo_and_bench).
//!
//! # Features
//! - `32_bit_limbs`: Sets the type of [`Limb`](malachite_nz#limbs) to [`u32`] instead of the
//!   default, [`u64`].
//! - `test_build`: A large proportion of the code in this crate is only used for testing. For a
//!   typical user, building this code would result in an unnecessarily long compilation time and
//!   an unnecessarily large binary. My solution is to only build this code when the `test_build`
//!   feature is enabled. If you want to run unit tests, you must enable `test_build`. However,
//!   doctests don't require it, since they only test the public interface.
//! - `bin_build`: This feature is used to build the code for demos and benchmarks, which also
//!   takes a long time to build. Enabling this feature also enables `test_build`.

#![forbid(unsafe_code)]
#![allow(
    unstable_name_collisions,
    clippy::assertions_on_constants,
    clippy::cognitive_complexity,
    clippy::many_single_char_names,
    clippy::range_plus_one,
    clippy::suspicious_arithmetic_impl,
    clippy::suspicious_op_assign_impl,
    clippy::too_many_arguments,
    clippy::type_complexity,
    clippy::upper_case_acronyms,
    clippy::multiple_bound_locations
)]
#![warn(
    clippy::cast_lossless,
    clippy::comparison_chain,
    clippy::explicit_into_iter_loop,
    clippy::explicit_iter_loop,
    clippy::filter_map_next,
    clippy::large_digit_groups,
    clippy::manual_filter_map,
    clippy::manual_find_map,
    clippy::map_flatten,
    clippy::map_unwrap_or,
    clippy::match_same_arms,
    clippy::missing_const_for_fn,
    clippy::mut_mut,
    clippy::needless_borrow,
    clippy::needless_continue,
    clippy::needless_pass_by_value,
    clippy::print_stdout,
    clippy::redundant_closure_for_method_calls,
    clippy::single_match_else,
    clippy::trait_duplication_in_bounds,
    clippy::type_repetition_in_bounds,
    clippy::uninlined_format_args,
    clippy::unused_self,
    clippy::if_not_else,
    clippy::manual_assert,
    clippy::range_plus_one,
    clippy::redundant_else,
    clippy::semicolon_if_nothing_returned,
    clippy::cloned_instead_of_copied,
    clippy::flat_map_option,
    clippy::unnecessary_wraps,
    clippy::unnested_or_patterns,
    clippy::use_self,
    clippy::trivially_copy_pass_by_ref
)]
#![cfg_attr(
    not(any(feature = "test_build", feature = "random", feature = "std")),
    no_std
)]

extern crate alloc;

#[macro_use]
extern crate malachite_base;

#[cfg(feature = "serde")]
#[macro_use]
extern crate serde;
#[macro_use]
mod macros;

#[cfg(feature = "test_build")]
extern crate itertools;

use core::cmp::Ordering::{self, *};
use malachite_base::num::basic::floats::PrimitiveFloat;
use malachite_base::num::basic::traits::{Infinity, NegativeInfinity};
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_q::Rational;

#[allow(clippy::type_repetition_in_bounds)]
fn emulate_finish<T: PrimitiveFloat>(mut result: Float, o: Ordering) -> T
where
    Float: PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    if !result.is_normal() {
        return T::exact_from(&result);
    }
    // The result was correctly rounded to MANTISSA_WIDTH + 1 bits with the ternary o; gradual
    // underflow is then emulated with a subnormalize pass, as in MPFR's recipe for emulating IEEE
    // arithmetic. The minimum normal exponent is converted from the scientific convention to the
    // raw convention.
    result.subnormalize_assign(o, T::MIN_NORMAL_EXPONENT + 1, Nearest);
    if result > T::MAX_FINITE {
        T::INFINITY
    } else if result < -T::MAX_FINITE {
        T::NEGATIVE_INFINITY
    } else {
        T::exact_from(&result)
    }
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_to_float_fn<T: PrimitiveFloat, F: Fn(Float, u64) -> (Float, Ordering)>(
    f: F,
    x: T,
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let (result, o) = f(x, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_to_float_pair_fn<
    T: PrimitiveFloat,
    F: Fn(Float, u64) -> (Float, Float, Ordering, Ordering),
>(
    f: F,
    x: T,
) -> (T, T)
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let (a, b, o_a, o_b) = f(x, T::MANTISSA_WIDTH + 1);
    (emulate_finish(a, o_a), emulate_finish(b, o_b))
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_rational_to_float_pair_fn<
    T: PrimitiveFloat,
    F: Fn(&Rational, u64) -> (Float, Float, Ordering, Ordering),
>(
    f: F,
    x: &Rational,
) -> (T, T)
where
    Float: PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let (a, b, o_a, o_b) = f(x, T::MANTISSA_WIDTH + 1);
    (emulate_finish(a, o_a), emulate_finish(b, o_b))
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_constant_to_float_fn<T: PrimitiveFloat, F: Fn(u64) -> (Float, Ordering)>(f: F) -> T
where
    Float: PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let (result, o) = f(T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_float_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(Float, Float, u64) -> (Float, Ordering),
>(
    f: F,
    x: T,
    y: T,
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let y = Float::from(y);
    let (result, o) = f(x, y, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_float_float_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(Float, Float, Float, u64) -> (Float, Ordering),
>(
    f: F,
    x: T,
    y: T,
    z: T,
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let y = Float::from(y);
    let z = Float::from(z);
    let (result, o) = f(x, y, z, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_float_float_float_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(Float, Float, Float, Float, u64) -> (Float, Ordering),
>(
    f: F,
    x: T,
    y: T,
    z: T,
    w: T,
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let y = Float::from(y);
    let z = Float::from(z);
    let w = Float::from(w);
    let (result, o) = f(x, y, z, w, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_slice_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(&[Float], u64) -> (Float, Ordering),
>(
    f: F,
    xs: &[T],
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let xs: alloc::vec::Vec<Float> = xs.iter().map(|&x| Float::from(x)).collect();
    let (result, o) = f(&xs, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_slice_float_slice_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(&[Float], &[Float], u64) -> (Float, Ordering),
>(
    f: F,
    xs: &[T],
    ys: &[T],
) -> T
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let xs: alloc::vec::Vec<Float> = xs.iter().map(|&x| Float::from(x)).collect();
    let ys: alloc::vec::Vec<Float> = ys.iter().map(|&y| Float::from(y)).collect();
    let (result, o) = f(&xs, &ys, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_to_float_and_i64_fn<
    T: PrimitiveFloat,
    F: Fn(Float, u64) -> (Float, Ordering, i64),
>(
    f: F,
    x: T,
) -> (T, i64)
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let (result, o, quo) = f(x, T::MANTISSA_WIDTH + 1);
    // the quotient bits are computed from the exact values, so they are unaffected by the
    // subnormalization of the remainder
    (emulate_finish(result, o), quo)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_float_float_to_float_and_i64_fn<
    T: PrimitiveFloat,
    F: Fn(Float, Float, u64) -> (Float, Ordering, i64),
>(
    f: F,
    x: T,
    y: T,
) -> (T, i64)
where
    Float: From<T> + PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let x = Float::from(x);
    let y = Float::from(y);
    let (result, o, quo) = f(x, y, T::MANTISSA_WIDTH + 1);
    // the quotient bits are computed from the exact values, so they are unaffected by the
    // subnormalization of the remainder
    (emulate_finish(result, o), quo)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_rational_to_float_fn<T: PrimitiveFloat, F: Fn(&Rational, u64) -> (Float, Ordering)>(
    f: F,
    x: &Rational,
) -> T
where
    Float: PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let (result, o) = f(x, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

#[allow(clippy::type_repetition_in_bounds)]
#[doc(hidden)]
pub fn emulate_rational_rational_to_float_fn<
    T: PrimitiveFloat,
    F: Fn(&Rational, &Rational, u64) -> (Float, Ordering),
>(
    f: F,
    x: &Rational,
    y: &Rational,
) -> T
where
    Float: PartialOrd<T>,
    for<'a> T: ExactFrom<&'a Float>,
{
    let (result, o) = f(x, y, T::MANTISSA_WIDTH + 1);
    emulate_finish(result, o)
}

/// Given the `(Float, Ordering)` result of an operation, determines whether an overflow occurred.
///
/// We're defining an overflow to occur whenever the actual result is outside the representable
/// finite range, and is rounded to either infinity or to the maximum or minimum representable
/// finite value. An overflow can present itself in four ways:
/// - The result is $\infty$ and the `Ordering` is `Greater`
/// - The result is $-\infty$ and the `Ordering` is `Less`
/// - The result is the largest finite value (of any `Float` with its precision) and the `Ordering`
///   is `Less`
/// - The result is the smallest (most negative) finite value (of any `Float` with its precision)
///   and the `Ordering` is `Greater`
///
/// # Worst-case complexity
/// $T(n) = O(n)$
///
/// $M(n) = O(1)$
///
/// where $T$ is time, $M$ is additional memory, and $n$ is `self.significant_bits()`.
///
/// # Examples
/// ```
/// use malachite_base::num::basic::traits::{Infinity, NegativeInfinity, One};
/// use malachite_float::{Float, test_overflow};
/// use std::cmp::Ordering::*;
///
/// assert!(test_overflow(&Float::INFINITY, Greater));
/// assert!(test_overflow(&Float::NEGATIVE_INFINITY, Less));
/// assert!(test_overflow(&Float::max_finite_value_with_prec(10), Less));
/// assert!(test_overflow(
///     &-Float::max_finite_value_with_prec(10),
///     Greater
/// ));
///
/// assert!(!test_overflow(&Float::INFINITY, Equal));
/// assert!(!test_overflow(&Float::ONE, Less));
/// ```
pub fn test_overflow(result: &Float, o: Ordering) -> bool {
    if o == Equal {
        return false;
    }
    *result == Float::INFINITY && o == Greater
        || *result == Float::NEGATIVE_INFINITY && o == Less
        || *result > 0u32 && result.abs_is_max_finite_value_with_prec() && o == Less
        || *result < 0u32 && result.abs_is_max_finite_value_with_prec() && o == Greater
}

/// Given the `(Float, Ordering)` result of an operation, determines whether an underflow occurred.
///
/// We're defining an underflow to occur whenever the actual result is outside the representable
/// finite range, and is rounded to zero, to the minimum positive value, or to the maximum negative
/// value. An underflow can present itself in four ways:
/// - The result is $0.0$ or $-0.0$ and the `Ordering` is `Less`
/// - The result is $0.0$ or $-0.0$ and the `Ordering` is `Greater`
/// - The result is the smallest positive value and the `Ordering` is `Greater`
/// - The result is the largest (least negative) negative value and the `Ordering` is `Less`
///
/// # Worst-case complexity
/// $T(n) = O(n)$
///
/// $M(n) = O(1)$
///
/// where $T$ is time, $M$ is additional memory, and $n$ is `self.significant_bits()`.
///
/// # Examples
/// ```
/// use malachite_base::num::basic::traits::{One, Zero};
/// use malachite_float::{Float, test_underflow};
/// use std::cmp::Ordering::*;
///
/// assert!(test_underflow(&Float::ZERO, Less));
/// assert!(test_underflow(&Float::ZERO, Greater));
/// assert!(test_underflow(&Float::min_positive_value_prec(10), Greater));
/// assert!(test_underflow(&-Float::min_positive_value_prec(10), Less));
///
/// assert!(!test_underflow(&Float::ZERO, Equal));
/// assert!(!test_underflow(&Float::ONE, Less));
/// ```
pub fn test_underflow(result: &Float, o: Ordering) -> bool {
    if o == Equal {
        return false;
    }
    *result == 0u32
        || *result > 0u32 && result.abs_is_min_positive_value() && o == Greater
        || *result < 0u32 && result.abs_is_min_positive_value() && o == Less
}

/// [`Float`], the crate's floating-point type, and everything defined on it.
#[macro_use]
pub mod float;
pub use float::{ComparableFloat, ComparableFloatRef, Float};
pub(crate) use float::{
    InnerFloat, TWICE_WIDTH, WIDTH_MINUS_1, floor_and_ceiling, significand_bits,
};

#[cfg(feature = "test_build")]
pub mod test_util;