/rust/registry/src/index.crates.io-6f17d22bba15001f/num-traits-0.2.19/src/lib.rs

Source (jump to first uncovered line)
// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Numeric traits for generic mathematics
//!
//! ## Compatibility
//!
//! The `num-traits` crate is tested for rustc 1.60 and greater.

#![doc(html_root_url = "https://docs.rs/num-traits/0.2")]
#![deny(unconditional_recursion)]
#![no_std]

// Need to explicitly bring the crate in for inherent float methods
#[cfg(feature = "std")]
extern crate std;

use core::fmt;
use core::num::Wrapping;
use core::ops::{Add, Div, Mul, Rem, Sub};
use core::ops::{AddAssign, DivAssign, MulAssign, RemAssign, SubAssign};

pub use crate::bounds::Bounded;
#[cfg(any(feature = "std", feature = "libm"))]
pub use crate::float::Float;
pub use crate::float::FloatConst;
// pub use real::{FloatCore, Real}; // NOTE: Don't do this, it breaks `use num_traits::*;`.
pub use crate::cast::{cast, AsPrimitive, FromPrimitive, NumCast, ToPrimitive};
pub use crate::identities::{one, zero, ConstOne, ConstZero, One, Zero};
pub use crate::int::PrimInt;
pub use crate::ops::bytes::{FromBytes, ToBytes};
pub use crate::ops::checked::{
    CheckedAdd, CheckedDiv, CheckedMul, CheckedNeg, CheckedRem, CheckedShl, CheckedShr, CheckedSub,
};
pub use crate::ops::euclid::{CheckedEuclid, Euclid};
pub use crate::ops::inv::Inv;
pub use crate::ops::mul_add::{MulAdd, MulAddAssign};
pub use crate::ops::saturating::{Saturating, SaturatingAdd, SaturatingMul, SaturatingSub};
pub use crate::ops::wrapping::{
    WrappingAdd, WrappingMul, WrappingNeg, WrappingShl, WrappingShr, WrappingSub,
};
pub use crate::pow::{checked_pow, pow, Pow};
pub use crate::sign::{abs, abs_sub, signum, Signed, Unsigned};

#[macro_use]
mod macros;

pub mod bounds;
pub mod cast;
pub mod float;
pub mod identities;
pub mod int;
pub mod ops;
pub mod pow;
pub mod real;
pub mod sign;

/// The base trait for numeric types, covering `0` and `1` values,
/// comparisons, basic numeric operations, and string conversion.
pub trait Num: PartialEq + Zero + One + NumOps {
    type FromStrRadixErr;

    /// Convert from a string and radix (typically `2..=36`).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_traits::Num;
    ///
    /// let result = <i32 as Num>::from_str_radix("27", 10);
    /// assert_eq!(result, Ok(27));
    ///
    /// let result = <i32 as Num>::from_str_radix("foo", 10);
    /// assert!(result.is_err());
    /// ```
    ///
    /// # Supported radices
    ///
    /// The exact range of supported radices is at the discretion of each type implementation. For
    /// primitive integers, this is implemented by the inherent `from_str_radix` methods in the
    /// standard library, which **panic** if the radix is not in the range from 2 to 36. The
    /// implementation in this crate for primitive floats is similar.
    ///
    /// For third-party types, it is suggested that implementations should follow suit and at least
    /// accept `2..=36` without panicking, but an `Err` may be returned for any unsupported radix.
    /// It's possible that a type might not even support the common radix 10, nor any, if string
    /// parsing doesn't make sense for that type.
    fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr>;
}

/// Generic trait for types implementing basic numeric operations
///
/// This is automatically implemented for types which implement the operators.
pub trait NumOps<Rhs = Self, Output = Self>:
    Add<Rhs, Output = Output>
    + Sub<Rhs, Output = Output>
    + Mul<Rhs, Output = Output>
    + Div<Rhs, Output = Output>
    + Rem<Rhs, Output = Output>
{
}

impl<T, Rhs, Output> NumOps<Rhs, Output> for T where
    T: Add<Rhs, Output = Output>
        + Sub<Rhs, Output = Output>
        + Mul<Rhs, Output = Output>
        + Div<Rhs, Output = Output>
        + Rem<Rhs, Output = Output>
{
}

/// The trait for `Num` types which also implement numeric operations taking
/// the second operand by reference.
///
/// This is automatically implemented for types which implement the operators.
pub trait NumRef: Num + for<'r> NumOps<&'r Self> {}
impl<T> NumRef for T where T: Num + for<'r> NumOps<&'r T> {}

/// The trait for `Num` references which implement numeric operations, taking the
/// second operand either by value or by reference.
///
/// This is automatically implemented for all types which implement the operators. It covers
/// every type implementing the operations though, regardless of it being a reference or
/// related to `Num`.
pub trait RefNum<Base>: NumOps<Base, Base> + for<'r> NumOps<&'r Base, Base> {}
impl<T, Base> RefNum<Base> for T where T: NumOps<Base, Base> + for<'r> NumOps<&'r Base, Base> {}

/// Generic trait for types implementing numeric assignment operators (like `+=`).
///
/// This is automatically implemented for types which implement the operators.
pub trait NumAssignOps<Rhs = Self>:
    AddAssign<Rhs> + SubAssign<Rhs> + MulAssign<Rhs> + DivAssign<Rhs> + RemAssign<Rhs>
{
}

impl<T, Rhs> NumAssignOps<Rhs> for T where
    T: AddAssign<Rhs> + SubAssign<Rhs> + MulAssign<Rhs> + DivAssign<Rhs> + RemAssign<Rhs>
{
}

/// The trait for `Num` types which also implement assignment operators.
///
/// This is automatically implemented for types which implement the operators.
pub trait NumAssign: Num + NumAssignOps {}
impl<T> NumAssign for T where T: Num + NumAssignOps {}

/// The trait for `NumAssign` types which also implement assignment operations
/// taking the second operand by reference.
///
/// This is automatically implemented for types which implement the operators.
pub trait NumAssignRef: NumAssign + for<'r> NumAssignOps<&'r Self> {}
impl<T> NumAssignRef for T where T: NumAssign + for<'r> NumAssignOps<&'r T> {}

macro_rules! int_trait_impl {
    ($name:ident for $($t:ty)*) => ($(
        impl $name for $t {
            type FromStrRadixErr = ::core::num::ParseIntError;
            #[inline]
            fn from_str_radix(s: &str, radix: u32)
                              -> Result<Self, ::core::num::ParseIntError>
            {
                <$t>::from_str_radix(s, radix)
            }
        }
    )*)
}
int_trait_impl!(Num for usize u8 u16 u32 u64 u128);
int_trait_impl!(Num for isize i8 i16 i32 i64 i128);

impl<T: Num> Num for Wrapping<T>
where
    Wrapping<T>: NumOps,
{
    type FromStrRadixErr = T::FromStrRadixErr;
    fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr> {
        T::from_str_radix(str, radix).map(Wrapping)
    }
}

#[derive(Debug)]
pub enum FloatErrorKind {
    Empty,
    Invalid,
}
// FIXME: core::num::ParseFloatError is stable in 1.0, but opaque to us,
// so there's not really any way for us to reuse it.
#[derive(Debug)]
pub struct ParseFloatError {
    pub kind: FloatErrorKind,
}

impl fmt::Display for ParseFloatError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let description = match self.kind {
            FloatErrorKind::Empty => "cannot parse float from empty string",
            FloatErrorKind::Invalid => "invalid float literal",
        };

        description.fmt(f)
    }
}

fn str_to_ascii_lower_eq_str(a: &str, b: &str) -> bool {
    a.len() == b.len()
        && a.bytes().zip(b.bytes()).all(|(a, b)| {
            let a_to_ascii_lower = a | (((b'A' <= a && a <= b'Z') as u8) << 5);
            a_to_ascii_lower == b
        })
}

// FIXME: The standard library from_str_radix on floats was deprecated, so we're stuck
// with this implementation ourselves until we want to make a breaking change.
// (would have to drop it from `Num` though)
macro_rules! float_trait_impl {
    ($name:ident for $($t:ident)*) => ($(
        impl $name for $t {
            type FromStrRadixErr = ParseFloatError;

            fn from_str_radix(src: &str, radix: u32)
                              -> Result<Self, Self::FromStrRadixErr>
            {
                use self::FloatErrorKind::*;
                use self::ParseFloatError as PFE;

                // Special case radix 10 to use more accurate standard library implementation
                if radix == 10 {
                    return src.parse().map_err(|_| PFE {
                        kind: if src.is_empty() { Empty } else { Invalid },
                    });
                }

                // Special values
                if str_to_ascii_lower_eq_str(src, "inf")
                    || str_to_ascii_lower_eq_str(src, "infinity")
                {
                    return Ok(core::$t::INFINITY);
                } else if str_to_ascii_lower_eq_str(src, "-inf")
                    || str_to_ascii_lower_eq_str(src, "-infinity")
                {
                    return Ok(core::$t::NEG_INFINITY);
                } else if str_to_ascii_lower_eq_str(src, "nan") {
                    return Ok(core::$t::NAN);
                } else if str_to_ascii_lower_eq_str(src, "-nan") {
                    return Ok(-core::$t::NAN);
                }

                fn slice_shift_char(src: &str) -> Option<(char, &str)> {
                    let mut chars = src.chars();
                    Some((chars.next()?, chars.as_str()))
                }

                let (is_positive, src) =  match slice_shift_char(src) {
                    None             => return Err(PFE { kind: Empty }),
                    Some(('-', ""))  => return Err(PFE { kind: Empty }),
                    Some(('-', src)) => (false, src),
                    Some((_, _))     => (true,  src),
                };

                // The significand to accumulate
                let mut sig = if is_positive { 0.0 } else { -0.0 };
                // Necessary to detect overflow
                let mut prev_sig = sig;
                let mut cs = src.chars().enumerate();
                // Exponent prefix and exponent index offset
                let mut exp_info = None::<(char, usize)>;

                // Parse the integer part of the significand
                for (i, c) in cs.by_ref() {
                    match c.to_digit(radix) {
                        Some(digit) => {
                            // shift significand one digit left
                            sig *= radix as $t;

                            // add/subtract current digit depending on sign
                            if is_positive {
                                sig += (digit as isize) as $t;
                            } else {
                                sig -= (digit as isize) as $t;
                            }

                            // Detect overflow by comparing to last value, except
                            // if we've not seen any non-zero digits.
                            if prev_sig != 0.0 {
                                if is_positive && sig <= prev_sig
                                    { return Ok(core::$t::INFINITY); }
                                if !is_positive && sig >= prev_sig
                                    { return Ok(core::$t::NEG_INFINITY); }

                                // Detect overflow by reversing the shift-and-add process
                                if is_positive && (prev_sig != (sig - digit as $t) / radix as $t)
                                    { return Ok(core::$t::INFINITY); }
                                if !is_positive && (prev_sig != (sig + digit as $t) / radix as $t)
                                    { return Ok(core::$t::NEG_INFINITY); }
                            }
                            prev_sig = sig;
                        },
                        None => match c {
                            'e' | 'E' | 'p' | 'P' => {
                                exp_info = Some((c, i + 1));
                                break;  // start of exponent
                            },
                            '.' => {
                                break;  // start of fractional part
                            },
                            _ => {
                                return Err(PFE { kind: Invalid });
                            },
                        },
                    }
                }

                // If we are not yet at the exponent parse the fractional
                // part of the significand
                if exp_info.is_none() {
                    let mut power = 1.0;
                    for (i, c) in cs.by_ref() {
                        match c.to_digit(radix) {
                            Some(digit) => {
                                // Decrease power one order of magnitude
                                power /= radix as $t;
                                // add/subtract current digit depending on sign
                                sig = if is_positive {
                                    sig + (digit as $t) * power
                                } else {
                                    sig - (digit as $t) * power
                                };
                                // Detect overflow by comparing to last value
                                if is_positive && sig < prev_sig
                                    { return Ok(core::$t::INFINITY); }
                                if !is_positive && sig > prev_sig
                                    { return Ok(core::$t::NEG_INFINITY); }
                                prev_sig = sig;
                            },
                            None => match c {
                                'e' | 'E' | 'p' | 'P' => {
                                    exp_info = Some((c, i + 1));
                                    break; // start of exponent
                                },
                                _ => {
                                    return Err(PFE { kind: Invalid });
                                },
                            },
                        }
                    }
                }

                // Parse and calculate the exponent
                let exp = match exp_info {
                    Some((c, offset)) => {
                        let base = match c {
                            'E' | 'e' if radix == 10 => 10.0,
                            'P' | 'p' if radix == 16 => 2.0,
                            _ => return Err(PFE { kind: Invalid }),
                        };

                        // Parse the exponent as decimal integer
                        let src = &src[offset..];
                        let (is_positive, exp) = match slice_shift_char(src) {
                            Some(('-', src)) => (false, src.parse::<usize>()),
                            Some(('+', src)) => (true,  src.parse::<usize>()),
                            Some((_, _))     => (true,  src.parse::<usize>()),
                            None             => return Err(PFE { kind: Invalid }),
                        };

                        #[cfg(feature = "std")]
                        fn pow(base: $t, exp: usize) -> $t {
                            Float::powi(base, exp as i32)
                        }
                        // otherwise uses the generic `pow` from the root

                        match (is_positive, exp) {
                            (true,  Ok(exp)) => pow(base, exp),
                            (false, Ok(exp)) => 1.0 / pow(base, exp),
                            (_, Err(_))      => return Err(PFE { kind: Invalid }),
                        }
                    },
                    None => 1.0, // no exponent
                };

                Ok(sig * exp)
            }
        }
    )*)
}
float_trait_impl!(Num for f32 f64);

/// A value bounded by a minimum and a maximum
///
///  If input is less than min then this returns min.
///  If input is greater than max then this returns max.
///  Otherwise this returns input.
///
/// **Panics** in debug mode if `!(min <= max)`.
#[inline]
pub fn clamp<T: PartialOrd>(input: T, min: T, max: T) -> T {
    debug_assert!(min <= max, "min must be less than or equal to max");
    if input < min {
        min
    } else if input > max {
        max
    } else {
        input
    }
}

/// A value bounded by a minimum value
///
///  If input is less than min then this returns min.
///  Otherwise this returns input.
///  `clamp_min(std::f32::NAN, 1.0)` preserves `NAN` different from `f32::min(std::f32::NAN, 1.0)`.
///
/// **Panics** in debug mode if `!(min == min)`. (This occurs if `min` is `NAN`.)
#[inline]
#[allow(clippy::eq_op)]
pub fn clamp_min<T: PartialOrd>(input: T, min: T) -> T {
    debug_assert!(min == min, "min must not be NAN");
    if input < min {
        min
    } else {
        input
    }
}

/// A value bounded by a maximum value
///
///  If input is greater than max then this returns max.
///  Otherwise this returns input.
///  `clamp_max(std::f32::NAN, 1.0)` preserves `NAN` different from `f32::max(std::f32::NAN, 1.0)`.
///
/// **Panics** in debug mode if `!(max == max)`. (This occurs if `max` is `NAN`.)
#[inline]
#[allow(clippy::eq_op)]
pub fn clamp_max<T: PartialOrd>(input: T, max: T) -> T {
    debug_assert!(max == max, "max must not be NAN");
    if input > max {
        max
    } else {
        input
    }
}

#[test]
fn clamp_test() {
    // Int test
    assert_eq!(1, clamp(1, -1, 2));
    assert_eq!(-1, clamp(-2, -1, 2));
    assert_eq!(2, clamp(3, -1, 2));
    assert_eq!(1, clamp_min(1, -1));
    assert_eq!(-1, clamp_min(-2, -1));
    assert_eq!(-1, clamp_max(1, -1));
    assert_eq!(-2, clamp_max(-2, -1));

    // Float test
    assert_eq!(1.0, clamp(1.0, -1.0, 2.0));
    assert_eq!(-1.0, clamp(-2.0, -1.0, 2.0));
    assert_eq!(2.0, clamp(3.0, -1.0, 2.0));
    assert_eq!(1.0, clamp_min(1.0, -1.0));
    assert_eq!(-1.0, clamp_min(-2.0, -1.0));
    assert_eq!(-1.0, clamp_max(1.0, -1.0));
    assert_eq!(-2.0, clamp_max(-2.0, -1.0));
    assert!(clamp(::core::f32::NAN, -1.0, 1.0).is_nan());
    assert!(clamp_min(::core::f32::NAN, 1.0).is_nan());
    assert!(clamp_max(::core::f32::NAN, 1.0).is_nan());
}

#[test]
#[should_panic]
#[cfg(debug_assertions)]
fn clamp_nan_min() {
    clamp(0., ::core::f32::NAN, 1.);
}

#[test]
#[should_panic]
#[cfg(debug_assertions)]
fn clamp_nan_max() {
    clamp(0., -1., ::core::f32::NAN);
}

#[test]
#[should_panic]
#[cfg(debug_assertions)]
fn clamp_nan_min_max() {
    clamp(0., ::core::f32::NAN, ::core::f32::NAN);
}

#[test]
#[should_panic]
#[cfg(debug_assertions)]
fn clamp_min_nan_min() {
    clamp_min(0., ::core::f32::NAN);
}

#[test]
#[should_panic]
#[cfg(debug_assertions)]
fn clamp_max_nan_max() {
    clamp_max(0., ::core::f32::NAN);
}

#[test]
fn from_str_radix_unwrap() {
    // The Result error must impl Debug to allow unwrap()

    let i: i32 = Num::from_str_radix("0", 10).unwrap();
    assert_eq!(i, 0);

    let f: f32 = Num::from_str_radix("0.0", 10).unwrap();
    assert_eq!(f, 0.0);
}

#[test]
fn from_str_radix_multi_byte_fail() {
    // Ensure parsing doesn't panic, even on invalid sign characters
    assert!(f32::from_str_radix("™0.2", 10).is_err());

    // Even when parsing the exponent sign
    assert!(f32::from_str_radix("0.2E™1", 10).is_err());
}

#[test]
fn from_str_radix_ignore_case() {
    assert_eq!(
        f32::from_str_radix("InF", 16).unwrap(),
        ::core::f32::INFINITY
    );
    assert_eq!(
        f32::from_str_radix("InfinitY", 16).unwrap(),
        ::core::f32::INFINITY
    );
    assert_eq!(
        f32::from_str_radix("-InF", 8).unwrap(),
        ::core::f32::NEG_INFINITY
    );
    assert_eq!(
        f32::from_str_radix("-InfinitY", 8).unwrap(),
        ::core::f32::NEG_INFINITY
    );
    assert!(f32::from_str_radix("nAn", 4).unwrap().is_nan());
    assert!(f32::from_str_radix("-nAn", 4).unwrap().is_nan());
}

#[test]
fn wrapping_is_num() {
    fn require_num<T: Num>(_: &T) {}
    require_num(&Wrapping(42_u32));
    require_num(&Wrapping(-42));
}

#[test]
fn wrapping_from_str_radix() {
    macro_rules! test_wrapping_from_str_radix {
        ($($t:ty)+) => {
            $(
                for &(s, r) in &[("42", 10), ("42", 2), ("-13.0", 10), ("foo", 10)] {
                    let w = Wrapping::<$t>::from_str_radix(s, r).map(|w| w.0);
                    assert_eq!(w, <$t as Num>::from_str_radix(s, r));
                }
            )+
        };
    }

    test_wrapping_from_str_radix!(usize u8 u16 u32 u64 isize i8 i16 i32 i64);
}

#[test]
fn check_num_ops() {
    fn compute<T: Num + Copy>(x: T, y: T) -> T {
        x * y / y % y + y - y
    }
    assert_eq!(compute(1, 2), 1)
}

#[test]
fn check_numref_ops() {
    fn compute<T: NumRef>(x: T, y: &T) -> T {
        x * y / y % y + y - y
    }
    assert_eq!(compute(1, &2), 1)
}

#[test]
fn check_refnum_ops() {
    fn compute<T: Copy>(x: &T, y: T) -> T
    where
        for<'a> &'a T: RefNum<T>,
    {
        &(&(&(&(x * y) / y) % y) + y) - y
    }
    assert_eq!(compute(&1, 2), 1)
}

#[test]
fn check_refref_ops() {
    fn compute<T>(x: &T, y: &T) -> T
    where
        for<'a> &'a T: RefNum<T>,
    {
        &(&(&(&(x * y) / y) % y) + y) - y
    }
    assert_eq!(compute(&1, &2), 1)
}

#[test]
fn check_numassign_ops() {
    fn compute<T: NumAssign + Copy>(mut x: T, y: T) -> T {
        x *= y;
        x /= y;
        x %= y;
        x += y;
        x -= y;
        x
    }
    assert_eq!(compute(1, 2), 1)
}

#[test]
fn check_numassignref_ops() {
    fn compute<T: NumAssignRef + Copy>(mut x: T, y: &T) -> T {
        x *= y;
        x /= y;
        x %= y;
        x += y;
        x -= y;
        x
    }
    assert_eq!(compute(1, &2), 1)
}

Coverage Report

Created: 2025-07-11 07:02

Line	Count	Source (jump to first uncovered line)
1		// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2		// file at the top-level directory of this distribution and at
3		// http://rust-lang.org/COPYRIGHT.
4		//
5		// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6		// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7		// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8		// option. This file may not be copied, modified, or distributed
9		// except according to those terms.
10
11		//! Numeric traits for generic mathematics
12		//!
13		//! ## Compatibility
14		//!
15		//! The `num-traits` crate is tested for rustc 1.60 and greater.
16
17		#![doc(html_root_url = "https://docs.rs/num-traits/0.2")]
18		#![deny(unconditional_recursion)]
19		#![no_std]
20
21		// Need to explicitly bring the crate in for inherent float methods
22		#[cfg(feature = "std")]
23		extern crate std;
24
25		use core::fmt;
26		use core::num::Wrapping;
27		use core::ops::{Add, Div, Mul, Rem, Sub};
28		use core::ops::{AddAssign, DivAssign, MulAssign, RemAssign, SubAssign};
29
30		pub use crate::bounds::Bounded;
31		#[cfg(any(feature = "std", feature = "libm"))]
32		pub use crate::float::Float;
33		pub use crate::float::FloatConst;
34		// pub use real::{FloatCore, Real}; // NOTE: Don't do this, it breaks `use num_traits::*;`.
35		pub use crate::cast::{cast, AsPrimitive, FromPrimitive, NumCast, ToPrimitive};
36		pub use crate::identities::{one, zero, ConstOne, ConstZero, One, Zero};
37		pub use crate::int::PrimInt;
38		pub use crate::ops::bytes::{FromBytes, ToBytes};
39		pub use crate::ops::checked::{
40		CheckedAdd, CheckedDiv, CheckedMul, CheckedNeg, CheckedRem, CheckedShl, CheckedShr, CheckedSub,
41		};
42		pub use crate::ops::euclid::{CheckedEuclid, Euclid};
43		pub use crate::ops::inv::Inv;
44		pub use crate::ops::mul_add::{MulAdd, MulAddAssign};
45		pub use crate::ops::saturating::{Saturating, SaturatingAdd, SaturatingMul, SaturatingSub};
46		pub use crate::ops::wrapping::{
47		WrappingAdd, WrappingMul, WrappingNeg, WrappingShl, WrappingShr, WrappingSub,
48		};
49		pub use crate::pow::{checked_pow, pow, Pow};
50		pub use crate::sign::{abs, abs_sub, signum, Signed, Unsigned};
51
52		#[macro_use]
53		mod macros;
54
55		pub mod bounds;
56		pub mod cast;
57		pub mod float;
58		pub mod identities;
59		pub mod int;
60		pub mod ops;
61		pub mod pow;
62		pub mod real;
63		pub mod sign;
64
65		/// The base trait for numeric types, covering `0` and `1` values,
66		/// comparisons, basic numeric operations, and string conversion.
67		pub trait Num: PartialEq + Zero + One + NumOps {
68		type FromStrRadixErr;
69
70		/// Convert from a string and radix (typically `2..=36`).
71		///
72		/// # Examples
73		///
74		/// ```rust
75		/// use num_traits::Num;
76		///
77		/// let result = <i32 as Num>::from_str_radix("27", 10);
78		/// assert_eq!(result, Ok(27));
79		///
80		/// let result = <i32 as Num>::from_str_radix("foo", 10);
81		/// assert!(result.is_err());
82		/// ```
83		///
84		/// # Supported radices
85		///
86		/// The exact range of supported radices is at the discretion of each type implementation. For
87		/// primitive integers, this is implemented by the inherent `from_str_radix` methods in the
88		/// standard library, which panic if the radix is not in the range from 2 to 36. The
89		/// implementation in this crate for primitive floats is similar.
90		///
91		/// For third-party types, it is suggested that implementations should follow suit and at least
92		/// accept `2..=36` without panicking, but an `Err` may be returned for any unsupported radix.
93		/// It's possible that a type might not even support the common radix 10, nor any, if string
94		/// parsing doesn't make sense for that type.
95		fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr>;
96		}
97
98		/// Generic trait for types implementing basic numeric operations
99		///
100		/// This is automatically implemented for types which implement the operators.
101		pub trait NumOps<Rhs = Self, Output = Self>:
102		Add<Rhs, Output = Output>
103		+ Sub<Rhs, Output = Output>
104		+ Mul<Rhs, Output = Output>
105		+ Div<Rhs, Output = Output>
106		+ Rem<Rhs, Output = Output>
107		{
108		}
109
110		impl<T, Rhs, Output> NumOps<Rhs, Output> for T where
111		T: Add<Rhs, Output = Output>
112		+ Sub<Rhs, Output = Output>
113		+ Mul<Rhs, Output = Output>
114		+ Div<Rhs, Output = Output>
115		+ Rem<Rhs, Output = Output>
116		{
117		}
118
119		/// The trait for `Num` types which also implement numeric operations taking
120		/// the second operand by reference.
121		///
122		/// This is automatically implemented for types which implement the operators.
123		pub trait NumRef: Num + for<'r> NumOps<&'r Self> {}
124		impl<T> NumRef for T where T: Num + for<'r> NumOps<&'r T> {}
125
126		/// The trait for `Num` references which implement numeric operations, taking the
127		/// second operand either by value or by reference.
128		///
129		/// This is automatically implemented for all types which implement the operators. It covers
130		/// every type implementing the operations though, regardless of it being a reference or
131		/// related to `Num`.
132		pub trait RefNum<Base>: NumOps<Base, Base> + for<'r> NumOps<&'r Base, Base> {}
133		impl<T, Base> RefNum<Base> for T where T: NumOps<Base, Base> + for<'r> NumOps<&'r Base, Base> {}
134
135		/// Generic trait for types implementing numeric assignment operators (like `+=`).
136		///
137		/// This is automatically implemented for types which implement the operators.
138		pub trait NumAssignOps<Rhs = Self>:
139		AddAssign<Rhs> + SubAssign<Rhs> + MulAssign<Rhs> + DivAssign<Rhs> + RemAssign<Rhs>
140		{
141		}
142
143		impl<T, Rhs> NumAssignOps<Rhs> for T where
144		T: AddAssign<Rhs> + SubAssign<Rhs> + MulAssign<Rhs> + DivAssign<Rhs> + RemAssign<Rhs>
145		{
146		}
147
148		/// The trait for `Num` types which also implement assignment operators.
149		///
150		/// This is automatically implemented for types which implement the operators.
151		pub trait NumAssign: Num + NumAssignOps {}
152		impl<T> NumAssign for T where T: Num + NumAssignOps {}
153
154		/// The trait for `NumAssign` types which also implement assignment operations
155		/// taking the second operand by reference.
156		///
157		/// This is automatically implemented for types which implement the operators.
158		pub trait NumAssignRef: NumAssign + for<'r> NumAssignOps<&'r Self> {}
159		impl<T> NumAssignRef for T where T: NumAssign + for<'r> NumAssignOps<&'r T> {}
160
161		macro_rules! int_trait_impl {
162		($name:ident for $($t:ty)*) => ($(
163		impl $name for $t {
164		type FromStrRadixErr = ::core::num::ParseIntError;
165		#[inline]
166	0	fn from_str_radix(s: &str, radix: u32)
167	0	-> Result<Self, ::core::num::ParseIntError>
168	0	{
169	0	<$t>::from_str_radix(s, radix)
170	0	} Unexecuted instantiation: <usize as num_traits::Num>::from_str_radix Unexecuted instantiation: <u8 as num_traits::Num>::from_str_radix Unexecuted instantiation: <u16 as num_traits::Num>::from_str_radix Unexecuted instantiation: <u32 as num_traits::Num>::from_str_radix Unexecuted instantiation: <u64 as num_traits::Num>::from_str_radix Unexecuted instantiation: <u128 as num_traits::Num>::from_str_radix Unexecuted instantiation: <isize as num_traits::Num>::from_str_radix Unexecuted instantiation: <i8 as num_traits::Num>::from_str_radix Unexecuted instantiation: <i16 as num_traits::Num>::from_str_radix Unexecuted instantiation: <i32 as num_traits::Num>::from_str_radix Unexecuted instantiation: <i64 as num_traits::Num>::from_str_radix Unexecuted instantiation: <i128 as num_traits::Num>::from_str_radix
171		}
172		)*)
173		}
174		int_trait_impl!(Num for usize u8 u16 u32 u64 u128);
175		int_trait_impl!(Num for isize i8 i16 i32 i64 i128);
176
177		impl<T: Num> Num for Wrapping<T>
178		where
179		Wrapping<T>: NumOps,
180		{
181		type FromStrRadixErr = T::FromStrRadixErr;
182	0	fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr> {
183	0	T::from_str_radix(str, radix).map(Wrapping)
184	0	}
185		}
186
187		#[derive(Debug)]
188		pub enum FloatErrorKind {
189		Empty,
190		Invalid,
191		}
192		// FIXME: core::num::ParseFloatError is stable in 1.0, but opaque to us,
193		// so there's not really any way for us to reuse it.
194		#[derive(Debug)]
195		pub struct ParseFloatError {
196		pub kind: FloatErrorKind,
197		}
198
199		impl fmt::Display for ParseFloatError {
200	0	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
201	0	let description = match self.kind {
202	0	FloatErrorKind::Empty => "cannot parse float from empty string",
203	0	FloatErrorKind::Invalid => "invalid float literal",
204		};
205
206	0	description.fmt(f)
207	0	}
208		}
209
210	0	fn str_to_ascii_lower_eq_str(a: &str, b: &str) -> bool {
211	0	a.len() == b.len()
212	0	&& a.bytes().zip(b.bytes()).all(\|(a, b)\| {
213	0	let a_to_ascii_lower = a \| (((b'A' <= a && a <= b'Z') as u8) << 5);
214	0	a_to_ascii_lower == b
215	0	})
216	0	}
217
218		// FIXME: The standard library from_str_radix on floats was deprecated, so we're stuck
219		// with this implementation ourselves until we want to make a breaking change.
220		// (would have to drop it from `Num` though)
221		macro_rules! float_trait_impl {
222		($name:ident for $($t:ident)*) => ($(
223		impl $name for $t {
224		type FromStrRadixErr = ParseFloatError;
225
226	0	fn from_str_radix(src: &str, radix: u32)
227	0	-> Result<Self, Self::FromStrRadixErr>
228	0	{
229		use self::FloatErrorKind::*;
230		use self::ParseFloatError as PFE;
231
232		// Special case radix 10 to use more accurate standard library implementation
233	0	if radix == 10 {
234	0	return src.parse().map_err(\|_\| PFE {
235	0	kind: if src.is_empty() { Empty } else { Invalid },
236	0	}); Unexecuted instantiation: <f32 as num_traits::Num>::from_str_radix::{closure#0} Unexecuted instantiation: <f64 as num_traits::Num>::from_str_radix::{closure#0}
237	0	}
238	0
239	0	// Special values
240	0	if str_to_ascii_lower_eq_str(src, "inf")
241	0	\|\| str_to_ascii_lower_eq_str(src, "infinity")
242		{
243	0	return Ok(core::$t::INFINITY);
244	0	} else if str_to_ascii_lower_eq_str(src, "-inf")
245	0	\|\| str_to_ascii_lower_eq_str(src, "-infinity")
246		{
247	0	return Ok(core::$t::NEG_INFINITY);
248	0	} else if str_to_ascii_lower_eq_str(src, "nan") {
249	0	return Ok(core::$t::NAN);
250	0	} else if str_to_ascii_lower_eq_str(src, "-nan") {
251	0	return Ok(-core::$t::NAN);
252	0	}
253
254	0	fn slice_shift_char(src: &str) -> Option<(char, &str)> {
255	0	let mut chars = src.chars();
256	0	Some((chars.next()?, chars.as_str()))
257	0	} Unexecuted instantiation: <f32 as num_traits::Num>::from_str_radix::slice_shift_char Unexecuted instantiation: <f64 as num_traits::Num>::from_str_radix::slice_shift_char
258
259	0	let (is_positive, src) = match slice_shift_char(src) {
260	0	None => return Err(PFE { kind: Empty }),
261	0	Some(('-', "")) => return Err(PFE { kind: Empty }),
262	0	Some(('-', src)) => (false, src),
263	0	Some((_, _)) => (true, src),
264		};
265
266		// The significand to accumulate
267	0	let mut sig = if is_positive { 0.0 } else { -0.0 };
268		// Necessary to detect overflow
269	0	let mut prev_sig = sig;
270	0	let mut cs = src.chars().enumerate();
271	0	// Exponent prefix and exponent index offset
272	0	let mut exp_info = None::<(char, usize)>;
273
274		// Parse the integer part of the significand
275	0	for (i, c) in cs.by_ref() {
276	0	match c.to_digit(radix) {
277	0	Some(digit) => {
278	0	// shift significand one digit left
279	0	sig *= radix as $t;
280	0
281	0	// add/subtract current digit depending on sign
282	0	if is_positive {
283	0	sig += (digit as isize) as $t;
284	0	} else {
285	0	sig -= (digit as isize) as $t;
286	0	}
287
288		// Detect overflow by comparing to last value, except
289		// if we've not seen any non-zero digits.
290	0	if prev_sig != 0.0 {
291	0	if is_positive && sig <= prev_sig
292	0	{ return Ok(core::$t::INFINITY); }
293	0	if !is_positive && sig >= prev_sig
294	0	{ return Ok(core::$t::NEG_INFINITY); }
295	0
296	0	// Detect overflow by reversing the shift-and-add process
297	0	if is_positive && (prev_sig != (sig - digit as $t) / radix as $t)
298	0	{ return Ok(core::$t::INFINITY); }
299	0	if !is_positive && (prev_sig != (sig + digit as $t) / radix as $t)
300	0	{ return Ok(core::$t::NEG_INFINITY); }
301	0	}
302	0	prev_sig = sig;
303		},
304	0	None => match c {
305		'e' \| 'E' \| 'p' \| 'P' => {
306	0	exp_info = Some((c, i + 1));
307	0	break; // start of exponent
308		},
309		'.' => {
310	0	break; // start of fractional part
311		},
312		_ => {
313	0	return Err(PFE { kind: Invalid });
314		},
315		},
316		}
317		}
318
319		// If we are not yet at the exponent parse the fractional
320		// part of the significand
321	0	if exp_info.is_none() {
322	0	let mut power = 1.0;
323	0	for (i, c) in cs.by_ref() {
324	0	match c.to_digit(radix) {
325	0	Some(digit) => {
326	0	// Decrease power one order of magnitude
327	0	power /= radix as $t;
328	0	// add/subtract current digit depending on sign
329	0	sig = if is_positive {
330	0	sig + (digit as $t) * power
331		} else {
332	0	sig - (digit as $t) * power
333		};
334		// Detect overflow by comparing to last value
335	0	if is_positive && sig < prev_sig
336	0	{ return Ok(core::$t::INFINITY); }
337	0	if !is_positive && sig > prev_sig
338	0	{ return Ok(core::$t::NEG_INFINITY); }
339	0	prev_sig = sig;
340		},
341	0	None => match c {
342		'e' \| 'E' \| 'p' \| 'P' => {
343	0	exp_info = Some((c, i + 1));
344	0	break; // start of exponent
345		},
346		_ => {
347	0	return Err(PFE { kind: Invalid });
348		},
349		},
350		}
351		}
352	0	}
353
354		// Parse and calculate the exponent
355	0	let exp = match exp_info {
356	0	Some((c, offset)) => {
357	0	let base = match c {
358	0	'E' \| 'e' if radix == 10 => 10.0,
359	0	'P' \| 'p' if radix == 16 => 2.0,
360	0	_ => return Err(PFE { kind: Invalid }),
361		};
362
363		// Parse the exponent as decimal integer
364	0	let src = &src[offset..];
365	0	let (is_positive, exp) = match slice_shift_char(src) {
366	0	Some(('-', src)) => (false, src.parse::<usize>()),
367	0	Some(('+', src)) => (true, src.parse::<usize>()),
368	0	Some((_, _)) => (true, src.parse::<usize>()),
369	0	None => return Err(PFE { kind: Invalid }),
370		};
371
372		#[cfg(feature = "std")]
373		fn pow(base: $t, exp: usize) -> $t {
374		Float::powi(base, exp as i32)
375		}
376		// otherwise uses the generic `pow` from the root
377
378	0	match (is_positive, exp) {
379	0	(true, Ok(exp)) => pow(base, exp),
380	0	(false, Ok(exp)) => 1.0 / pow(base, exp),
381	0	(_, Err(_)) => return Err(PFE { kind: Invalid }),
382		}
383		},
384	0	None => 1.0, // no exponent
385		};
386
387	0	Ok(sig * exp)
388	0	} Unexecuted instantiation: <f32 as num_traits::Num>::from_str_radix Unexecuted instantiation: <f64 as num_traits::Num>::from_str_radix
389		}
390		)*)
391		}
392		float_trait_impl!(Num for f32 f64);
393
394		/// A value bounded by a minimum and a maximum
395		///
396		/// If input is less than min then this returns min.
397		/// If input is greater than max then this returns max.
398		/// Otherwise this returns input.
399		///
400		/// Panics in debug mode if `!(min <= max)`.
401		#[inline]
402	0	pub fn clamp<T: PartialOrd>(input: T, min: T, max: T) -> T {
403	0	debug_assert!(min <= max, "min must be less than or equal to max");
404	0	if input < min {
405	0	min
406	0	} else if input > max {
407	0	max
408		} else {
409	0	input
410		}
411	0	}
412
413		/// A value bounded by a minimum value
414		///
415		/// If input is less than min then this returns min.
416		/// Otherwise this returns input.
417		/// `clamp_min(std::f32::NAN, 1.0)` preserves `NAN` different from `f32::min(std::f32::NAN, 1.0)`.
418		///
419		/// Panics in debug mode if `!(min == min)`. (This occurs if `min` is `NAN`.)
420		#[inline]
421		#[allow(clippy::eq_op)]
422	0	pub fn clamp_min<T: PartialOrd>(input: T, min: T) -> T {
423	0	debug_assert!(min == min, "min must not be NAN");
424	0	if input < min {
425	0	min
426		} else {
427	0	input
428		}
429	0	}
430
431		/// A value bounded by a maximum value
432		///
433		/// If input is greater than max then this returns max.
434		/// Otherwise this returns input.
435		/// `clamp_max(std::f32::NAN, 1.0)` preserves `NAN` different from `f32::max(std::f32::NAN, 1.0)`.
436		///
437		/// Panics in debug mode if `!(max == max)`. (This occurs if `max` is `NAN`.)
438		#[inline]
439		#[allow(clippy::eq_op)]
440	0	pub fn clamp_max<T: PartialOrd>(input: T, max: T) -> T {
441	0	debug_assert!(max == max, "max must not be NAN");
442	0	if input > max {
443	0	max
444		} else {
445	0	input
446		}
447	0	}
448
449		#[test]
450		fn clamp_test() {
451		// Int test
452		assert_eq!(1, clamp(1, -1, 2));
453		assert_eq!(-1, clamp(-2, -1, 2));
454		assert_eq!(2, clamp(3, -1, 2));
455		assert_eq!(1, clamp_min(1, -1));
456		assert_eq!(-1, clamp_min(-2, -1));
457		assert_eq!(-1, clamp_max(1, -1));
458		assert_eq!(-2, clamp_max(-2, -1));
459
460		// Float test
461		assert_eq!(1.0, clamp(1.0, -1.0, 2.0));
462		assert_eq!(-1.0, clamp(-2.0, -1.0, 2.0));
463		assert_eq!(2.0, clamp(3.0, -1.0, 2.0));
464		assert_eq!(1.0, clamp_min(1.0, -1.0));
465		assert_eq!(-1.0, clamp_min(-2.0, -1.0));
466		assert_eq!(-1.0, clamp_max(1.0, -1.0));
467		assert_eq!(-2.0, clamp_max(-2.0, -1.0));
468		assert!(clamp(::core::f32::NAN, -1.0, 1.0).is_nan());
469		assert!(clamp_min(::core::f32::NAN, 1.0).is_nan());
470		assert!(clamp_max(::core::f32::NAN, 1.0).is_nan());
471		}
472
473		#[test]
474		#[should_panic]
475		#[cfg(debug_assertions)]
476		fn clamp_nan_min() {
477		clamp(0., ::core::f32::NAN, 1.);
478		}
479
480		#[test]
481		#[should_panic]
482		#[cfg(debug_assertions)]
483		fn clamp_nan_max() {
484		clamp(0., -1., ::core::f32::NAN);
485		}
486
487		#[test]
488		#[should_panic]
489		#[cfg(debug_assertions)]
490		fn clamp_nan_min_max() {
491		clamp(0., ::core::f32::NAN, ::core::f32::NAN);
492		}
493
494		#[test]
495		#[should_panic]
496		#[cfg(debug_assertions)]
497		fn clamp_min_nan_min() {
498		clamp_min(0., ::core::f32::NAN);
499		}
500
501		#[test]
502		#[should_panic]
503		#[cfg(debug_assertions)]
504		fn clamp_max_nan_max() {
505		clamp_max(0., ::core::f32::NAN);
506		}
507
508		#[test]
509		fn from_str_radix_unwrap() {
510		// The Result error must impl Debug to allow unwrap()
511
512		let i: i32 = Num::from_str_radix("0", 10).unwrap();
513		assert_eq!(i, 0);
514
515		let f: f32 = Num::from_str_radix("0.0", 10).unwrap();
516		assert_eq!(f, 0.0);
517		}
518
519		#[test]
520		fn from_str_radix_multi_byte_fail() {
521		// Ensure parsing doesn't panic, even on invalid sign characters
522		assert!(f32::from_str_radix("™0.2", 10).is_err());
523
524		// Even when parsing the exponent sign
525		assert!(f32::from_str_radix("0.2E™1", 10).is_err());
526		}
527
528		#[test]
529		fn from_str_radix_ignore_case() {
530		assert_eq!(
531		f32::from_str_radix("InF", 16).unwrap(),
532		::core::f32::INFINITY
533		);
534		assert_eq!(
535		f32::from_str_radix("InfinitY", 16).unwrap(),
536		::core::f32::INFINITY
537		);
538		assert_eq!(
539		f32::from_str_radix("-InF", 8).unwrap(),
540		::core::f32::NEG_INFINITY
541		);
542		assert_eq!(
543		f32::from_str_radix("-InfinitY", 8).unwrap(),
544		::core::f32::NEG_INFINITY
545		);
546		assert!(f32::from_str_radix("nAn", 4).unwrap().is_nan());
547		assert!(f32::from_str_radix("-nAn", 4).unwrap().is_nan());
548		}
549
550		#[test]
551		fn wrapping_is_num() {
552		fn require_num<T: Num>(_: &T) {}
553		require_num(&Wrapping(42_u32));
554		require_num(&Wrapping(-42));
555		}
556
557		#[test]
558		fn wrapping_from_str_radix() {
559		macro_rules! test_wrapping_from_str_radix {
560		($($t:ty)+) => {
561		$(
562		for &(s, r) in &[("42", 10), ("42", 2), ("-13.0", 10), ("foo", 10)] {
563		let w = Wrapping::<$t>::from_str_radix(s, r).map(\|w\| w.0);
564		assert_eq!(w, <$t as Num>::from_str_radix(s, r));
565		}
566		)+
567		};
568		}
569
570		test_wrapping_from_str_radix!(usize u8 u16 u32 u64 isize i8 i16 i32 i64);
571		}
572
573		#[test]
574		fn check_num_ops() {
575		fn compute<T: Num + Copy>(x: T, y: T) -> T {
576		x * y / y % y + y - y
577		}
578		assert_eq!(compute(1, 2), 1)
579		}
580
581		#[test]
582		fn check_numref_ops() {
583		fn compute<T: NumRef>(x: T, y: &T) -> T {
584		x * y / y % y + y - y
585		}
586		assert_eq!(compute(1, &2), 1)
587		}
588
589		#[test]
590		fn check_refnum_ops() {
591		fn compute<T: Copy>(x: &T, y: T) -> T
592		where
593		for<'a> &'a T: RefNum<T>,
594		{
595		&(&(&(&(x * y) / y) % y) + y) - y
596		}
597		assert_eq!(compute(&1, 2), 1)
598		}
599
600		#[test]
601		fn check_refref_ops() {
602		fn compute<T>(x: &T, y: &T) -> T
603		where
604		for<'a> &'a T: RefNum<T>,
605		{
606		&(&(&(&(x * y) / y) % y) + y) - y
607		}
608		assert_eq!(compute(&1, &2), 1)
609		}
610
611		#[test]
612		fn check_numassign_ops() {
613		fn compute<T: NumAssign + Copy>(mut x: T, y: T) -> T {
614		x *= y;
615		x /= y;
616		x %= y;
617		x += y;
618		x -= y;
619		x
620		}
621		assert_eq!(compute(1, 2), 1)
622		}
623
624		#[test]
625		fn check_numassignref_ops() {
626		fn compute<T: NumAssignRef + Copy>(mut x: T, y: &T) -> T {
627		x *= y;
628		x /= y;
629		x %= y;
630		x += y;
631		x -= y;
632		x
633		}
634		assert_eq!(compute(1, &2), 1)
635		}