Struct ComparableFloat 

pub struct ComparableFloat(pub Float);

ComparableFloat is a wrapper around a Float, taking the Float by value.

CompatableFloat has different comparison behavior than Float. See the Float documentation for its comparison behavior, which is largely derived from the IEEE 754 specification; the ComparableFloat behavior, on the other hand, is more mathematically well-behaved, and respects the principle that equality should be the finest equivalence relation: that is, that two equal objects should not be different in any way.

To be more specific: when a Float is wrapped in a ComparableFloat,

• NaN is not equal to any other Float, but equal to itself;
• Positive and negative zero are not equal to each other;
• Ordering is total. Negative zero is ordered to be smaller than positive zero, and NaN is arbitrarily ordered to be between the two zeros;
• Two Floats with different precisions but representing the same value are unequal, and the one with the greater precision is ordered to be larger;
• The hashing function is compatible with equality.

The analogous wrapper for primitive floats is NiceFloat. However, NiceFloat also facilitates better string conversion, something that isn’t necessary for Floats

ComparableFloat owns its float. This is useful in many cases, for example if you want to use Floats as keys in a hash map. In other situations, it is better to use ComparableFloatRef, which only has a reference to its float.

Tuple Fields

0: Float

Implementations

impl ComparableFloat

pub const fn as_ref(&self) -> ComparableFloatRef<'_>

Methods from Deref<Target = Float>

pub fn abs_negative_zero_ref(&self) -> Self

If self is negative zero, returns positive zero; otherwise, returns self, taking self by reference.

This function does not overflow or underflow.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, Zero,
};
use malachite_float::{ComparableFloat, Float};

assert_eq!(
    ComparableFloat(Float::NAN.abs_negative_zero_ref()),
    ComparableFloat(Float::NAN)
);
assert_eq!(Float::INFINITY.abs_negative_zero_ref(), Float::INFINITY);
assert_eq!(
    Float::NEGATIVE_INFINITY.abs_negative_zero_ref(),
    Float::NEGATIVE_INFINITY
);
assert_eq!(
    ComparableFloat(Float::ZERO.abs_negative_zero_ref()),
    ComparableFloat(Float::ZERO)
);
assert_eq!(
    ComparableFloat(Float::NEGATIVE_ZERO.abs_negative_zero_ref()),
    ComparableFloat(Float::ZERO)
);
assert_eq!(Float::ONE.abs_negative_zero_ref(), Float::ONE);
assert_eq!(
    Float::NEGATIVE_ONE.abs_negative_zero_ref(),
    Float::NEGATIVE_ONE
);

pub fn add_prec_round_ref_val( &self, other: Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Adds two Floats, rounding the result to the specified precision and with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\infty,-\infty,p,m)=f(-\infty,\infty,p,m)= \text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,p,m)=0.0$
• $f(-0.0,-0.0,p,m)=-0.0$
• $f(0.0,-0.0,p,m)=f(-0.0,0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,-0.0,p,m)=f(-0.0,0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,-x,p,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,-x,p,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::add_prec_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::add_round_ref_val instead. If both of these things are true, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact addition.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_prec_round_val_ref(&Float::from(E), 5, Floor);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_val(Float::from(E), 5, Ceiling);
assert_eq!(sum.to_string(), "6.0");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_prec_round_ref_val(Float::from(E), 5, Nearest);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_val(Float::from(E), 20, Floor);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_val(Float::from(E), 20, Ceiling);
assert_eq!(sum.to_string(), "5.85988");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_prec_round_ref_val(Float::from(E), 20, Nearest);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

pub fn add_prec_round_ref_ref( &self, other: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Adds two Floats, rounding the result to the specified precision and with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\infty,-\infty,p,m)=f(-\infty,\infty,p,m)= \text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,p,m)=0.0$
• $f(-0.0,-0.0,p,m)=-0.0$
• $f(0.0,-0.0,p,m)=f(-0.0,0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,-0.0,p,m)=f(-0.0,0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,-x,p,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,-x,p,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::add_prec_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::add_round_ref_ref instead. If both of these things are true, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact addition.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 5, Floor);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 5, Ceiling);
assert_eq!(sum.to_string(), "6.0");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 5, Nearest);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 20, Floor);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 20, Ceiling);
assert_eq!(sum.to_string(), "5.85988");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_prec_round_ref_ref(&Float::from(E), 20, Nearest);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

pub fn add_prec_ref_val(&self, other: Self, prec: u64) -> (Self, Ordering)

Adds two Floats, rounding the result to the nearest value of the specified precision. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the sum is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\infty,-\infty,p)=f(-\infty,\infty,p)=\text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p)=f(x,-\infty,p)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,p)=0.0$
• $f(-0.0,-0.0,p)=-0.0$
• $f(0.0,-0.0,p)=f(-0.0,0.0,p)=0.0$
• $f(x,-x,p)=0.0$ if $x$ is finite and nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::add_prec_round_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = (&Float::from(PI)).add_prec_ref_val(Float::from(E), 5);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = (&Float::from(PI)).add_prec_ref_val(Float::from(E), 20);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

pub fn add_prec_ref_ref(&self, other: &Self, prec: u64) -> (Self, Ordering)

Adds two Floats, rounding the result to the nearest value of the specified precision. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the sum is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\infty,-\infty,p)=f(-\infty,\infty,p)=\text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p)=f(x,-\infty,p)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,p)=0.0$
• $f(-0.0,-0.0,p)=-0.0$
• $f(0.0,-0.0,p)=f(-0.0,0.0,p)=0.0$
• $f(x,-x,p)=0.0$ if $x$ is finite and nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::add_prec_round_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = (&Float::from(PI)).add_prec_ref_ref(&Float::from(E), 5);
assert_eq!(sum.to_string(), "5.8");
assert_eq!(o, Less);

let (sum, o) = (&Float::from(PI)).add_prec_ref_ref(&Float::from(E), 20);
assert_eq!(sum.to_string(), "5.85987");
assert_eq!(o, Less);

pub fn add_round_ref_val( &self, other: Self, rm: RoundingMode, ) -> (Self, Ordering)

Adds two Floats, rounding the result with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\infty,-\infty,m)=f(-\infty,\infty,m)= \text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=f(x,-\infty,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,m)=0.0$
• $f(-0.0,-0.0,m)=-0.0$
• $f(0.0,-0.0,m)=f(-0.0,0.0,m)=0.0$ if $m$ is not Floor
• $f(0.0,-0.0,m)=f(-0.0,0.0,m)=-0.0$ if $m$ is Floor
• $f(0.0,x,m)=f(x,0.0,m)=f(-0.0,x,m)=f(x,-0.0,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,-x,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,-x,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::add_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is self.significant_bits().

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = (&Float::from(PI)).add_round_ref_val(Float::from(E), Floor);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

let (sum, o) = (&Float::from(PI)).add_round_ref_val(Float::from(E), Ceiling);
assert_eq!(sum.to_string(), "5.859874482048839");
assert_eq!(o, Greater);

let (sum, o) = (&Float::from(PI)).add_round_ref_val(Float::from(E), Nearest);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

pub fn add_round_ref_ref( &self, other: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Adds two Floats, rounding the result with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\infty,-\infty,m)=f(-\infty,\infty,m)= \text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=f(x,-\infty,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0.0,m)=0.0$
• $f(-0.0,-0.0,m)=-0.0$
• $f(0.0,-0.0,m)=f(-0.0,0.0,m)=0.0$ if $m$ is not Floor
• $f(0.0,-0.0,m)=f(-0.0,0.0,m)=-0.0$ if $m$ is Floor
• $f(0.0,x,m)=f(x,0.0,m)=f(-0.0,x,m)=f(x,-0.0,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,-x,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,-x,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::add_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using + instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_round_ref_ref(&Float::from(E), Floor);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_round_ref_ref(&Float::from(E), Ceiling);
assert_eq!(sum.to_string(), "5.859874482048839");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_round_ref_ref(&Float::from(E), Nearest);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

pub fn add_rational_prec_round_ref_val( &self, other: Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$
• $f(-\infty,x,p,m)=-\infty$
• $f(0.0,0,p,m)=0.0$
• $f(-0.0,0,p,m)=-0.0$
• $f(x,-x,p,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,-x,p,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::add_rational_prec_ref_val instead. If you know that your target precision is the precision of the Float input, consider using Float::add_rational_round_ref_val instead. If both of these things are true, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact addition.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(sum.to_string(), "3.4");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(sum.to_string(), "3.5");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(sum.to_string(), "3.5");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(sum.to_string(), "3.474922");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(sum.to_string(), "3.474926");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(sum.to_string(), "3.474926");
assert_eq!(o, Greater);

pub fn add_rational_prec_round_ref_ref( &self, other: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float and the Rational are both taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$
• $f(-\infty,x,p,m)=-\infty$
• $f(0.0,0,p,m)=0.0$
• $f(-0.0,0,p,m)=-0.0$
• $f(x,-x,p,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,-x,p,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::add_rational_prec_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using Float::add_rational_round_ref_ref instead. If both of these things are true, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact addition.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(sum.to_string(), "3.4");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(sum.to_string(), "3.5");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(sum.to_string(), "3.5");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(sum.to_string(), "3.474922");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(sum.to_string(), "3.474926");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(sum.to_string(), "3.474926");
assert_eq!(o, Greater);

pub fn add_rational_prec_ref_val( &self, other: Rational, prec: u64, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result to the nearest value of the specified precision. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the sum is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$
• $f(-\infty,x,p)=-\infty$
• $f(0.0,0,p)=0.0$
• $f(-0.0,0,p)=-0.0$
• $f(x,-x,p)=0.0$ if $x$ is nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::add_rational_prec_round_ref_val instead. If you know that your target precision is the precision of the Float input, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_rational_prec_ref_val(Rational::exact_from(1.5), 5);
assert_eq!(sum.to_string(), "4.8");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_ref_val(Rational::exact_from(1.5), 20);
assert_eq!(sum.to_string(), "4.641594");
assert_eq!(o, Greater);

pub fn add_rational_prec_ref_ref( &self, other: &Rational, prec: u64, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result to the nearest value of the specified precision. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the sum is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$
• $f(-\infty,x,p)=-\infty$
• $f(0.0,0,p)=0.0$
• $f(-0.0,0,p)=-0.0$
• $f(x,-x,p)=0.0$ if $x$ is nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::add_rational_prec_round_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).add_rational_prec_ref_ref(&Rational::exact_from(1.5), 5);
assert_eq!(sum.to_string(), "4.8");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).add_rational_prec_ref_ref(&Rational::exact_from(1.5), 20);
assert_eq!(sum.to_string(), "4.641594");
assert_eq!(o, Greater);

pub fn add_rational_round_ref_val( &self, other: Rational, rm: RoundingMode, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result with the specified rounding mode. The Float is taken by reference and the Float by value. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0,m)=0.0$
• $f(-0.0,0,m)=-0.0$
• $f(0.0,x,m)=f(x,0,m)=f(-0.0,x,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,-x,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,-x,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::add_rational_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) =
    Float::from(PI).add_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(sum.to_string(), "3.474925986923125");
assert_eq!(o, Less);

let (sum, o) =
    Float::from(PI).add_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(sum.to_string(), "3.474925986923129");
assert_eq!(o, Greater);

let (sum, o) =
    Float::from(PI).add_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(sum.to_string(), "3.474925986923125");
assert_eq!(o, Less);

pub fn add_rational_round_ref_ref( &self, other: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Adds a Float and a Rational, rounding the result with the specified rounding mode. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded sum is less than, equal to, or greater than the exact sum. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x+y+\varepsilon. $$

• If $x+y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x+y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x+y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x+y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x+y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0,m)=0.0$
• $f(-0.0,0,m)=-0.0$
• $f(0.0,x,m)=f(x,0,m)=f(-0.0,x,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,-x,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,-x,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::add_rational_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using + instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) =
    Float::from(PI).add_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(sum.to_string(), "3.474925986923125");
assert_eq!(o, Less);

let (sum, o) =
    Float::from(PI).add_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(sum.to_string(), "3.474925986923129");
assert_eq!(o, Greater);

let (sum, o) =
    Float::from(PI).add_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(sum.to_string(), "3.474925986923125");
assert_eq!(o, Less);

pub fn agm_prec_round_ref_val( &self, other: Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result to the specified precision and with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p+1}$.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(-\infty,x,p,m)=f(x,-\infty,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,p,m)=\infty$
• $f(\pm0.0,x,p,m)=f(x,\pm0.0,p,m)=0.0$
• $f(x,y,p,m)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::agm_prec_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::agm_round_ref_val instead. If both of these things are true, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but the two Float arguments are positive and distinct (and the exact result is therefore irrational).

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) = Float::from(24).agm_prec_round_val_ref(&Float::from(6), 5, Floor);
assert_eq!(agm.to_string(), "13.0");
assert_eq!(o, Less);

let (agm, o) = Float::from(24).agm_prec_round_ref_val(Float::from(6), 5, Ceiling);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_val(Float::from(6), 5, Nearest);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_val(Float::from(6), 20, Floor);
assert_eq!(agm.to_string(), "13.45816");
assert_eq!(o, Less);

let (agm, o) = Float::from(24).agm_prec_round_ref_val(Float::from(6), 20, Ceiling);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_val(Float::from(6), 20, Nearest);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

pub fn agm_prec_round_ref_ref( &self, other: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result to the specified precision and with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p+1}$.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(-\infty,x,p,m)=f(x,-\infty,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,p,m)=\infty$
• $f(\pm0.0,x,p,m)=f(x,\pm0.0,p,m)=0.0$
• $f(x,y,p,m)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::agm_prec_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::agm_round_ref_ref instead. If both of these things are true, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but the two Float arguments are positive and distinct (and the exact result is therefore irrational).

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 5, Floor);
assert_eq!(agm.to_string(), "13.0");
assert_eq!(o, Less);

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 5, Ceiling);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 5, Nearest);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 20, Floor);
assert_eq!(agm.to_string(), "13.45816");
assert_eq!(o, Less);

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 20, Ceiling);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

let (agm, o) = Float::from(24).agm_prec_round_ref_ref(&Float::from(6), 20, Nearest);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

This is mpfr_agm from agm.c, MPFR 4.3.0.

pub fn agm_prec_ref_val(&self, other: Self, prec: u64) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result to the nearest value of the specified precision. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the agm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(-\infty,x,p)=f(x,-\infty,p)=\text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,p)=\infty$
• $f(\pm0.0,x,p)=f(x,\pm0.0,p)=0.0$
• $f(x,y,p)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::agm_prec_round_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) = (&Float::from(24)).agm_prec_ref_val(Float::from(6), 5);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = (&Float::from(24)).agm_prec_ref_val(Float::from(6), 20);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

pub fn agm_prec_ref_ref(&self, other: &Self, prec: u64) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result to the nearest value of the specified precision. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the agm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(-\infty,x,p)=f(x,-\infty,p)=\text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,p)=\infty$
• $f(\pm0.0,x,p)=f(x,\pm0.0,p)=0.0$
• $f(x,y,p)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::agm_prec_round_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) = (&Float::from(24)).agm_prec_ref_ref(&Float::from(6), 5);
assert_eq!(agm.to_string(), "13.5");
assert_eq!(o, Greater);

let (agm, o) = (&Float::from(24)).agm_prec_ref_ref(&Float::from(6), 20);
assert_eq!(agm.to_string(), "13.45818");
assert_eq!(o, Greater);

pub fn agm_round_ref_val( &self, other: Self, rm: RoundingMode, ) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(-\infty,x,m)=f(x,-\infty,m)=\text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,m)=\infty$
• $f(\pm0.0,x,m)=f(x,\pm0.0,m)=0.0$
• $f(x,y,m)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::agm_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is self.significant_bits().

Panics

Panics if rm is Exact but the two Float arguments are positive and distinct (and the exact result is therefore irrational).

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) =
    (&Float::from_unsigned_prec(24u8, 100).0).agm_round_ref_val(Float::from(6), Floor);
assert_eq!(agm.to_string(), "13.45817148172561542076681315696");
assert_eq!(o, Less);

let (agm, o) =
    (&Float::from_unsigned_prec(24u8, 100).0).agm_round_ref_val(Float::from(6), Ceiling);
assert_eq!(agm.to_string(), "13.45817148172561542076681315698");
assert_eq!(o, Greater);

let (agm, o) =
    (&Float::from_unsigned_prec(24u8, 100).0).agm_round_ref_val(Float::from(6), Nearest);
assert_eq!(agm.to_string(), "13.45817148172561542076681315698");
assert_eq!(o, Greater);

pub fn agm_round_ref_ref( &self, other: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Computes the arithmetic-geometric mean (AGM) of two Floats, rounding the result with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded AGM is less than, equal to, or greater than the exact AGM. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = \text{AGM}(x,y)+\varepsilon =\frac{\pi}{2}\left(\int_0^{\frac{\pi}{2}}\frac{\mathrm{d}\theta} {\sqrt{x^2\cos^2\theta+y^2\sin^2\theta}}\right)^{-1}+\varepsilon. $$

• If $\text{AGM}(x,y)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $\text{AGM}(x,y)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \text{AGM}(x,y)\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(-\infty,x,m)=f(x,-\infty,m)=\text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\text{NaN}$ if $x\neq\infty$
• $f(\infty,\infty,m)=\infty$
• $f(\pm0.0,x,m)=f(x,\pm0.0,m)=0.0$
• $f(x,y,m)=\text{NaN}$ if $x<0$ or $y<0$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::agm_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using Float::agm instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the two Float arguments are positive and distinct (and the exact result is therefore irrational).

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (agm, o) = Float::from_unsigned_prec(24u8, 100)
    .0
    .agm_round_ref_ref(&Float::from(6), Floor);
assert_eq!(agm.to_string(), "13.45817148172561542076681315696");
assert_eq!(o, Less);

let (agm, o) = Float::from_unsigned_prec(24u8, 100)
    .0
    .agm_round_ref_ref(&Float::from(6), Ceiling);
assert_eq!(agm.to_string(), "13.45817148172561542076681315698");
assert_eq!(o, Greater);

let (agm, o) = Float::from_unsigned_prec(24u8, 100)
    .0
    .agm_round_ref_ref(&Float::from(6), Nearest);
assert_eq!(agm.to_string(), "13.45817148172561542076681315698");
assert_eq!(o, Greater);

pub fn div_prec_round_ref_val( &self, other: Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Divides two Floats, rounding the result to the specified precision and with the specified rounding mode. The first Float is are taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,p,m)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,p,m)=\infty$ if $x>0.0$
• $f(x,0.0,p,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,p,m)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,p,m)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,p,m)=-\infty$ if $x>0.0$
• $f(x,-0.0,p,m)=\infty$ if $x<0.0$
• $f(0.0,x,p,m)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,p,m)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p,m)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,p,m)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::div_prec_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::div_round_ref_val instead. If both of these things are true, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact division.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 5, Floor);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 5, Ceiling);
assert_eq!(quotient.to_string(), "1.19");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 5, Nearest);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 20, Floor);
assert_eq!(quotient.to_string(), "1.155725");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 20, Ceiling);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_prec_round_ref_val(Float::from(E), 20, Nearest);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

pub fn div_prec_round_ref_ref( &self, other: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Divides two Floats, rounding the result to the specified precision and with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,p,m)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,p,m)=\infty$ if $x>0.0$
• $f(x,0.0,p,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,p,m)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,p,m)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,p,m)=-\infty$ if $x>0.0$
• $f(x,-0.0,p,m)=\infty$ if $x<0.0$
• $f(0.0,x,p,m)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,p,m)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p,m)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,p,m)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::div_prec_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::div_round_ref_ref instead. If both of these things are true, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact division.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 5, Floor);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 5, Ceiling);
assert_eq!(quotient.to_string(), "1.19");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 5, Nearest);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 20, Floor);
assert_eq!(quotient.to_string(), "1.155725");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 20, Ceiling);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_prec_round_ref_ref(&Float::from(E), 20, Nearest);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

pub fn div_prec_ref_val(&self, other: Self, prec: u64) -> (Self, Ordering)

Divides two Floats, rounding the result to the nearest value of the specified precision. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the quotient is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,p)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,p)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,p)=\infty$ if $x>0.0$
• $f(x,0.0,p)=-\infty$ if $x<0.0$
• $f(-\infty,x,p)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,p)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,p)=-\infty$ if $x>0.0$
• $f(x,-0.0,p)=\infty$ if $x<0.0$
• $f(0.0,x,p)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,p)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,p)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::div_prec_round_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_prec_ref_val(Float::from(E), 5);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_ref_val(Float::from(E), 20);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

pub fn div_prec_ref_ref(&self, other: &Self, prec: u64) -> (Self, Ordering)

Divides two Floats, rounding the result to the nearest value of the specified precision. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the quotient is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,p)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,p)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,p)=\infty$ if $x>0.0$
• $f(x,0.0,p)=-\infty$ if $x<0.0$
• $f(-\infty,x,p)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,p)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,p)=-\infty$ if $x>0.0$
• $f(x,-0.0,p)=\infty$ if $x<0.0$
• $f(0.0,x,p)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,p)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,p)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::div_prec_round_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_prec_ref_ref(&Float::from(E), 5);
assert_eq!(quotient.to_string(), "1.12");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_prec_ref_ref(&Float::from(E), 20);
assert_eq!(quotient.to_string(), "1.155727");
assert_eq!(o, Greater);

pub fn div_round_ref_val( &self, other: Self, rm: RoundingMode, ) -> (Self, Ordering)

Divides two Floats, rounding the result with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,m)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,m)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,m)=\infty$ if $x>0.0$
• $f(x,0.0,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,m)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,m)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,m)=-\infty$ if $x>0.0$
• $f(x,-0.0,m)=\infty$ if $x<0.0$
• $f(0.0,x,m)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,m)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,m)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,m)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::div_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_round_ref_val(Float::from(E), Floor);
assert_eq!(quotient.to_string(), "1.1557273497909217");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_round_ref_val(Float::from(E), Ceiling);
assert_eq!(quotient.to_string(), "1.155727349790922");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_round_ref_val(Float::from(E), Nearest);
assert_eq!(quotient.to_string(), "1.1557273497909217");
assert_eq!(o, Less);

pub fn div_round_ref_ref( &self, other: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Divides two Floats, rounding the result with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm\infty,p,m)=f(\pm0.0,\pm0.0,p,m) = \text{NaN}$
• $f(\infty,x,m)=\infty$ if $0.0<x<\infty$
• $f(\infty,x,m)=-\infty$ if $-\infty<x<0.0$
• $f(x,0.0,m)=\infty$ if $x>0.0$
• $f(x,0.0,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,m)=-\infty$ if $0.0<x<\infty$
• $f(-\infty,x,m)=\infty$ if $-\infty<x<0.0$
• $f(x,-0.0,m)=-\infty$ if $x>0.0$
• $f(x,-0.0,m)=\infty$ if $x<0.0$
• $f(0.0,x,m)=0.0$ if $x$ is not NaN and $x>0.0$
• $f(0.0,x,m)=-0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,\infty,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,\infty,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,m)=-0.0$ if $x$ is not NaN and $x>0.0$
• $f(-0.0,x,m)=0.0$ if $x$ is not NaN and $x<0.0$
• $f(x,-\infty,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(x,-\infty,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::div_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_round_ref_ref(&Float::from(E), Floor);
assert_eq!(quotient.to_string(), "1.1557273497909217");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_round_ref_ref(&Float::from(E), Ceiling);
assert_eq!(quotient.to_string(), "1.155727349790922");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_round_ref_ref(&Float::from(E), Nearest);
assert_eq!(quotient.to_string(), "1.1557273497909217");
assert_eq!(o, Less);

pub fn div_rational_prec_round_ref_val( &self, other: Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(\pm\infty,0,p,m)=f(\pm0.0,0,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x\geq 0$
• $f(\infty,x,p,m)=-\infty$ if $x<0$
• $f(-\infty,x,p,m)=-\infty$ if $x\geq 0$
• $f(-\infty,x,p,m)=\infty$ if $x<0$
• $f(0.0,x,p,m)=0.0$ if $x>0$
• $f(0.0,x,p,m)=-0.0$ if $x<0$
• $f(-0.0,x,p,m)=-0.0$ if $x>0$
• $f(-0.0,x,p,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::div_rational_prec_ref_val instead. If you know that your target precision is the precision of the Float input, consider using Float::div_rational_round_ref_val instead. If both of these things are true, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact division.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(quotient.to_string(), "9.0");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(quotient.to_string(), "9.5");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(quotient.to_string(), "9.5");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(quotient.to_string(), "9.42477");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(quotient.to_string(), "9.42479");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(quotient.to_string(), "9.42477");
assert_eq!(o, Less);

pub fn div_rational_prec_round_ref_ref( &self, other: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float and the Rational are both taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(\pm\infty,0,p,m)=f(\pm0.0,0,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x\geq 0$
• $f(\infty,x,p,m)=-\infty$ if $x<0$
• $f(-\infty,x,p,m)=-\infty$ if $x\geq 0$
• $f(-\infty,x,p,m)=\infty$ if $x<0$
• $f(0.0,x,p,m)=0.0$ if $x>0$
• $f(0.0,x,p,m)=-0.0$ if $x<0$
• $f(-0.0,x,p,m)=-0.0$ if $x>0$
• $f(-0.0,x,p,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::div_rational_prec_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using Float::div_rational_round_ref_ref instead. If both of these things are true, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact division.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(quotient.to_string(), "9.0");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(quotient.to_string(), "9.5");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(quotient.to_string(), "9.5");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(quotient.to_string(), "9.42477");
assert_eq!(o, Less);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(quotient.to_string(), "9.42479");
assert_eq!(o, Greater);

let (quotient, o) = Float::from(PI).div_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(quotient.to_string(), "9.42477");
assert_eq!(o, Less);

pub fn div_rational_prec_ref_val( &self, other: Rational, prec: u64, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the quotient is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(\pm\infty,0,p)=f(\pm0.0,0,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x\geq 0$
• $f(\infty,x,p)=-\infty$ if $x<0$
• $f(-\infty,x,p)=-\infty$ if $x\geq 0$
• $f(-\infty,x,p)=\infty$ if $x<0$
• $f(0.0,x,p)=0.0$ if $x>0$
• $f(0.0,x,p)=-0.0$ if $x<0$
• $f(-0.0,x,p)=-0.0$ if $x>0$
• $f(-0.0,x,p)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::div_rational_prec_round_ref_val instead. If you know that your target precision is the precision of the Float input, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) = Float::from(PI).div_rational_prec_ref_val(Rational::exact_from(1.5), 5);
assert_eq!(quotient.to_string(), "2.1");
assert_eq!(o, Greater);

let (quotient, o) =
    Float::from(PI).div_rational_prec_ref_val(Rational::exact_from(1.5), 20);
assert_eq!(quotient.to_string(), "2.094395");
assert_eq!(o, Less);

pub fn div_rational_prec_ref_ref( &self, other: &Rational, prec: u64, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the quotient is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(\pm\infty,0,p)=f(\pm0.0,0,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x\geq 0$
• $f(\infty,x,p)=-\infty$ if $x<0$
• $f(-\infty,x,p)=-\infty$ if $x\geq 0$
• $f(-\infty,x,p)=\infty$ if $x<0$
• $f(0.0,x,p)=0.0$ if $x>0$
• $f(0.0,x,p)=-0.0$ if $x<0$
• $f(-0.0,x,p)=-0.0$ if $x>0$
• $f(-0.0,x,p)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::div_rational_prec_round_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) =
    Float::from(PI).div_rational_prec_ref_ref(&Rational::exact_from(1.5), 5);
assert_eq!(quotient.to_string(), "2.1");
assert_eq!(o, Greater);

let (quotient, o) =
    Float::from(PI).div_rational_prec_ref_ref(&Rational::exact_from(1.5), 20);
assert_eq!(quotient.to_string(), "2.094395");
assert_eq!(o, Less);

pub fn div_rational_round_ref_val( &self, other: Rational, rm: RoundingMode, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=f(\pm\infty,0,m)=f(\pm0.0,0,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x\geq 0$
• $f(\infty,x,m)=-\infty$ if $x<0$
• $f(-\infty,x,m)=-\infty$ if $x\geq 0$
• $f(-\infty,x,m)=\infty$ if $x<0$
• $f(0.0,x,m)=0.0$ if $x>0$
• $f(0.0,x,m)=-0.0$ if $x<0$
• $f(-0.0,x,m)=-0.0$ if $x>0$
• $f(-0.0,x,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::div_rational_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(quotient.to_string(), "9.42477796076938");
assert_eq!(o, Less);

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(quotient.to_string(), "9.42477796076939");
assert_eq!(o, Greater);

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(quotient.to_string(), "9.42477796076938");
assert_eq!(o, Less);

pub fn div_rational_round_ref_ref( &self, other: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Divides a Float by a Rational, rounding the result with the specified rounding mode. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded quotient is less than, equal to, or greater than the exact quotient. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x/y+\varepsilon. $$

• If $x/y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x/y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x/y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x/y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x/y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=f(\pm\infty,0,m)=f(\pm0.0,0,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x\geq 0$
• $f(\infty,x,m)=-\infty$ if $x<0$
• $f(-\infty,x,m)=-\infty$ if $x\geq 0$
• $f(-\infty,x,m)=\infty$ if $x<0$
• $f(0.0,x,m)=0.0$ if $x>0$
• $f(0.0,x,m)=-0.0$ if $x<0$
• $f(-0.0,x,m)=-0.0$ if $x>0$
• $f(-0.0,x,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::div_rational_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using / instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(quotient.to_string(), "9.42477796076938");
assert_eq!(o, Less);

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(quotient.to_string(), "9.42477796076939");
assert_eq!(o, Greater);

let (quotient, o) =
    Float::from(PI).div_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(quotient.to_string(), "9.42477796076938");
assert_eq!(o, Less);

pub fn ln_prec_round_ref(&self, prec: u64, rm: RoundingMode) -> (Self, Ordering)

Computes the natural logarithm of a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded logarithm is less than, equal to, or greater than the exact logarithm. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The logarithm of any nonzero negative number is NaN.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = \ln{x}+\varepsilon. $$

• If $\ln{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |ln{x}|\rfloor-p+1}$.
• If $\ln{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |ln{x}|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=\infty$
• $f(-\infty,p,m)=\text{NaN}$
• $f(\pm0.0,p,m)=-\infty$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::ln_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::ln_round_ref instead. If both of these things are true, consider using (&Float).ln()instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(5, Floor);
assert_eq!(ln.to_string(), "2.2");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(5, Ceiling);
assert_eq!(ln.to_string(), "2.4");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(5, Nearest);
assert_eq!(ln.to_string(), "2.2");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(20, Floor);
assert_eq!(ln.to_string(), "2.302582");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(20, Ceiling);
assert_eq!(ln.to_string(), "2.302586");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_prec_round_ref(20, Nearest);
assert_eq!(ln.to_string(), "2.302586");
assert_eq!(o, Greater);

pub fn ln_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes the natural logarithm of a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded logarithm is less than, equal to, or greater than the exact logarithm. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The logarithm of any nonzero negative number is NaN.

If the logarithm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = \ln{x}+\varepsilon. $$

• If $\ln{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln{x}$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 \ln{x}\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=\infty$
• $f(-\infty,p)=\text{NaN}$
• $f(\pm0.0,p)=-\infty$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::ln_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).ln() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100).0.ln_prec_ref(5);
assert_eq!(ln.to_string(), "2.2");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100).0.ln_prec_ref(20);
assert_eq!(ln.to_string(), "2.302586");
assert_eq!(o, Greater);

pub fn ln_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes the natural logarithm of a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded logarithm is less than, equal to, or greater than the exact logarithm. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The logarithm of any nonzero negative number is NaN.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = \ln{x}+\varepsilon. $$

• If $\ln{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |ln{x}|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\ln{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |ln{x}|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=\infty$
• $f(-\infty,m)=\text{NaN}$
• $f(\pm0.0,m)=-\infty$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::ln_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).ln() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100).0.ln_round_ref(Floor);
assert_eq!(ln.to_string(), "2.302585092994045684017991454684");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_round_ref(Ceiling);
assert_eq!(ln.to_string(), "2.302585092994045684017991454687");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_round_ref(Nearest);
assert_eq!(ln.to_string(), "2.302585092994045684017991454684");
assert_eq!(o, Less);

pub fn ln_1_plus_x_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\ln(1+x)$, where $x$ is a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\ln(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = \ln(1+x)+\varepsilon. $$

• If $\ln(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\ln(1+x)|\rfloor-p+1}$.
• If $\ln(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\ln(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=\infty$
• $f(-\infty,p,m)=\text{NaN}$
• $f(\pm0.0,p,m)=\pm0.0$
• $f(-1,p,m)=-\infty$
• $f(x,p,m)=\text{NaN}$ for $x<-1$

This function cannot overflow, but it can underflow:

• If $0<f(x,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,p,m)<2^{-2^{30}}$, and $m$ is Ceiling, Up, or Nearest, $2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::ln_1_plus_x_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::ln_1_plus_x_round_ref instead. If both of these things are true, consider using (&Float).ln_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision. (The result cannot be represented exactly whenever the input is finite, nonzero, and greater than $-1$.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(5, Floor);
assert_eq!(ln.to_string(), "2.4");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(5, Ceiling);
assert_eq!(ln.to_string(), "2.5");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(5, Nearest);
assert_eq!(ln.to_string(), "2.4");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(20, Floor);
assert_eq!(ln.to_string(), "2.397892");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(20, Ceiling);
assert_eq!(ln.to_string(), "2.397896");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_round_ref(20, Nearest);
assert_eq!(ln.to_string(), "2.397896");
assert_eq!(o, Greater);

pub fn ln_1_plus_x_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes $\ln(1+x)$, where $x$ is a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\ln(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

If the result is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = \ln(1+x)+\varepsilon. $$

• If $\ln(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln(1+x)$ is finite and nonzero, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\ln(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=\infty$
• $f(-\infty,p)=\text{NaN}$
• $f(\pm0.0,p)=\pm0.0$
• $f(-1,p)=-\infty$
• $f(x,p)=\text{NaN}$ for $x<-1$

This function cannot overflow, but it can underflow: if $0<f(x,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::ln_1_plus_x_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).ln_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_base::num::basic::traits::One;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_ref(5);
assert_eq!(ln.to_string(), "2.4");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_prec_ref(20);
assert_eq!(ln.to_string(), "2.397896");
assert_eq!(o, Greater);

let (ln, o) = Float::ONE.ln_1_plus_x_prec_ref(20);
assert_eq!(ln.to_string(), "0.693147");
assert_eq!(o, Less);

pub fn ln_1_plus_x_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes $\ln(1+x)$, where $x$ is a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\ln(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = \ln(1+x)+\varepsilon. $$

• If $\ln(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\ln(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\ln(1+x)|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\ln(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\ln(1+x)|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=\infty$
• $f(-\infty,m)=\text{NaN}$
• $f(\pm0.0,m)=\pm0.0$
• $f(-1,m)=-\infty$
• $f(x,m)=\text{NaN}$ for $x<-1$

This function cannot overflow, but it can underflow:

• If $0<f(x,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,m)<2^{-2^{30}}$, and $m$ is Ceiling, Up, or Nearest, $2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::ln_1_plus_x_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).ln_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision. (The result cannot be represented exactly whenever the input is finite, nonzero, and greater than $-1$.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_round_ref(Floor);
assert_eq!(ln.to_string(), "2.397895272798370544061943577962");
assert_eq!(o, Less);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_round_ref(Ceiling);
assert_eq!(ln.to_string(), "2.397895272798370544061943577965");
assert_eq!(o, Greater);

let (ln, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .ln_1_plus_x_round_ref(Nearest);
assert_eq!(ln.to_string(), "2.397895272798370544061943577965");
assert_eq!(o, Greater);

pub fn log_base_prec_round_ref( &self, base: u64, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See Float::log_base_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if base is less than 2, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(1000).log_base_prec_round_ref(10, 10, Nearest);
assert_eq!(log.to_string(), "3.0");
assert_eq!(o, Equal);

pub fn log_base_prec_ref(&self, base: u64, prec: u64) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if base is less than 2.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(50).log_base_prec_ref(10, 10);
assert_eq!(log.to_string(), "1.699");
assert_eq!(o, Greater);

pub fn log_base_round_ref( &self, base: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the precision of the input and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if base is less than 2, or if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(81).log_base_round_ref(3, Ceiling);
assert_eq!(log.to_string(), "4.0");
assert_eq!(o, Equal);

pub fn log_base_10_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{10} x$, where $x$ is a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See Float::log_base_10_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(1000).log_base_10_prec_round_ref(10, Nearest);
assert_eq!(log.to_string(), "3.0");
assert_eq!(o, Equal);

pub fn log_base_10_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes $\log_{10} x$, where $x$ is a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_10_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(50).log_base_10_prec_ref(10);
assert_eq!(log.to_string(), "1.699");
assert_eq!(o, Greater);

pub fn log_base_10_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes $\log_{10} x$, where $x$ is a Float, rounding the result to the precision of the input and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_10_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(100).log_base_10_round_ref(Ceiling);
assert_eq!(log.to_string(), "2.0");
assert_eq!(o, Equal);

pub fn log_base_10_1_plus_x_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{10}(1+x)$, where $x$ is a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See Float::log_base_10_1_plus_x_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(99)).log_base_10_1_plus_x_prec_round_ref(10, Exact);
assert_eq!(log.to_string(), "2.0"); // log_10(100) = 2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(1)).log_base_10_1_plus_x_prec_round_ref(20, Floor);
assert_eq!(log.to_string(), "0.3010297"); // log_10(2), rounded down
assert_eq!(o, Less);

pub fn log_base_10_1_plus_x_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes $\log_{10}(1+x)$, where $x$ is a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_10_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(99)).log_base_10_1_plus_x_prec_ref(10);
assert_eq!(log.to_string(), "2.0"); // log_10(100) = 2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(7)).log_base_10_1_plus_x_prec_ref(30);
assert_eq!(log.to_string(), "0.903089987"); // log_10(8)
assert_eq!(o, Greater);

pub fn log_base_10_1_plus_x_round_ref( &self, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{10}(1+x)$, where $x$ is a Float, rounding the result to the precision of the input and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_10_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(99)).log_base_10_1_plus_x_round_ref(Exact);
assert_eq!(log.to_string(), "2.0"); // log_10(100) = 2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(9)).log_base_10_1_plus_x_round_ref(Exact);
assert_eq!(log.to_string(), "1.0"); // log_10(10) = 1
assert_eq!(o, Equal);

pub fn log_base_1_plus_x_prec_round_ref( &self, base: u64, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See Float::log_base_1_plus_x_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if base is less than 2, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from(8).log_base_1_plus_x_prec_round_ref(3, 10, Exact);
assert_eq!(log.to_string(), "2.0"); // log_3(9) = 2
assert_eq!(o, Equal);

let (log, o) = Float::from(1).log_base_1_plus_x_prec_round_ref(3, 20, Floor);
assert_eq!(log.to_string(), "0.630929"); // log_3(2), rounded down
assert_eq!(o, Less);

pub fn log_base_1_plus_x_prec_ref( &self, base: u64, prec: u64, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if base is less than 2.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(2)).log_base_1_plus_x_prec_ref(9, 10);
assert_eq!(log.to_string(), "0.5"); // log_9(3) = 1/2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(7)).log_base_1_plus_x_prec_ref(5, 30);
assert_eq!(log.to_string(), "1.292029675"); // log_5(8)
assert_eq!(o, Greater);

pub fn log_base_1_plus_x_round_ref( &self, base: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a u64 greater than 1, rounding the result to the precision of the input and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if base is less than 2, or if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(8)).log_base_1_plus_x_round_ref(3, Exact);
assert_eq!(log.to_string(), "2.0"); // log_3(9) = 2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(2)).log_base_1_plus_x_round_ref(9, Exact);
assert_eq!(log.to_string(), "0.5"); // log_9(3) = 1/2
assert_eq!(o, Equal);

pub fn log_base_2_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_2 x$, where $x$ is a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-2 logarithm of any nonzero negative number is NaN.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = \log_2 x+\varepsilon. $$

• If $\log_2 x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2 x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_2 x|\rfloor-p+1}$.
• If $\log_2 x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2 x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=\infty$
• $f(-\infty,p,m)=\text{NaN}$
• $f(\pm0.0,p,m)=-\infty$
• $f(1.0,p,m)=0.0$, and the result is exact
• $f(2^k,p,m)=k$, rounded to precision $p$; the result is exact if and only if $k$ is representable with precision $p$
• $f(x,p,m)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::log_base_2_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::log_base_2_round_ref instead. If both of these things are true, consider using (&Float).log_base_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision. (The result is exactly representable if and only if the input is NaN, infinite, zero, equal to 1, or a power of 2 whose base-2 logarithm is representable with the given precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(5, Floor);
assert_eq!(log.to_string(), "3.2");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(5, Ceiling);
assert_eq!(log.to_string(), "3.4");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(5, Nearest);
assert_eq!(log.to_string(), "3.4");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(20, Floor);
assert_eq!(log.to_string(), "3.321926");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(20, Ceiling);
assert_eq!(log.to_string(), "3.32193");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_round_ref(20, Nearest);
assert_eq!(log.to_string(), "3.32193");
assert_eq!(o, Greater);

pub fn log_base_2_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes $\log_2 x$, where $x$ is a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-2 logarithm of any nonzero negative number is NaN.

If the logarithm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = \log_2 x+\varepsilon. $$

• If $\log_2 x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2 x$ is finite and nonzero, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2 x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=\infty$
• $f(-\infty,p)=\text{NaN}$
• $f(\pm0.0,p)=-\infty$
• $f(1.0,p)=0.0$, and the result is exact
• $f(2^k,p)=k$, rounded to precision $p$; the result is exact if and only if $k$ is representable with precision $p$
• $f(x,p)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::log_base_2_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).log_base_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_ref(5);
assert_eq!(log.to_string(), "3.4");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_prec_ref(20);
assert_eq!(log.to_string(), "3.32193");
assert_eq!(o, Greater);

pub fn log_base_2_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes $\log_2 x$, where $x$ is a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-2 logarithm of any nonzero negative number is NaN.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = \log_2 x+\varepsilon. $$

• If $\log_2 x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2 x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_2 x|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\log_2 x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2 x|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=\infty$
• $f(-\infty,m)=\text{NaN}$
• $f(\pm0.0,m)=-\infty$
• $f(1.0,m)=0.0$, and the result is exact
• $f(2^k,m)=k$, rounded to the precision of the input; the result is exact if and only if $k$ is representable with that precision
• $f(x,m)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::log_base_2_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).log_base_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision. (The result is exactly representable if and only if the input is NaN, infinite, zero, equal to 1, or a power of 2 whose base-2 logarithm is representable with the input precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_round_ref(Floor);
assert_eq!(log.to_string(), "3.321928094887362347870319429487");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_round_ref(Ceiling);
assert_eq!(log.to_string(), "3.32192809488736234787031942949");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_round_ref(Nearest);
assert_eq!(log.to_string(), "3.32192809488736234787031942949");
assert_eq!(o, Greater);

pub fn log_base_2_1_plus_x_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_2(1+x)$, where $x$ is a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_2(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = \log_2(1+x)+\varepsilon. $$

• If $\log_2(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_2(1+x)|\rfloor-p+1}$.
• If $\log_2(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=\infty$
• $f(-\infty,p,m)=\text{NaN}$
• $f(\pm0.0,p,m)=\pm0.0$
• $f(-1,p,m)=-\infty$
• $f(x,p,m)=\text{NaN}$ for $x<-1$
• $f(x,p,m)=k$ when $1+x=2^k$. The result is the integer $k$ (subject to rounding at precision $p$, and exact iff $k$ is representable with precision $p$). This covers $x$ a power of 2 minus 1 (e.g. $x=1\to1$, $x=3\to2$) and negative $x$ such as $x=-1/2\to-1$ and $x=-3/4\to-2$.

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::log_base_2_1_plus_x_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::log_base_2_1_plus_x_round_ref instead. If both of these things are true, consider using (&Float).log_base_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision. (The result is exactly representable only when the input is NaN, infinite, zero, $-1$, less than $-1$, or a value for which $1+x$ is a power of 2 whose base-2 logarithm is representable with the given precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(5, Floor);
assert_eq!(log.to_string(), "3.4");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(5, Ceiling);
assert_eq!(log.to_string(), "3.5");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(5, Nearest);
assert_eq!(log.to_string(), "3.5");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(20, Floor);
assert_eq!(log.to_string(), "3.459431");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(20, Ceiling);
assert_eq!(log.to_string(), "3.459435");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_round_ref(20, Nearest);
assert_eq!(log.to_string(), "3.459431");
assert_eq!(o, Less);

pub fn log_base_2_1_plus_x_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes $\log_2(1+x)$, where $x$ is a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_2(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

If the result is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = \log_2(1+x)+\varepsilon. $$

• If $\log_2(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2(1+x)$ is finite and nonzero, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=\infty$
• $f(-\infty,p)=\text{NaN}$
• $f(\pm0.0,p)=\pm0.0$
• $f(-1,p)=-\infty$
• $f(x,p)=\text{NaN}$ for $x<-1$
• $f(x,p)=k$ when $1+x=2^k$. The result is the integer $k$ (subject to rounding at precision $p$, and exact iff $k$ is representable with precision $p$). This covers $x$ a power of 2 minus 1 (e.g. $x=1\to1$, $x=3\to2$) and negative $x$ such as $x=-1/2\to-1$ and $x=-3/4\to-2$.

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::log_base_2_1_plus_x_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).log_base_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_base::num::basic::traits::One;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_ref(5);
assert_eq!(log.to_string(), "3.5");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_prec_ref(20);
assert_eq!(log.to_string(), "3.459431");
assert_eq!(o, Less);

let (log, o) = Float::ONE.log_base_2_1_plus_x_prec_ref(20);
assert_eq!(log.to_string(), "1.0");
assert_eq!(o, Equal);

pub fn log_base_2_1_plus_x_round_ref( &self, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_2(1+x)$, where $x$ is a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_2(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = \log_2(1+x)+\varepsilon. $$

• If $\log_2(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_2(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_2(1+x)|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\log_2(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_2(1+x)|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=\infty$
• $f(-\infty,m)=\text{NaN}$
• $f(\pm0.0,m)=\pm0.0$
• $f(-1,m)=-\infty$
• $f(x,m)=\text{NaN}$ for $x<-1$
• $f(x,m)=k$ when $1+x=2^k$. The result is the integer $k$ (subject to rounding at the input precision $p$, and exact iff $k$ is representable with precision $p$). This covers $x$ a power of 2 minus 1 (e.g. $x=1\to1$, $x=3\to2$) and negative $x$ such as $x=-1/2\to-1$ and $x=-3/4\to-2$.

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::log_base_2_1_plus_x_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).log_base_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision. (The result is exactly representable only when the input is NaN, infinite, zero, $-1$, less than $-1$, or a value for which $1+x$ is a power of 2 whose base-2 logarithm is representable with the given precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_round_ref(Floor);
assert_eq!(log.to_string(), "3.459431618637297256199363046725");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_round_ref(Ceiling);
assert_eq!(log.to_string(), "3.459431618637297256199363046728");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_2_1_plus_x_round_ref(Nearest);
assert_eq!(log.to_string(), "3.459431618637297256199363046725");
assert_eq!(o, Less);

pub fn log_base_float_base_prec_round_ref( &self, base: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ and the base $b$ are both Floats, rounding the result to the specified precision and with the specified rounding mode. Both are taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_float_base_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(8)).log_base_float_base_prec_round_ref(&Float::from(2), 10, Exact);
assert_eq!(log.to_string(), "3.0"); // log_2(8) = 3
assert_eq!(o, Equal);

let (log, o) =
    (&Float::from(2)).log_base_float_base_prec_round_ref(&Float::from(4), 10, Exact);
assert_eq!(log.to_string(), "0.5"); // log_4(2) = 1/2
assert_eq!(o, Equal);

pub fn log_base_float_base_prec_ref( &self, base: &Self, prec: u64, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ and the base $b$ are both Floats, rounding the result to the nearest value of the specified precision. Both are taken by reference. An Ordering is also returned.

See Float::log_base_float_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(8)).log_base_float_base_prec_ref(&Float::from(4), 10);
assert_eq!(log.to_string(), "1.5"); // log_4(8) = 3/2
assert_eq!(o, Equal);

pub fn log_base_float_base_round_ref( &self, base: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ and the base $b$ are both Floats, rounding the result to the precision of the input and with the specified rounding mode. Both are taken by reference. An Ordering is also returned.

See Float::log_base_float_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(81)).log_base_float_base_round_ref(&Float::from(3), Exact);
assert_eq!(log.to_string(), "4.0"); // log_3(81) = 4
assert_eq!(o, Equal);

pub fn log_base_float_base_1_plus_x_prec_round_ref( &self, base: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ and the base $b$ are both Floats, rounding the result to the specified precision and with the specified rounding mode. Both are taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_float_base_1_plus_x_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let x = Float::from(7);
let (log, o) = x.log_base_float_base_1_plus_x_prec_round_ref(&Float::from(2), 10, Exact);
assert_eq!(log.to_string(), "3.0"); // log_2(1 + 7) = log_2(8) = 3
assert_eq!(o, Equal);

let x = Float::from(1);
let (log, o) = x.log_base_float_base_1_plus_x_prec_round_ref(&Float::from(3), 20, Floor);
assert_eq!(log.to_string(), "0.630929"); // log_3(2), rounded down
assert_eq!(o, Less);

pub fn log_base_float_base_1_plus_x_prec_ref( &self, base: &Self, prec: u64, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ and the base $b$ are both Floats, rounding the result to the nearest value of the specified precision. Both are taken by reference. An Ordering is also returned.

See Float::log_base_float_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero.

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(8)).log_base_float_base_1_plus_x_prec_ref(&Float::from(3), 10);
assert_eq!(log.to_string(), "2.0"); // log_3(1 + 8) = log_3(9) = 2
assert_eq!(o, Equal);

pub fn log_base_float_base_1_plus_x_round_ref( &self, base: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ and the base $b$ are both Floats, rounding the result to the precision of the input and with the specified rounding mode. Both are taken by reference. An Ordering is also returned.

See Float::log_base_float_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(8)).log_base_float_base_1_plus_x_round_ref(&Float::from(3), Exact);
assert_eq!(log.to_string(), "2.0"); // log_3(1 + 8) = log_3(9) = 2
assert_eq!(o, Equal);

pub fn log_base_power_of_2_prec_round_ref( &self, pow: i64, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{2^k} x$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result to the specified precision and with the specified rounding mode. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-$2^k$ logarithm of any nonzero negative number is NaN.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,k,p,m) = \log_{2^k} x+\varepsilon. $$

• If $\log_{2^k} x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k} x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_{2^k} x|\rfloor-p+1}$.
• If $\log_{2^k} x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k} x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},k,p,m)=\text{NaN}$
• $f(\infty,k,p,m)=\infty$ if $k>0$, and $-\infty$ if $k<0$
• $f(-\infty,k,p,m)=\text{NaN}$
• $f(\pm0.0,k,p,m)=-\infty$ if $k>0$, and $\infty$ if $k<0$
• $f(1.0,k,p,m)=0.0$, and the result is exact
• $f(2^m,k,p,m’)=m/k$, rounded to precision $p$; the result is exact if and only if $m/k$ is representable with precision $p$ (for example $\log_4 8=3/2$ is exact, but $\log_8 4=2/3$ is not)
• $f(x,k,p,m)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::log_base_power_of_2_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::log_base_power_of_2_round_ref instead. If both of these things are true, consider using (&Float).log_base_power_of_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if pow is zero (the base $2^0=1$ has no logarithm), or if rm is Exact but the result cannot be represented exactly with the given precision. (The result is exactly representable if and only if the input is NaN, infinite, zero, equal to 1, or a power of 2 whose base-$2^k$ logarithm is representable with the given precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(2, 5, Floor);
assert_eq!(log.to_string(), "1.62");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(2, 5, Ceiling);
assert_eq!(log.to_string(), "1.7");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(2, 5, Nearest);
assert_eq!(log.to_string(), "1.7");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(3, 20, Floor);
assert_eq!(log.to_string(), "1.107309");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(3, 20, Ceiling);
assert_eq!(log.to_string(), "1.107311");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_round_ref(3, 20, Nearest);
assert_eq!(log.to_string(), "1.107309");
assert_eq!(o, Less);

// log_4(8) = 3/2, exactly representable
let (log, o) = Float::from(8u32).log_base_power_of_2_prec_round_ref(2, 10, Nearest);
assert_eq!(log.to_string(), "1.5");
assert_eq!(o, Equal);

pub fn log_base_power_of_2_prec_ref( &self, pow: i64, prec: u64, ) -> (Self, Ordering)

Computes $\log_{2^k} x$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result to the nearest value of the specified precision. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-$2^k$ logarithm of any nonzero negative number is NaN.

If the logarithm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,k,p) = \log_{2^k} x+\varepsilon. $$

• If $\log_{2^k} x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k} x$ is finite and nonzero, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k} x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},k,p)=\text{NaN}$
• $f(\infty,k,p)=\infty$ if $k>0$, and $-\infty$ if $k<0$
• $f(-\infty,k,p)=\text{NaN}$
• $f(\pm0.0,k,p)=-\infty$ if $k>0$, and $\infty$ if $k<0$
• $f(1.0,k,p)=0.0$, and the result is exact
• $f(2^m,k,p)=m/k$, rounded to precision $p$; the result is exact if and only if $m/k$ is representable with precision $p$ (for example $\log_4 8=3/2$ is exact, but $\log_8 4=2/3$ is not)
• $f(x,k,p)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::log_base_power_of_2_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).log_base_power_of_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if pow is zero (the base $2^0=1$ has no logarithm).

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_ref(2, 5);
assert_eq!(log.to_string(), "1.7");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_prec_ref(3, 20);
assert_eq!(log.to_string(), "1.107309");
assert_eq!(o, Less);

pub fn log_base_power_of_2_round_ref( &self, pow: i64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{2^k} x$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result with the specified rounding mode. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The base-$2^k$ logarithm of any nonzero negative number is NaN.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,k,m) = \log_{2^k} x+\varepsilon. $$

• If $\log_{2^k} x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k} x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_{2^k} x|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\log_{2^k} x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k} x|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},k,m)=\text{NaN}$
• $f(\infty,k,m)=\infty$ if $k>0$, and $-\infty$ if $k<0$
• $f(-\infty,k,m)=\text{NaN}$
• $f(\pm0.0,k,m)=-\infty$ if $k>0$, and $\infty$ if $k<0$
• $f(1.0,k,m)=0.0$, and the result is exact
• $f(2^m,k,m’)=m/k$, rounded to the precision of the input; the result is exact if and only if $m/k$ is representable with that precision (for example $\log_4 8=3/2$ is exact, but $\log_8 4=2/3$ is not)
• $f(x,k,m)=\text{NaN}$ for $x<0$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::log_base_power_of_2_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).log_base_power_of_2() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if pow is zero (the base $2^0=1$ has no logarithm), or if rm is Exact but the result cannot be represented exactly with the input precision. (The result is exactly representable if and only if the input is NaN, infinite, zero, equal to 1, or a power of 2 whose base-$2^k$ logarithm is representable with the input precision.)

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_round_ref(2, Floor);
assert_eq!(log.to_string(), "1.660964047443681173935159714743");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_round_ref(2, Ceiling);
assert_eq!(log.to_string(), "1.660964047443681173935159714745");
assert_eq!(o, Greater);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_round_ref(2, Nearest);
assert_eq!(log.to_string(), "1.660964047443681173935159714745");
assert_eq!(o, Greater);

pub fn log_base_power_of_2_1_plus_x_prec_round_ref( &self, pow: i64, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{2^k}(1+x)$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result to the specified precision and with the specified rounding mode. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_{2^k}(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,k,p,m) = \log_{2^k}(1+x)+\varepsilon. $$

• If $\log_{2^k}(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k}(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_{2^k}(1+x)|\rfloor-p+1}$.
• If $\log_{2^k}(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k}(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},k,p,m)=\text{NaN}$
• $f(\infty,k,p,m)=\infty$ if $k>0$, and $-\infty$ if $k<0$
• $f(-\infty,k,p,m)=\text{NaN}$
• $f(0.0,k,p,m)=0.0$ if $k>0$, and $-0.0$ if $k<0$
• $f(-0.0,k,p,m)=-0.0$ if $k>0$, and $0.0$ if $k<0$
• $f(-1.0,k,p,m)=-\infty$ if $k>0$, and $\infty$ if $k<0$
• $f(x,k,p,m)=\text{NaN}$ for $x<-1$
• $f(x,k,p,m)=m/k$ when $1+x=2^m$, rounded to precision $p$; the result is exact if and only if $m/k$ is representable with precision $p$ (for example $\log_4 8=3/2$ when $x=7$ is exact, but $\log_8 4=2/3$ when $x=3$ is not)

This function cannot overflow, but it can underflow:

• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,k,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::log_base_power_of_2_1_plus_x_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::log_base_power_of_2_1_plus_x_round_ref instead. If both of these things are true, consider using (&Float).log_base_power_of_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if pow is zero (the base $2^0=1$ has no logarithm), or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_1_plus_x_prec_round_ref(2, 20, Floor);
assert_eq!(log.to_string(), "1.729715");
assert_eq!(o, Less);

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_1_plus_x_prec_round_ref(2, 20, Ceiling);
assert_eq!(log.to_string(), "1.729717");
assert_eq!(o, Greater);

pub fn log_base_power_of_2_1_plus_x_prec_ref( &self, pow: i64, prec: u64, ) -> (Self, Ordering)

Computes $\log_{2^k}(1+x)$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result to the nearest value of the specified precision. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_{2^k}(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

If the logarithm is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,k,p) = \log_{2^k}(1+x)+\varepsilon. $$

• If $\log_{2^k}(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k}(1+x)$ is finite and nonzero, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k}(1+x)|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},k,p)=\text{NaN}$
• $f(\infty,k,p)=\infty$ if $k>0$, and $-\infty$ if $k<0$
• $f(-\infty,k,p)=\text{NaN}$
• $f(0.0,k,p)=0.0$ if $k>0$, and $-0.0$ if $k<0$
• $f(-0.0,k,p)=-0.0$ if $k>0$, and $0.0$ if $k<0$
• $f(-1.0,k,p)=-\infty$ if $k>0$, and $\infty$ if $k<0$
• $f(x,k,p)=\text{NaN}$ for $x<-1$
• $f(x,k,p)=m/k$ when $1+x=2^m$, rounded to precision $p$; the result is exact if and only if $m/k$ is representable with precision $p$

This function cannot overflow, but it can underflow:

• If $0<f(x,k,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::log_base_power_of_2_1_plus_x_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).log_base_power_of_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if pow is zero (the base $2^0=1$ has no logarithm).

Examples

use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_1_plus_x_prec_ref(2, 20);
assert_eq!(log.to_string(), "1.729715");
assert_eq!(o, Less);

pub fn log_base_power_of_2_1_plus_x_round_ref( &self, pow: i64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_{2^k}(1+x)$, where $x$ is a Float and the base is $2^k$ for some nonzero integer $k$, rounding the result with the specified rounding mode. The base’s exponent $k$ is pow, which may be negative. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

$\log_{2^k}(1+x)$ is undefined for $x<-1$, so whenever $x<-1$, NaN is returned.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,k,m) = \log_{2^k}(1+x)+\varepsilon. $$

• If $\log_{2^k}(1+x)$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\log_{2^k}(1+x)$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |\log_{2^k}(1+x)|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\log_{2^k}(1+x)$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |\log_{2^k}(1+x)|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

See the Float::log_base_power_of_2_1_plus_x_prec_round documentation for information on special cases, overflow, and underflow.

If you want to specify an output precision, consider using Float::log_base_power_of_2_1_plus_x_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).log_base_power_of_2_1_plus_x() instead.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if pow is zero (the base $2^0=1$ has no logarithm), or if rm is Exact but the result cannot be represented exactly with the input precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (log, o) = Float::from_unsigned_prec(10u32, 100)
    .0
    .log_base_power_of_2_1_plus_x_round_ref(2, Floor);
assert_eq!(log.to_string(), "1.729715809318648628099681523362");
assert_eq!(o, Less);

pub fn log_base_rational_base_prec_round_ref( &self, base: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the specified precision and with the specified rounding mode. The Float and the base are both taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_rational_base_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if base is less than or equal to 1, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(8)).log_base_rational_base_prec_round_ref(&Rational::from(2), 10, Exact);
assert_eq!(log.to_string(), "3.0"); // log_2(8) = 3
assert_eq!(o, Equal);

let (log, o) =
    (&Float::from(2)).log_base_rational_base_prec_round_ref(&Rational::from(4), 10, Exact);
assert_eq!(log.to_string(), "0.5"); // log_4(2) = 1/2
assert_eq!(o, Equal);

pub fn log_base_rational_base_prec_ref( &self, base: &Rational, prec: u64, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the nearest value of the specified precision. The Float and the base are both taken by reference. An Ordering is also returned.

See Float::log_base_rational_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if base is less than or equal to 1.

Examples

use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(8)).log_base_rational_base_prec_ref(&Rational::from(2), 10);
assert_eq!(log.to_string(), "3.0"); // log_2(8) = 3
assert_eq!(o, Equal);

let (log, o) = (&Float::from(2)).log_base_rational_base_prec_ref(&Rational::from(4), 10);
assert_eq!(log.to_string(), "0.5"); // log_4(2) = 1/2
assert_eq!(o, Equal);

pub fn log_base_rational_base_round_ref( &self, base: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b x$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the precision of the input and with the specified rounding mode. The Float and the base are both taken by reference. An Ordering is also returned.

See Float::log_base_rational_base_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if base is less than or equal to 1, or if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(81)).log_base_rational_base_round_ref(&Rational::from(3), Exact);
assert_eq!(log.to_string(), "4.0"); // log_3(81) = 4
assert_eq!(o, Equal);

let (log, o) =
    (&Float::from(9)).log_base_rational_base_round_ref(&Rational::from(3), Exact);
assert_eq!(log.to_string(), "2.0"); // log_3(9) = 2
assert_eq!(o, Equal);

pub fn log_base_rational_base_1_plus_x_prec_round_ref( &self, base: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the specified precision and with the specified rounding mode. The Float and the base are both taken by reference. An Ordering is also returned, indicating whether the rounded value is less than, equal to, or greater than the exact value.

See Float::log_base_rational_base_1_plus_x_prec_round for details, special cases, and a description of the rounding behavior.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero, if base is less than or equal to 1, or if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) = (&Float::from(8)).log_base_rational_base_1_plus_x_prec_round_ref(
    &Rational::from(3),
    10,
    Exact,
);
assert_eq!(log.to_string(), "2.0"); // log_3(1 + 8) = log_3(9) = 2
assert_eq!(o, Equal);

let (log, o) = (&Float::from(1)).log_base_rational_base_1_plus_x_prec_round_ref(
    &Rational::from(3),
    20,
    Floor,
);
assert_eq!(log.to_string(), "0.630929"); // log_3(2), rounded down
assert_eq!(o, Less);

pub fn log_base_rational_base_1_plus_x_prec_ref( &self, base: &Rational, prec: u64, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the nearest value of the specified precision. The Float and the base are both taken by reference. An Ordering is also returned.

See Float::log_base_rational_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if prec is zero or if base is less than or equal to 1.

Examples

use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(8)).log_base_rational_base_1_plus_x_prec_ref(&Rational::from(3), 10);
assert_eq!(log.to_string(), "2.0"); // log_3(1 + 8) = log_3(9) = 2
assert_eq!(o, Equal);

pub fn log_base_rational_base_1_plus_x_round_ref( &self, base: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Computes $\log_b(1+x)$, where $x$ is a Float and $b$ is a Rational greater than 1, rounding the result to the precision of the input and with the specified rounding mode. The Float and the base are both taken by reference. An Ordering is also returned.

See Float::log_base_rational_base_1_plus_x_prec_round for details and special cases.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n (\log n)^2)$

where $T$ is time, $M$ is additional memory, and $n$ is the precision of the input.

Panics

Panics if base is less than or equal to 1, or if rm is Exact but the result cannot be represented exactly with the input’s precision.

Examples

use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (log, o) =
    (&Float::from(8)).log_base_rational_base_1_plus_x_round_ref(&Rational::from(3), Exact);
assert_eq!(log.to_string(), "2.0"); // log_3(1 + 8) = log_3(9) = 2
assert_eq!(o, Equal);

pub fn mul_prec_round_ref_val( &self, other: Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies two Floats, rounding the result to the specified precision and with the specified rounding mode. The first Float is are taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm0.0,p,m)=f(\pm0.0,\pm\infty,p,m) = \text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\infty$ if $x>0.0$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=-\infty$ if $x>0.0$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=\infty$ if $x<0.0$
• $f(0.0,x,p,m)=f(x,0.0,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,p,m)=f(x,0.0,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p,m)=f(x,-0.0,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,p,m)=f(x,-0.0,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::mul_prec_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::mul_round_ref_val instead. If both of these things are true, consider using * instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact multiplication.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 5, Floor);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 5, Ceiling);
assert_eq!(product.to_string(), "9.0");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 5, Nearest);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 20, Floor);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 20, Ceiling);
assert_eq!(product.to_string(), "8.53975");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_prec_round_ref_val(Float::from(E), 20, Nearest);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

pub fn mul_prec_round_ref_ref( &self, other: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies two Floats, rounding the result to the specified precision and with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\pm\infty,\pm0.0,p,m)=f(\pm0.0,\pm\infty,p,m) = \text{NaN}$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=\infty$ if $x>0.0$
• $f(\infty,x,p,m)=f(x,\infty,p,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=-\infty$ if $x>0.0$
• $f(-\infty,x,p,m)=f(x,-\infty,p,m)=\infty$ if $x<0.0$
• $f(0.0,x,p,m)=f(x,0.0,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,p,m)=f(x,0.0,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p,m)=f(x,-0.0,p,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,p,m)=f(x,-0.0,p,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::mul_prec_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::mul_round_ref_ref instead. If both of these things are true, consider using * instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact multiplication.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 5, Floor);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 5, Ceiling);
assert_eq!(product.to_string(), "9.0");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 5, Nearest);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 20, Floor);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 20, Ceiling);
assert_eq!(product.to_string(), "8.53975");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_prec_round_ref_ref(&Float::from(E), 20, Nearest);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

pub fn mul_prec_ref_val(&self, other: Self, prec: u64) -> (Self, Ordering)

Multiplies two Floats, rounding the result to the nearest value of the specified precision. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the product is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\pm\infty,\pm0.0,p)=f(\pm0.0,\pm\infty,p) = \text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\infty$ if $x>0.0$
• $f(\infty,x,p)=f(x,\infty,p)=-\infty$ if $x<0.0$
• $f(-\infty,x,p)=f(x,-\infty,p)=-\infty$ if $x>0.0$
• $f(-\infty,x,p)=f(x,-\infty,p)=\infty$ if $x<0.0$
• $f(0.0,x,p)=f(x,0.0,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,p)=f(x,0.0,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p)=f(x,-0.0,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,p)=f(x,-0.0,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::mul_prec_round_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using * instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_prec_ref_val(Float::from(E), 5);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_ref_val(Float::from(E), 20);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

pub fn mul_prec_ref_ref(&self, other: &Self, prec: u64) -> (Self, Ordering)

Multiplies two Floats, rounding the result to the nearest value of the specified precision. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the product is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\pm\infty,\pm0.0,p)=f(\pm0.0,\pm\infty,p) = \text{NaN}$
• $f(\infty,x,p)=f(x,\infty,p)=\infty$ if $x>0.0$
• $f(\infty,x,p)=f(x,\infty,p)=-\infty$ if $x<0.0$
• $f(-\infty,x,p)=f(x,-\infty,p)=-\infty$ if $x>0.0$
• $f(-\infty,x,p)=f(x,-\infty,p)=\infty$ if $x<0.0$
• $f(0.0,x,p)=f(x,0.0,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,p)=f(x,0.0,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,p)=f(x,-0.0,p)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,p)=f(x,-0.0,p)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::mul_prec_round_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using * instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_prec_ref_ref(&Float::from(E), 5);
assert_eq!(product.to_string(), "8.5");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_prec_ref_ref(&Float::from(E), 20);
assert_eq!(product.to_string(), "8.53973");
assert_eq!(o, Less);

pub fn mul_round_ref_val( &self, other: Self, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies two Floats, rounding the result with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\pm\infty,\pm0.0,m)=f(\pm0.0,\pm\infty,m) = \text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\infty$ if $x>0.0$
• $f(\infty,x,m)=f(x,\infty,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,m)=f(x,-\infty,m)=-\infty$ if $x>0.0$
• $f(-\infty,x,m)=f(x,-\infty,m)=\infty$ if $x<0.0$
• $f(0.0,x,m)=f(x,0.0,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,m)=f(x,0.0,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,m)=f(x,-0.0,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,m)=f(x,-0.0,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::mul_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_round_ref_val(Float::from(E), Floor);
assert_eq!(product.to_string(), "8.539734222673566");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_round_ref_val(Float::from(E), Ceiling);
assert_eq!(product.to_string(), "8.539734222673568");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_round_ref_val(Float::from(E), Nearest);
assert_eq!(product.to_string(), "8.539734222673566");
assert_eq!(o, Less);

pub fn mul_round_ref_ref( &self, other: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies two Floats, rounding the result with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\pm\infty,\pm0.0,m)=f(\pm0.0,\pm\infty,m) = \text{NaN}$
• $f(\infty,x,m)=f(x,\infty,m)=\infty$ if $x>0.0$
• $f(\infty,x,m)=f(x,\infty,m)=-\infty$ if $x<0.0$
• $f(-\infty,x,m)=f(x,-\infty,m)=-\infty$ if $x>0.0$
• $f(-\infty,x,m)=f(x,-\infty,m)=\infty$ if $x<0.0$
• $f(0.0,x,m)=f(x,0.0,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(0.0,x,m)=f(x,0.0,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$
• $f(-0.0,x,m)=f(x,-0.0,m)=-0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=0.0$ or $x>0.0$
• $f(-0.0,x,m)=f(x,-0.0,m)=0.0$ if $x$ is not NaN or $\pm\infty$, and if $x=-0.0$ or $x<0.0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::mul_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_round_ref_ref(&Float::from(E), Floor);
assert_eq!(product.to_string(), "8.539734222673566");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_round_ref_ref(&Float::from(E), Ceiling);
assert_eq!(product.to_string(), "8.539734222673568");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_round_ref_ref(&Float::from(E), Nearest);
assert_eq!(product.to_string(), "8.539734222673566");
assert_eq!(o, Less);

pub fn mul_rational_prec_round_ref_val( &self, other: Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(\pm\infty,0,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x>0$
• $f(\infty,x,p,m)=-\infty$ if $x<0$
• $f(-\infty,x,p,m)=-\infty$ if $x>0$
• $f(-\infty,x,p,m)=\infty$ if $x<0$
• $f(0.0,x,p,m)=0.0$ if $x\geq0$
• $f(0.0,x,p,m)=-0.0$ if $x<0$
• $f(-0.0,x,p,m)=-0.0$ if $x\geq0$
• $f(-0.0,x,p,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::mul_rational_prec_ref_val instead. If you know that your target precision is the precision of the Float input, consider using Float::mul_rational_round_ref_val instead. If both of these things are true, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact multiplication.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(product.to_string(), "1.0");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(product.to_string(), "1.06");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(product.to_string(), "1.06");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(product.to_string(), "1.047197");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(product.to_string(), "1.047199");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(product.to_string(), "1.047197");
assert_eq!(o, Less);

pub fn mul_rational_prec_round_ref_ref( &self, other: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float and the Rational are both taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(\pm\infty,0,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x>0$
• $f(\infty,x,p,m)=-\infty$ if $x<0$
• $f(-\infty,x,p,m)=-\infty$ if $x>0$
• $f(-\infty,x,p,m)=\infty$ if $x<0$
• $f(0.0,x,p,m)=0.0$ if $x\geq0$
• $f(0.0,x,p,m)=-0.0$ if $x<0$
• $f(-0.0,x,p,m)=-0.0$ if $x\geq0$
• $f(-0.0,x,p,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::mul_rational_prec_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using Float::mul_rational_round_ref_ref instead. If both of these things are true, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact multiplication.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(product.to_string(), "1.0");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(product.to_string(), "1.06");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(product.to_string(), "1.06");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(product.to_string(), "1.047197");
assert_eq!(o, Less);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(product.to_string(), "1.047199");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(product.to_string(), "1.047197");
assert_eq!(o, Less);

pub fn mul_rational_prec_ref_val( &self, other: Rational, prec: u64, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the product is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(\pm\infty,0,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x>0$
• $f(\infty,x,p)=-\infty$ if $x<0$
• $f(-\infty,x,p)=-\infty$ if $x>0$
• $f(-\infty,x,p)=\infty$ if $x<0$
• $f(0.0,x,p)=0.0$ if $x\geq0$
• $f(0.0,x,p)=-0.0$ if $x<0$
• $f(-0.0,x,p)=-0.0$ if $x\geq0$
• $f(-0.0,x,p)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::mul_rational_prec_round_ref_val instead. If you know that your target precision is the precision of the Float input, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_rational_prec_ref_val(Rational::exact_from(1.5), 5);
assert_eq!(product.to_string(), "4.8");
assert_eq!(o, Greater);

let (product, o) = Float::from(PI).mul_rational_prec_ref_val(Rational::exact_from(1.5), 20);
assert_eq!(product.to_string(), "4.712387");
assert_eq!(o, Less);

pub fn mul_rational_prec_ref_ref( &self, other: &Rational, prec: u64, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the product is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(\pm\infty,0,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x>0$
• $f(\infty,x,p)=-\infty$ if $x<0$
• $f(-\infty,x,p)=-\infty$ if $x>0$
• $f(-\infty,x,p)=\infty$ if $x<0$
• $f(0.0,x,p)=0.0$ if $x\geq0$
• $f(0.0,x,p)=-0.0$ if $x<0$
• $f(-0.0,x,p)=-0.0$ if $x\geq0$
• $f(-0.0,x,p)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::mul_rational_prec_round_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) = Float::from(PI).mul_rational_prec_ref_ref(&Rational::exact_from(1.5), 5);
assert_eq!(product.to_string(), "4.8");
assert_eq!(o, Greater);

let (product, o) =
    Float::from(PI).mul_rational_prec_ref_ref(&Rational::exact_from(1.5), 20);
assert_eq!(product.to_string(), "4.712387");
assert_eq!(o, Less);

pub fn mul_rational_round_ref_val( &self, other: Rational, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=f(\pm\infty,0,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x>0$
• $f(\infty,x,m)=-\infty$ if $x<0$
• $f(-\infty,x,m)=-\infty$ if $x>0$
• $f(-\infty,x,m)=\infty$ if $x<0$
• $f(0.0,x,m)=0.0$ if $x\geq0$
• $f(0.0,x,m)=-0.0$ if $x<0$
• $f(-0.0,x,m)=-0.0$ if $x\geq0$
• $f(-0.0,x,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::mul_rational_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) =
    Float::from(PI).mul_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(product.to_string(), "1.047197551196597");
assert_eq!(o, Less);

let (product, o) =
    Float::from(PI).mul_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(product.to_string(), "1.047197551196598");
assert_eq!(o, Greater);

let (product, o) =
    Float::from(PI).mul_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(product.to_string(), "1.047197551196598");
assert_eq!(o, Greater);

pub fn mul_rational_round_ref_ref( &self, other: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Multiplies a Float by a Rational, rounding the result with the specified rounding mode. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded product is less than, equal to, or greater than the exact product. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = xy+\varepsilon. $$

• If $xy$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $xy$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |xy|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $xy$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |xy|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=f(\pm\infty,0,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x>0$
• $f(\infty,x,m)=-\infty$ if $x<0$
• $f(-\infty,x,m)=-\infty$ if $x>0$
• $f(-\infty,x,m)=\infty$ if $x<0$
• $f(0.0,x,m)=0.0$ if $x\geq0$
• $f(0.0,x,m)=-0.0$ if $x<0$
• $f(-0.0,x,m)=-0.0$ if $x\geq0$
• $f(-0.0,x,m)=0.0$ if $x<0$

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::mul_rational_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using * instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (product, o) =
    Float::from(PI).mul_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(product.to_string(), "1.047197551196597");
assert_eq!(o, Less);

let (product, o) =
    Float::from(PI).mul_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(product.to_string(), "1.047197551196598");
assert_eq!(o, Greater);

let (product, o) =
    Float::from(PI).mul_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(product.to_string(), "1.047197551196598");
assert_eq!(o, Greater);

pub fn reciprocal_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Takes the reciprocal of a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal is less than, equal to, or greater than the exact reciprocal. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = 1/x+\varepsilon. $$

• If $1/x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |1/x|\rfloor-p+1}$.
• If $1/x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |1/x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=0.0$
• $f(-\infty,p,m)=-0.0$
• $f(0.0,p,m)=\infty$
• $f(-0.0,p,m)=-\infty$

Overflow:

• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.

This function cannot underflow.

If you know you’ll be using Nearest, consider using Float::reciprocal_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::reciprocal_round_ref instead. If both of these things are true, consider using (&Float)::reciprocal() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact reciprocation.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(5, Floor);
assert_eq!(reciprocal.to_string(), "0.31");
assert_eq!(o, Less);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(5, Ceiling);
assert_eq!(reciprocal.to_string(), "0.33");
assert_eq!(o, Greater);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(5, Nearest);
assert_eq!(reciprocal.to_string(), "0.31");
assert_eq!(o, Less);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(20, Floor);
assert_eq!(reciprocal.to_string(), "0.3183098");
assert_eq!(o, Less);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(20, Ceiling);
assert_eq!(reciprocal.to_string(), "0.3183103");
assert_eq!(o, Greater);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_round_ref(20, Nearest);
assert_eq!(reciprocal.to_string(), "0.3183098");
assert_eq!(o, Less);

pub fn reciprocal_prec_ref(&self, prec: u64) -> (Self, Ordering)

Takes the reciprocal of a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal is less than, equal to, or greater than the exact reciprocal. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the reciprocal is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = 1/x+\varepsilon. $$

• If $1/x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/x$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |1/x|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=0.0$
• $f(-\infty,p)=-0.0$
• $f(0.0,p)=\infty$
• $f(-0.0,p)=-\infty$

Overflow:

• If $f(x,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.

This function cannot underflow.

If you want to use a rounding mode other than Nearest, consider using Float::reciprocal_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float)::reciprocal() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal, o) = Float::from(PI).reciprocal_prec_ref(5);
assert_eq!(reciprocal.to_string(), "0.31");
assert_eq!(o, Less);

let (reciprocal, o) = Float::from(PI).reciprocal_prec_ref(20);
assert_eq!(reciprocal.to_string(), "0.3183098");
assert_eq!(o, Less);

pub fn reciprocal_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Takes the reciprocal of a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal is less than, equal to, or greater than the exact reciprocal. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = 1/x+\varepsilon. $$

• If $1/x$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/x$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |1/x|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $1/x$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |1/x|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=0.0$
• $f(-\infty,m)=-0.0$
• $f(0.0,m)=\infty$
• $f(-0.0,m)=-\infty$

Overflow:

• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.

This function cannot underflow.

If you want to specify an output precision, consider using Float::reciprocal_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float)::reciprocal() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Panics

Panics if rm is Exact but the precision of the input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal, o) = Float::from(PI).reciprocal_round_ref(Floor);
assert_eq!(reciprocal.to_string(), "0.3183098861837905");
assert_eq!(o, Less);

let (reciprocal, o) = Float::from(PI).reciprocal_round_ref(Ceiling);
assert_eq!(reciprocal.to_string(), "0.318309886183791");
assert_eq!(o, Greater);

let (reciprocal, o) = Float::from(PI).reciprocal_round_ref(Nearest);
assert_eq!(reciprocal.to_string(), "0.3183098861837905");
assert_eq!(o, Less);

pub fn reciprocal_sqrt_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes the reciprocal of the square root of a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The reciprocal square root of any nonzero negative number is NaN.

Using this function is more accurate than taking the square root and then the reciprocal, or vice versa.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = 1/\sqrt{x}+\varepsilon. $$

• If $1/\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/\sqrt{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 1/\sqrt{x}\rfloor-p+1}$.
• If $1/\sqrt{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 1/\sqrt{x}\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=0.0$
• $f(-\infty,p,m)=\text{NaN}$
• $f(0.0,p,m)=\infty$
• $f(-0.0,p,m)=\infty$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::reciprocal_sqrt_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::reciprocal_sqrt_round_ref instead. If both of these things are true, consider using (&Float).reciprocal_sqrt()instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(5, Floor);
assert_eq!(reciprocal_sqrt.to_string(), "0.56");
assert_eq!(o, Less);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(5, Ceiling);
assert_eq!(reciprocal_sqrt.to_string(), "0.59");
assert_eq!(o, Greater);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(5, Nearest);
assert_eq!(reciprocal_sqrt.to_string(), "0.56");
assert_eq!(o, Less);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(20, Floor);
assert_eq!(reciprocal_sqrt.to_string(), "0.564189");
assert_eq!(o, Less);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(20, Ceiling);
assert_eq!(reciprocal_sqrt.to_string(), "0.56419");
assert_eq!(o, Greater);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_round_ref(20, Nearest);
assert_eq!(reciprocal_sqrt.to_string(), "0.56419");
assert_eq!(o, Greater);

This is mpfr_rec_sqrt from rec_sqrt.c, MPFR 4.3.0.

pub fn reciprocal_sqrt_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes the reciprocal of the square root of a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The reciprocal square root of any nonzero negative number is NaN.

Using this function is more accurate than taking the square root and then the reciprocal, or vice versa.

If the reciprocal square root is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = 1/\sqrt{x}+\varepsilon. $$

• If $1/\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/\sqrt{x}$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 1/\sqrt{x}\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=0.0$
• $f(-\infty,p)=\text{NaN}$
• $f(0.0,p)=\infty$
• $f(-0.0,p)=\infty$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::reciprocal_sqrt_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).reciprocal_sqrt() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::PI;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_ref(5);
assert_eq!(reciprocal_sqrt.to_string(), "0.56");
assert_eq!(o, Less);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_prec_ref(20);
assert_eq!(reciprocal_sqrt.to_string(), "0.56419");
assert_eq!(o, Greater);

pub fn reciprocal_sqrt_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes the reciprocal of the square root of a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded reciprocal square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The reciprocal square root of any nonzero negative number is NaN.

Using this function is more accurate than taking the square root and then the reciprocal, or vice versa.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = 1/\sqrt{x}+\varepsilon. $$

• If $1/\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $1/\sqrt{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 1/\sqrt{x}\rfloor-p+1}$, where $p$ is the precision of the input.
• If $1/\sqrt{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 1/\sqrt{x}\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=0.0$
• $f(-\infty,m)=\text{NaN}$
• $f(0.0,m)=\infty$
• $f(-0.0,m)=\infty$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::reciprocal_sqrt_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).reciprocal_sqrt() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_round_ref(Floor);
assert_eq!(reciprocal_sqrt.to_string(), "0.564189583547756");
assert_eq!(o, Less);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_round_ref(Ceiling);
assert_eq!(reciprocal_sqrt.to_string(), "0.564189583547757");
assert_eq!(o, Greater);

let (reciprocal_sqrt, o) = Float::from(PI).reciprocal_sqrt_round_ref(Nearest);
assert_eq!(reciprocal_sqrt.to_string(), "0.564189583547757");
assert_eq!(o, Greater);

pub fn shl_prec_round_ref<T: PrimitiveInt>( &self, bits: T, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Left-shifts a Float (multiplies it by a power of 2), rounding the result with the specified rounding mode and precision, and taking the Float by reference.

NaN, infinities, and zeros are unchanged. If the output has a precision, it is prec.

$$ f(x,k,p,m) = x2^k. $$

• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is prec.
• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,k,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::shl_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::shl_round instead. If both of these things are true, or you don’t care about overflow or underflow behavior, consider using << instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Panics

Panics if rm is Exact and the result overflows or underflows, or cannot be expressed exactly with the specified precision.

Examples

See here.

pub fn shl_prec_ref<T: PrimitiveInt>( &self, bits: T, prec: u64, ) -> (Self, Ordering)

Left-shifts a Float (multiplies it by a power of 2), rounding the result with the specified precision, and taking the Float by reference.

NaN, infinities, and zeros are unchanged. If the output has a precision, it is prec.

$$ f(x,k,p) = x2^k. $$

• If $f(x,k,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,k,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,k,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you know that your target precision is the precision of the input, or you don’t care about overflow or underflow behavior, consider using << instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

See here.

pub fn shr_prec_round_ref<T: PrimitiveInt>( &self, bits: T, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Right-shifts a Float (divides it by a power of 2), rounding the result with the specified rounding mode and precision, and taking the Float by reference.

NaN, infinities, and zeros are unchanged. If the output has a precision, it is prec.

$$ f(x,k,p,m) = x/2^k. $$

• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,k,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is prec.
• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,k,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::shr_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::shr_round instead. If both of these things are true, or you don’t care about overflow or underflow behavior, consider using >> instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Panics

Panics if rm is Exact and the result overflows or underflows, or cannot be expressed exactly with the specified precision.

Examples

See here.

pub fn shr_prec_ref<T: PrimitiveInt>( &self, bits: T, prec: u64, ) -> (Self, Ordering)

Right-shifts a Float (divides it by a power of 2), rounding the result with the specified precision, and taking the Float by reference.

NaN, infinities, and zeros are unchanged. If the output has a precision, it is prec.

$$ f(x,k,p) = x/2^k. $$

• If $f(x,k,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,k,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,k,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,k,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,k,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,k,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you know that your target precision is the precision of the input, or you don’t care about overflow or underflow behavior, consider using >> instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

See here.

pub fn sqrt_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Computes the square root of a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The square root of any nonzero negative number is NaN.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = \sqrt{x}+\varepsilon. $$

• If $\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\sqrt{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \sqrt{x}\rfloor-p+1}$.
• If $\sqrt{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \sqrt{x}\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\infty,p,m)=\infty$
• $f(-\infty,p,m)=\text{NaN}$
• $f(0.0,p,m)=0.0$
• $f(-0.0,p,m)=-0.0$

Neither overflow nor underflow is possible.

If you know you’ll be using Nearest, consider using Float::sqrt_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::sqrt_round_ref instead. If both of these things are true, consider using (&Float).sqrt()instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but the result cannot be represented exactly with the given precision.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(5, Floor);
assert_eq!(sqrt.to_string(), "1.75");
assert_eq!(o, Less);

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(5, Ceiling);
assert_eq!(sqrt.to_string(), "1.81");
assert_eq!(o, Greater);

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(5, Nearest);
assert_eq!(sqrt.to_string(), "1.75");
assert_eq!(o, Less);

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(20, Floor);
assert_eq!(sqrt.to_string(), "1.772453");
assert_eq!(o, Less);

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(20, Ceiling);
assert_eq!(sqrt.to_string(), "1.772455");
assert_eq!(o, Greater);

let (sqrt, o) = Float::from(PI).sqrt_prec_round_ref(20, Nearest);
assert_eq!(sqrt.to_string(), "1.772453");
assert_eq!(o, Less);

pub fn sqrt_prec_ref(&self, prec: u64) -> (Self, Ordering)

Computes the square root of a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The square root of any nonzero negative number is NaN.

If the square root is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = \sqrt{x}+\varepsilon. $$

• If $\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\sqrt{x}$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 \sqrt{x}\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\infty,p)=\infty$
• $f(-\infty,p)=\text{NaN}$
• $f(0.0,p)=0.0$
• $f(-0.0,p)=-0.0$

Neither overflow nor underflow is possible.

If you want to use a rounding mode other than Nearest, consider using Float::sqrt_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).sqrt() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::PI;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sqrt, o) = Float::from(PI).sqrt_prec_ref(5);
assert_eq!(sqrt.to_string(), "1.75");
assert_eq!(o, Less);

let (sqrt, o) = Float::from(PI).sqrt_prec_ref(20);
assert_eq!(sqrt.to_string(), "1.772453");
assert_eq!(o, Less);

pub fn sqrt_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Computes the square root of a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square root is less than, equal to, or greater than the exact square root. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The square root of any nonzero negative number is NaN.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = \sqrt{x}+\varepsilon. $$

• If $\sqrt{x}$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $\sqrt{x}$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 \sqrt{x}\rfloor-p+1}$, where $p$ is the precision of the input.
• If $\sqrt{x}$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 \sqrt{x}\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\infty,m)=\infty$
• $f(-\infty,m)=\text{NaN}$
• $f(0.0,m)=0.0$
• $f(-0.0,m)=-0.0$

Neither overflow nor underflow is possible.

If you want to specify an output precision, consider using Float::sqrt_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).sqrt() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.get_prec().

Panics

Panics if rm is Exact but the result cannot be represented exactly with the input precision.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sqrt, o) = Float::from(PI).sqrt_round_ref(Floor);
assert_eq!(sqrt.to_string(), "1.772453850905515");
assert_eq!(o, Less);

let (sqrt, o) = Float::from(PI).sqrt_round_ref(Ceiling);
assert_eq!(sqrt.to_string(), "1.772453850905517");
assert_eq!(o, Greater);

let (sqrt, o) = Float::from(PI).sqrt_round_ref(Nearest);
assert_eq!(sqrt.to_string(), "1.772453850905515");
assert_eq!(o, Less);

pub fn square_prec_round_ref( &self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Squares a Float, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square is less than, equal to, or greater than the exact square. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,p,m) = x^2+\varepsilon. $$

• If $x^2$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x^2$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x^2|\rfloor-p+1}$.
• If $x^2$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x^2|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p,m)=\text{NaN}$
• $f(\pm\infty,p,m)=\infty$
• $f(\pm0.0,p,m)=0.0$

Overflow and underflow:

• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::square_prec_ref instead. If you know that your target precision is the precision of the input, consider using Float::square_round_ref instead. If both of these things are true, consider using (&Float).square()instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is self.significant_bits(), and $m$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact squaring.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (square, o) = Float::from(PI).square_prec_round_ref(5, Floor);
assert_eq!(square.to_string(), "9.5");
assert_eq!(o, Less);

let (square, o) = Float::from(PI).square_prec_round_ref(5, Ceiling);
assert_eq!(square.to_string(), "10.0");
assert_eq!(o, Greater);

let (square, o) = Float::from(PI).square_prec_round_ref(5, Nearest);
assert_eq!(square.to_string(), "10.0");
assert_eq!(o, Greater);

let (square, o) = Float::from(PI).square_prec_round_ref(20, Floor);
assert_eq!(square.to_string(), "9.8696");
assert_eq!(o, Less);

let (square, o) = Float::from(PI).square_prec_round_ref(20, Ceiling);
assert_eq!(square.to_string(), "9.86961");
assert_eq!(o, Greater);

let (square, o) = Float::from(PI).square_prec_round_ref(20, Nearest);
assert_eq!(square.to_string(), "9.8696");
assert_eq!(o, Less);

pub fn square_prec_ref(&self, prec: u64) -> (Self, Ordering)

Squares a Float, rounding the result to the nearest value of the specified precision. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square is less than, equal to, or greater than the exact square. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the square is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,p) = x^2+\varepsilon. $$

• If $x^2$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x^2$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x^2|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},p)=\text{NaN}$
• $f(\pm\infty,p)=\infty$
• $f(\pm0.0,p)=0.0$

Overflow and underflow:

• If $f(x,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::square_prec_round_ref instead. If you know that your target precision is the precision of the input, consider using (&Float).square() instead.

Worst-case complexity

$T(n, m) = O(n \log n \log\log n + m)$

$M(n, m) = O(n \log n + m)$

where $T$ is time, $M$ is additional memory, $n$ is self.significant_bits(), and $m$ is prec.

Examples

use core::f64::consts::PI;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (square, o) = Float::from(PI).square_prec_ref(5);
assert_eq!(square.to_string(), "10.0");
assert_eq!(o, Greater);

let (square, o) = Float::from(PI).square_prec_ref(20);
assert_eq!(square.to_string(), "9.8696");
assert_eq!(o, Less);

pub fn square_round_ref(&self, rm: RoundingMode) -> (Self, Ordering)

Squares a Float, rounding the result with the specified rounding mode. The Float is taken by reference. An Ordering is also returned, indicating whether the rounded square is less than, equal to, or greater than the exact square. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,m) = x^2+\varepsilon. $$

• If $x^2$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x^2$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x^2|\rfloor-p+1}$, where $p$ is the precision of the input.
• If $x^2$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x^2|\rfloor-p}$, where $p$ is the precision of the input.

If the output has a precision, it is the precision of the input.

Special cases:

• $f(\text{NaN},m)=\text{NaN}$
• $f(\pm\infty,m)=\infty$
• $f(\pm0.0,m)=0.0$

Overflow and underflow:

• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::square_prec_round_ref instead. If you know you’ll be using the Nearest rounding mode, consider using (&Float).square() instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Panics

Panics if rm is Exact but the precision of the input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (square, o) = Float::from(PI).square_round_ref(Floor);
assert_eq!(square.to_string(), "9.86960440108935");
assert_eq!(o, Less);

let (square, o) = Float::from(PI).square_round_ref(Ceiling);
assert_eq!(square.to_string(), "9.86960440108936");
assert_eq!(o, Greater);

let (square, o) = Float::from(PI).square_round_ref(Nearest);
assert_eq!(square.to_string(), "9.86960440108936");
assert_eq!(o, Greater);

pub fn sub_prec_round_ref_val( &self, other: Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts two Floats, rounding the result to the specified precision and with the specified rounding mode. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\infty,\infty,p,m)=f(-\infty,-\infty,p,m)= \text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,p,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p,m)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,p,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,p,m)=0.0$
• $f(-0.0,0.0,p,m)=-0.0$
• $f(0.0,0.0,p,m)=f(-0.0,-0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,p,m)=f(-0.0,-0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,x,p,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,p,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::sub_prec_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::sub_round_ref_val instead. If both of these things are true, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact subtraction.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 5, Floor);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 5, Ceiling);
assert_eq!(sum.to_string(), "0.44");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 5, Nearest);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 20, Floor);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 20, Ceiling);
assert_eq!(sum.to_string(), "0.4233112");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_prec_round_ref_val(Float::from(E), 20, Nearest);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

pub fn sub_prec_round_ref_ref( &self, other: &Self, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts two Floats, rounding the result to the specified precision and with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=f(x,\text{NaN},p,m)=f(\infty,\infty,p,m)=f(-\infty,-\infty,p,m)= \text{NaN}$
• $f(\infty,x,p,m)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,p,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p,m)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,p,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,p,m)=0.0$
• $f(-0.0,0.0,p,m)=-0.0$
• $f(0.0,0.0,p,m)=f(-0.0,-0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,p,m)=f(-0.0,-0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,x,p,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,p,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::sub_prec_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using Float::sub_round_ref_ref instead. If both of these things are true, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Panics

Panics if rm is Exact but prec is too small for an exact subtraction.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 5, Floor);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 5, Ceiling);
assert_eq!(sum.to_string(), "0.44");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 5, Nearest);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 20, Floor);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 20, Ceiling);
assert_eq!(sum.to_string(), "0.4233112");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_prec_round_ref_ref(&Float::from(E), 20, Nearest);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

pub fn sub_prec_ref_val(&self, other: Self, prec: u64) -> (Self, Ordering)

Subtracts two Floats, rounding the result to the nearest value of the specified precision. The first Float is taken by reference and the second by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the difference is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\infty,\infty,p)=f(-\infty,-\infty,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,p)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,p)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,p)=0.0$
• $f(-0.0,0.0,p)=-0.0$
• $f(0.0,0.0,p)=f(-0.0,-0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,p)=f(-0.0,-0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,x,p)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,p)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::sub_prec_round_ref_val instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_prec_ref_val(Float::from(E), 5);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_ref_val(Float::from(E), 20);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

pub fn sub_prec_ref_ref(&self, other: &Self, prec: u64) -> (Self, Ordering)

Subtracts two Floats, rounding the result to the nearest value of the specified precision. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the difference is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=f(x,\text{NaN},p)=f(\infty,\infty,p)=f(-\infty,-\infty,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,p)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,p)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,p)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,p)=0.0$
• $f(-0.0,0.0,p)=-0.0$
• $f(0.0,0.0,p)=f(-0.0,-0.0,p,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,p)=f(-0.0,-0.0,p,m)=-0.0$ if $m$ is Floor
• $f(x,x,p)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,p)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::sub_prec_round_ref_ref instead. If you know that your target precision is the maximum of the precisions of the two inputs, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is prec.

Examples

use core::f64::consts::{E, PI};
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_prec_ref_ref(&Float::from(E), 5);
assert_eq!(sum.to_string(), "0.42");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_prec_ref_ref(&Float::from(E), 20);
assert_eq!(sum.to_string(), "0.4233108");
assert_eq!(o, Less);

pub fn sub_round_ref_val( &self, other: Self, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts two Floats, rounding the result with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\infty,\infty,m)=f(-\infty,-\infty,m)= \text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,m)=0.0$
• $f(-0.0,0.0,m)=-0.0$
• $f(0.0,0.0,m)=f(-0.0,-0.0,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,m)=f(-0.0,-0.0,m)=-0.0$ if $m$ is Floor
• $f(x,x,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::sub_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(m)$

where $T$ is time, $M$ is additional memory, $n$ is max(self.significant_bits(), other.significant_bits()), and $m$ is self.significant_bits().

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_round_ref_val(Float::from(-E), Floor);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_round_ref_val(Float::from(-E), Ceiling);
assert_eq!(sum.to_string(), "5.859874482048839");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_round_ref_val(Float::from(-E), Nearest);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

pub fn sub_round_ref_ref( &self, other: &Self, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts two Floats, rounding the result with the specified rounding mode. Both Floats are taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the maximum of the precision of the inputs. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$, where $p$ is the maximum precision of the inputs.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$, where $p$ is the maximum precision of the inputs.

If the output has a precision, it is the maximum of the precisions of the inputs.

Special cases:

• $f(\text{NaN},x,m)=f(x,\text{NaN},m)=f(\infty,\infty,m)=f(-\infty,-\infty,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $\infty$
• $f(x,-\infty,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $-\infty$
• $f(x,\infty,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,-0.0,m)=0.0$
• $f(-0.0,0.0,m)=-0.0$
• $f(0.0,0.0,m)=f(-0.0,-0.0,m)=0.0$ if $m$ is not Floor
• $f(0.0,0.0,m)=f(-0.0,-0.0,m)=-0.0$ if $m$ is Floor
• $f(x,x,m)=0.0$ if $x$ is finite and nonzero and $m$ is not Floor
• $f(x,x,m)=-0.0$ if $x$ is finite and nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::sub_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using - instead.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the maximum precision of the inputs is not high enough to represent the output.

Examples

use core::f64::consts::{E, PI};
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_round_ref_ref(&Float::from(-E), Floor);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_round_ref_ref(&Float::from(-E), Ceiling);
assert_eq!(sum.to_string(), "5.859874482048839");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_round_ref_ref(&Float::from(-E), Nearest);
assert_eq!(sum.to_string(), "5.859874482048838");
assert_eq!(o, Less);

pub fn sub_rational_prec_round_ref_val( &self, other: Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$
• $f(-\infty,x,p,m)=-\infty$
• $f(0.0,0,p,m)=0.0$
• $f(-0.0,0,p,m)=-0.0$
• $f(x,x,p,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,x,p,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::sub_rational_prec_ref_val instead. If you know that your target precision is the precision of the Float input, consider using Float::sub_rational_round_ref_val instead. If both of these things are true, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact subtraction.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(sum.to_string(), "2.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(sum.to_string(), "2.9");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(sum.to_string(), "2.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(sum.to_string(), "2.808258");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(sum.to_string(), "2.808262");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_val(
    Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(sum.to_string(), "2.808258");
assert_eq!(o, Less);

pub fn sub_rational_prec_round_ref_ref( &self, other: &Rational, prec: u64, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result to the specified precision and with the specified rounding mode. The Float and the Rational are both taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,p,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p,m)=\text{NaN}$
• $f(\infty,x,p,m)=\infty$
• $f(-\infty,x,p,m)=-\infty$
• $f(0.0,0,p,m)=0.0$
• $f(-0.0,0,p,m)=-0.0$
• $f(x,x,p,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,x,p,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,p,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,p,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you know you’ll be using Nearest, consider using Float::sub_rational_prec_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using Float::sub_rational_round_ref_ref instead. If both of these things are true, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Panics

Panics if rm is Exact but prec is too small for an exact subtraction.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Floor,
);
assert_eq!(sum.to_string(), "2.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Ceiling,
);
assert_eq!(sum.to_string(), "2.9");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    5,
    Nearest,
);
assert_eq!(sum.to_string(), "2.8");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Floor,
);
assert_eq!(sum.to_string(), "2.808258");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Ceiling,
);
assert_eq!(sum.to_string(), "2.808262");
assert_eq!(o, Greater);

let (sum, o) = Float::from(PI).sub_rational_prec_round_ref_ref(
    &Rational::from_unsigneds(1u8, 3),
    20,
    Nearest,
);
assert_eq!(sum.to_string(), "2.808258");
assert_eq!(o, Less);

pub fn sub_rational_prec_ref_val( &self, other: Rational, prec: u64, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the difference is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$
• $f(-\infty,x,p)=-\infty$
• $f(0.0,0,p)=0.0$
• $f(-0.0,0,p)=-0.0$
• $f(x,x,p)=0.0$ if $x$ is nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::sub_rational_prec_round_ref_val instead. If you know that your target precision is the precision of the Float input, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_rational_prec_ref_val(Rational::exact_from(1.5), 5);
assert_eq!(sum.to_string(), "1.62");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_ref_val(Rational::exact_from(1.5), 20);
assert_eq!(sum.to_string(), "1.641592");
assert_eq!(o, Less);

pub fn sub_rational_prec_ref_ref( &self, other: &Rational, prec: u64, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result to the nearest value of the specified precision. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

If the difference is equidistant from two Floats with the specified precision, the Float with fewer 1s in its binary expansion is chosen. See RoundingMode for a description of the Nearest rounding mode.

$$ f(x,y,p) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p}$.

If the output has a precision, it is prec.

Special cases:

• $f(\text{NaN},x,p)=\text{NaN}$
• $f(\infty,x,p)=\infty$
• $f(-\infty,x,p)=-\infty$
• $f(0.0,0,p)=0.0$
• $f(-0.0,0,p)=-0.0$
• $f(x,x,p)=0.0$ if $x$ is nonzero

Overflow and underflow:

• If $f(x,y,p)\geq 2^{2^{30}-1}$, $\infty$ is returned instead.
• If $f(x,y,p)\geq 2^{2^{30}-1}$, $-\infty$ is returned instead.
• If $0<f(x,y,p)\leq2^{-2^{30}-1}$, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,p)<2^{-2^{30}}$, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,p)<0$, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,p)<-2^{-2^{30}-1}$, $-2^{-2^{30}}$ is returned instead.

If you want to use a rounding mode other than Nearest, consider using Float::sub_rational_prec_round_ref_ref instead. If you know that your target precision is the precision of the Float input, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(other.significant_bits(), prec).

Examples

use core::f64::consts::PI;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) = Float::from(PI).sub_rational_prec_ref_ref(&Rational::exact_from(1.5), 5);
assert_eq!(sum.to_string(), "1.62");
assert_eq!(o, Less);

let (sum, o) = Float::from(PI).sub_rational_prec_ref_ref(&Rational::exact_from(1.5), 20);
assert_eq!(sum.to_string(), "1.641592");
assert_eq!(o, Less);

pub fn sub_rational_round_ref_val( &self, other: Rational, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result with the specified rounding mode. The Float is taken by reference and the Rational by value. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0,m)=0.0$
• $f(-0.0,0,m)=-0.0$
• $f(x,0,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(0.0,x,m)=f(-0.0,x,m)=-x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,x,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,x,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::sub_rational_prec_round_ref_val instead. If you know you’ll be using the Nearest rounding mode, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(sum.to_string(), "2.808259320256457");
assert_eq!(o, Less);

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(sum.to_string(), "2.808259320256461");
assert_eq!(o, Greater);

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_val(Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(sum.to_string(), "2.808259320256461");
assert_eq!(o, Greater);

pub fn sub_rational_round_ref_ref( &self, other: &Rational, rm: RoundingMode, ) -> (Self, Ordering)

Subtracts a Float by a Rational, rounding the result with the specified rounding mode. The Float and the Rational are both are taken by reference. An Ordering is also returned, indicating whether the rounded difference is less than, equal to, or greater than the exact difference. Although NaNs are not comparable to any Float, whenever this function returns a NaN it also returns Equal.

The precision of the output is the precision of the Float input. See RoundingMode for a description of the possible rounding modes.

$$ f(x,y,m) = x-y+\varepsilon. $$

• If $x-y$ is infinite, zero, or NaN, $\varepsilon$ may be ignored or assumed to be 0.
• If $x-y$ is finite and nonzero, and $m$ is not Nearest, then $|\varepsilon| < 2^{\lfloor\log_2 |x-y|\rfloor-p+1}$, where $p$ is the precision of the input Float.
• If $x-y$ is finite and nonzero, and $m$ is Nearest, then $|\varepsilon| \leq 2^{\lfloor\log_2 |x-y|\rfloor-p}$, where $p$ is the precision of the input Float.

If the output has a precision, it is the precision of the Float input.

Special cases:

• $f(\text{NaN},x,m)=\text{NaN}$
• $f(\infty,x,m)=\infty$ if $x$ is not NaN or $-\infty$
• $f(-\infty,x,m)=-\infty$ if $x$ is not NaN or $\infty$
• $f(0.0,0,m)=0.0$
• $f(-0.0,0,m)=-0.0$
• $f(x,0,m)=x$ if $x$ is not NaN and $x$ is nonzero
• $f(0.0,x,m)=f(-0.0,x,m)=-x$ if $x$ is not NaN and $x$ is nonzero
• $f(x,x,m)=0.0$ if $x$ is nonzero and $m$ is not Floor
• $f(x,x,m)=-0.0$ if $x$ is nonzero and $m$ is Floor

Overflow and underflow:

• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling, Up, or Nearest, $\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor or Down, $(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Floor, Up, or Nearest, $-\infty$ is returned instead.
• If $f(x,y,m)\geq 2^{2^{30}-1}$ and $m$ is Ceiling or Down, $-(1-(1/2)^p)2^{2^{30}-1}$ is returned instead, where p is the precision of the input.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Floor or Down, $0.0$ is returned instead.
• If $0<f(x,y,m)<2^{-2^{30}}$, and $m$ is Ceiling or Up, $2^{-2^{30}}$ is returned instead.
• If $0<f(x,y,m)\leq2^{-2^{30}-1}$, and $m$ is Nearest, $0.0$ is returned instead.
• If $2^{-2^{30}-1}<f(x,y,m)<2^{-2^{30}}$, and $m$ is Nearest, $2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Ceiling or Down, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<0$, and $m$ is Floor or Up, $-2^{-2^{30}}$ is returned instead.
• If $-2^{-2^{30}-1}\leq f(x,y,m)<0$, and $m$ is Nearest, $-0.0$ is returned instead.
• If $-2^{-2^{30}}<f(x,y,m)<-2^{-2^{30}-1}$, and $m$ is Nearest, $-2^{-2^{30}}$ is returned instead.

If you want to specify an output precision, consider using Float::sub_rational_prec_round_ref_ref instead. If you know you’ll be using the Nearest rounding mode, consider using - instead.

Worst-case complexity

$T(n) = O(n \log n \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Panics

Panics if rm is Exact but the precision of the Float input is not high enough to represent the output.

Examples

use core::f64::consts::PI;
use malachite_base::rounding_modes::RoundingMode::*;
use malachite_float::Float;
use malachite_q::Rational;
use std::cmp::Ordering::*;

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Floor);
assert_eq!(sum.to_string(), "2.808259320256457");
assert_eq!(o, Less);

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Ceiling);
assert_eq!(sum.to_string(), "2.808259320256461");
assert_eq!(o, Greater);

let (sum, o) =
    Float::from(PI).sub_rational_round_ref_ref(&Rational::from_unsigneds(1u8, 3), Nearest);
assert_eq!(sum.to_string(), "2.808259320256461");
assert_eq!(o, Greater);

pub fn is_nan(&self) -> bool

Determines whether a Float is NaN.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{NaN, One};
use malachite_float::Float;

assert_eq!(Float::NAN.is_nan(), true);
assert_eq!(Float::ONE.is_nan(), false);

pub fn is_finite(&self) -> bool

Determines whether a Float is finite.

NaN is not finite.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, One};
use malachite_float::Float;

assert_eq!(Float::NAN.is_finite(), false);
assert_eq!(Float::INFINITY.is_finite(), false);
assert_eq!(Float::ONE.is_finite(), true);

pub fn is_infinite(&self) -> bool

Determines whether a Float is infinite.

NaN is not infinite.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, One};
use malachite_float::Float;

assert_eq!(Float::NAN.is_infinite(), false);
assert_eq!(Float::INFINITY.is_infinite(), true);
assert_eq!(Float::ONE.is_infinite(), false);

pub fn is_positive_zero(&self) -> bool

Determines whether a Float is positive zero.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.is_positive_zero(), false);
assert_eq!(Float::INFINITY.is_positive_zero(), false);
assert_eq!(Float::ONE.is_positive_zero(), false);
assert_eq!(Float::ZERO.is_positive_zero(), true);
assert_eq!(Float::NEGATIVE_ZERO.is_positive_zero(), false);

pub fn is_negative_zero(&self) -> bool

Determines whether a Float is negative zero.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.is_negative_zero(), false);
assert_eq!(Float::INFINITY.is_negative_zero(), false);
assert_eq!(Float::ONE.is_negative_zero(), false);
assert_eq!(Float::ZERO.is_negative_zero(), false);
assert_eq!(Float::NEGATIVE_ZERO.is_negative_zero(), true);

pub fn is_zero(&self) -> bool

Determines whether a Float is zero (positive or negative).

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.is_zero(), false);
assert_eq!(Float::INFINITY.is_zero(), false);
assert_eq!(Float::ONE.is_zero(), false);
assert_eq!(Float::ZERO.is_zero(), true);
assert_eq!(Float::NEGATIVE_ZERO.is_zero(), true);

pub fn is_normal(&self) -> bool

Determines whether a Float is normal, that is, finite and nonzero.

There is no notion of subnormal Floats.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.is_normal(), false);
assert_eq!(Float::INFINITY.is_normal(), false);
assert_eq!(Float::ZERO.is_normal(), false);
assert_eq!(Float::NEGATIVE_ZERO.is_normal(), false);
assert_eq!(Float::ONE.is_normal(), true);

pub fn is_sign_positive(&self) -> bool

Determines whether a Float’s sign is positive.

A NaN has no sign, so this function returns false when given a NaN.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, Zero,
};
use malachite_float::Float;

assert_eq!(Float::NAN.is_sign_positive(), false);
assert_eq!(Float::INFINITY.is_sign_positive(), true);
assert_eq!(Float::NEGATIVE_INFINITY.is_sign_positive(), false);
assert_eq!(Float::ZERO.is_sign_positive(), true);
assert_eq!(Float::NEGATIVE_ZERO.is_sign_positive(), false);
assert_eq!(Float::ONE.is_sign_positive(), true);
assert_eq!(Float::NEGATIVE_ONE.is_sign_positive(), false);

pub fn is_sign_negative(&self) -> bool

Determines whether a Float’s sign is negative.

A NaN has no sign, so this function returns false when given a NaN.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, Zero,
};
use malachite_float::Float;

assert_eq!(Float::NAN.is_sign_negative(), false);
assert_eq!(Float::INFINITY.is_sign_negative(), false);
assert_eq!(Float::NEGATIVE_INFINITY.is_sign_negative(), true);
assert_eq!(Float::ZERO.is_sign_negative(), false);
assert_eq!(Float::NEGATIVE_ZERO.is_sign_negative(), true);
assert_eq!(Float::ONE.is_sign_negative(), false);
assert_eq!(Float::NEGATIVE_ONE.is_sign_negative(), true);

pub fn classify(&self) -> FpCategory

Classifies a Float into one of several categories.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, Zero,
};
use malachite_float::Float;
use std::num::FpCategory;

assert_eq!(Float::NAN.classify(), FpCategory::Nan);
assert_eq!(Float::INFINITY.classify(), FpCategory::Infinite);
assert_eq!(Float::NEGATIVE_INFINITY.classify(), FpCategory::Infinite);
assert_eq!(Float::ZERO.classify(), FpCategory::Zero);
assert_eq!(Float::NEGATIVE_ZERO.classify(), FpCategory::Zero);
assert_eq!(Float::ONE.classify(), FpCategory::Normal);
assert_eq!(Float::NEGATIVE_ONE.classify(), FpCategory::Normal);

pub fn to_non_nan(&self) -> Option<Self>

Turns a NaN into a None and wraps any non-NaN Float with a Some. The Float is taken by reference.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.to_non_nan(), None);
assert_eq!(Float::INFINITY.to_non_nan(), Some(Float::INFINITY));
assert_eq!(Float::ZERO.to_non_nan(), Some(Float::ZERO));
assert_eq!(
    Float::NEGATIVE_ZERO.to_non_nan(),
    Some(Float::NEGATIVE_ZERO)
);
assert_eq!(Float::ONE.to_non_nan(), Some(Float::ONE));

pub fn to_finite(&self) -> Option<Self>

Turns any Float that’s NaN or infinite into a None and wraps any finite Float with a Some. The Float is taken by reference.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, NegativeZero, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.to_finite(), None);
assert_eq!(Float::INFINITY.to_finite(), None);
assert_eq!(Float::ZERO.to_finite(), Some(Float::ZERO));
assert_eq!(Float::NEGATIVE_ZERO.to_finite(), Some(Float::NEGATIVE_ZERO));
assert_eq!(Float::ONE.to_finite(), Some(Float::ONE));

pub fn complexity(&self) -> u64

Determines a Float’s complexity. The complexity is defined as follows:

$$ f(\text{NaN}) = f(\pm\infty) = f(\pm 0.0) = 1, $$

and, if $x$ is finite and nonzero,

$$ f(x) = \max(|\lfloor \log_2 x\rfloor|, p), $$

where $p$ is the precision of $x$.

Informally, the complexity is proportional to the number of characters you would need to write the Float out without using exponents.

See also the Float implementation of SignificantBits.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::arithmetic::traits::PowerOf2;
use malachite_base::num::basic::traits::{NaN, One};
use malachite_float::Float;

assert_eq!(Float::NAN.complexity(), 1);
assert_eq!(Float::ONE.complexity(), 1);
assert_eq!(Float::one_prec(100).complexity(), 100);
assert_eq!(Float::from(std::f64::consts::PI).complexity(), 50);
assert_eq!(Float::power_of_2(100u64).complexity(), 100);
assert_eq!(Float::power_of_2(-100i64).complexity(), 100);

pub const MIN_POSITIVE: Self

pub fn abs_is_min_positive_value(&self) -> bool

Returns whether the absolute value of a Float is equal to the minimum representable positive value, or $2^{-2^{30}}$.

$$ f(x) = (|x|=2^{-2^{30}}). $$

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_float::Float;

assert!(Float::min_positive_value_prec(100).abs_is_min_positive_value());
assert!((-Float::min_positive_value_prec(100)).abs_is_min_positive_value());
assert!(!(Float::min_positive_value_prec(100) << 1u32).abs_is_min_positive_value());

pub fn abs_is_max_finite_value_with_prec(&self) -> bool

Returns whether the absolute value of a Float is equal to the maximum representable finite value with that precision.

$$ f(x) = (|x|=(1-(1/2)^p)2^{2^{30}-1}), $$ where $p$ is the precision of the $x$.

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_float::Float;

assert!(Float::max_finite_value_with_prec(100).abs_is_max_finite_value_with_prec());
assert!((-Float::max_finite_value_with_prec(100)).abs_is_max_finite_value_with_prec());
assert!(
    !(Float::max_finite_value_with_prec(100) >> 1u32).abs_is_max_finite_value_with_prec()
);

pub fn to_significand(&self) -> Option<Natural>

Gets the significand of a Float, taking the Float by value.

The significand is the smallest positive integer which is some power of 2 times the Float, and whose number of significant bits is a multiple of the limb width. If the Float is NaN, infinite, or zero, then None is returned.

Worst-case complexity

Constant time and additional memory.

Examples

#[cfg(not(feature = "32_bit_limbs"))]
use malachite_base::num::arithmetic::traits::PowerOf2;
#[cfg(not(feature = "32_bit_limbs"))]
use malachite_base::num::basic::traits::One;
use malachite_base::num::basic::traits::{Infinity, NaN, Zero};
use malachite_float::Float;
#[cfg(not(feature = "32_bit_limbs"))]
use malachite_nz::natural::Natural;

assert_eq!(Float::NAN.to_significand(), None);
assert_eq!(Float::INFINITY.to_significand(), None);
assert_eq!(Float::ZERO.to_significand(), None);

#[cfg(not(feature = "32_bit_limbs"))]
{
    assert_eq!(Float::ONE.to_significand(), Some(Natural::power_of_2(63)));
    assert_eq!(
        Float::from(std::f64::consts::PI).to_significand().unwrap(),
        14488038916154245120u64
    );
}

pub fn significand_ref(&self) -> Option<&Natural>

Returns a reference to the significand of a Float.

The significand is the smallest positive integer which is some power of 2 times the Float, and whose number of significant bits is a multiple of the limb width. If the Float is NaN, infinite, or zero, then None is returned.

Worst-case complexity

Constant time and additional memory.

Examples

#[cfg(not(feature = "32_bit_limbs"))]
use malachite_base::num::arithmetic::traits::PowerOf2;
#[cfg(not(feature = "32_bit_limbs"))]
use malachite_base::num::basic::traits::One;
use malachite_base::num::basic::traits::{Infinity, NaN, Zero};
use malachite_float::Float;
#[cfg(not(feature = "32_bit_limbs"))]
use malachite_nz::natural::Natural;

assert_eq!(Float::NAN.significand_ref(), None);
assert_eq!(Float::INFINITY.significand_ref(), None);
assert_eq!(Float::ZERO.significand_ref(), None);

#[cfg(not(feature = "32_bit_limbs"))]
{
    assert_eq!(
        *Float::ONE.significand_ref().unwrap(),
        Natural::power_of_2(63)
    );
    assert_eq!(
        *Float::from(std::f64::consts::PI).significand_ref().unwrap(),
        14488038916154245120u64
    );
}

pub fn get_exponent(&self) -> Option<i32>

Returns a Float’s exponent.

$$ f(\text{NaN}) = f(\pm\infty) = f(\pm 0.0) = \text{None}, $$

and, if $x$ is finite and nonzero,

$$ f(x) = \operatorname{Some}(\lfloor \log_2 |x| \rfloor + 1). $$

The output is in the range $[-(2^{30}-1), 2^{30}-1]$.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::arithmetic::traits::PowerOf2;
use malachite_base::num::basic::traits::{Infinity, NaN, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.get_exponent(), None);
assert_eq!(Float::INFINITY.get_exponent(), None);
assert_eq!(Float::ZERO.get_exponent(), None);

assert_eq!(Float::ONE.get_exponent(), Some(1));
assert_eq!(Float::from(std::f64::consts::PI).get_exponent(), Some(2));
assert_eq!(Float::power_of_2(100u64).get_exponent(), Some(101));
assert_eq!(Float::power_of_2(-100i64).get_exponent(), Some(-99));

pub fn get_prec(&self) -> Option<u64>

Returns a Float’s precision. The precision is a positive integer denoting how many of the Float’s bits are significant.

Only Floats that are finite and nonzero have a precision. For other Floats, None is returned.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.get_prec(), None);
assert_eq!(Float::INFINITY.get_prec(), None);
assert_eq!(Float::ZERO.get_prec(), None);

assert_eq!(Float::ONE.get_prec(), Some(1));
assert_eq!(Float::one_prec(100).get_prec(), Some(100));
assert_eq!(Float::from(std::f64::consts::PI).get_prec(), Some(50));

pub fn get_min_prec(&self) -> Option<u64>

Returns the minimum precision necessary to represent the given Float’s value.

For example, Float:one_prec(100) has a precision of 100, but its minimum precision is 1, because that’s all that’s necessary to represent the value 1.

The minimum precision is always less than or equal to the actual precision.

Only Floats that are finite and nonzero have a minimum precision. For other Floats, None is returned.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::basic::traits::{Infinity, NaN, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.get_min_prec(), None);
assert_eq!(Float::INFINITY.get_min_prec(), None);
assert_eq!(Float::ZERO.get_min_prec(), None);

assert_eq!(Float::ONE.get_min_prec(), Some(1));
assert_eq!(Float::one_prec(100).get_min_prec(), Some(1));
assert_eq!(Float::from(std::f64::consts::PI).get_min_prec(), Some(50));

pub fn ulp(&self) -> Option<Self>

Gets a Float’s ulp (unit in last place, or unit of least precision).

If the Float is positive, its ulp is the distance to the next-largest Float with the same precision; if it is negative, the next-smallest. (This definition works even if the Float is the largest in its binade. If the Float is the largest in its binade and has the maximum exponent, we can define its ulp to be the distance to the next-smallest Float with the same precision if positive, and to the next-largest Float with the same precision if negative.)

If the Float is NaN, infinite, or zero, then None is returned.

This function does not overflow or underflow, technically. But it is possible that a Float’s ulp is too small to represent, for example if the Float has the minimum exponent and its precision is greater than 1, or if the precision is extremely large in general. In such cases, None is returned.

$$ f(\text{NaN}) = f(\pm\infty) = f(\pm 0.0) = \text{None}, $$

and, if $x$ is finite and nonzero,

$$ f(x) = \operatorname{Some}(2^{\lfloor \log_2 |x| \rfloor-p+1}), $$ where $p$ is the precision of $x$.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is self.significant_bits().

Examples

use malachite_base::num::arithmetic::traits::PowerOf2;
use malachite_base::num::basic::traits::{Infinity, NaN, NegativeOne, One, Zero};
use malachite_float::Float;

assert_eq!(Float::NAN.ulp(), None);
assert_eq!(Float::INFINITY.ulp(), None);
assert_eq!(Float::ZERO.ulp(), None);

let s = Float::ONE.ulp().map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("1.0"));

let s = Float::one_prec(100).ulp().map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("2.0e-30"));

let s = Float::from(std::f64::consts::PI)
    .ulp()
    .map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("4.0e-15"));

let s = Float::power_of_2(100u64).ulp().map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("1.0e30"));

let s = Float::power_of_2(-100i64).ulp().map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("8.0e-31"));

let s = Float::NEGATIVE_ONE.ulp().map(|x| x.to_string());
assert_eq!(s.as_ref().map(|s| s.as_str()), Some("1.0"));

pub fn sci_mantissa_and_exponent_round<T: PrimitiveFloat>( &self, rm: RoundingMode, ) -> Option<(T, i32, Ordering)>

Returns a Float’s scientific mantissa and exponent, rounding according to the specified rounding mode. An Ordering is also returned, indicating whether the mantissa and exponent represent a value that is less than, equal to, or greater than the original value.

When $x$ is positive, we can write $x = 2^{e_s}m_s$, where $e_s$ is an integer and $m_s$ is a rational number with $1 \leq m_s < 2$. We represent the rational mantissa as a float. The conversion might not be exact, so we round to the nearest float using the provided rounding mode. If the rounding mode is Exact but the conversion is not exact, None is returned. $$ f(x, r) \approx \left (\frac{x}{2^{\lfloor \log_2 x \rfloor}}, \lfloor \log_2 x \rfloor\right ). $$

This function does not overflow or underflow. The returned exponent is always in the range $[-2^{30}, 2^{30}-1]$. Notice that although a Float’s maximum scientific exponent is $2^{30}-2$, this function may return an exponent one larger than this limit due to rounding.

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::arithmetic::traits::Pow;
use malachite_base::num::conversion::traits::ExactFrom;
use malachite_base::num::float::NiceFloat;
use malachite_base::rounding_modes::RoundingMode::{self, *};
use malachite_float::Float;
use malachite_nz::natural::Natural;
use std::cmp::Ordering::{self, *};

let test = |x: Float, rm: RoundingMode, out: Option<(f32, i32, Ordering)>| {
    assert_eq!(
        x.sci_mantissa_and_exponent_round(rm)
            .map(|(m, e, o)| (NiceFloat(m), e, o)),
        out.map(|(m, e, o)| (NiceFloat(m), e, o))
    );
};
test(Float::from(3u32), Floor, Some((1.5, 1, Equal)));
test(Float::from(3u32), Down, Some((1.5, 1, Equal)));
test(Float::from(3u32), Ceiling, Some((1.5, 1, Equal)));
test(Float::from(3u32), Up, Some((1.5, 1, Equal)));
test(Float::from(3u32), Nearest, Some((1.5, 1, Equal)));
test(Float::from(3u32), Exact, Some((1.5, 1, Equal)));

let x = Float::from(std::f64::consts::PI);
test(x.clone(), Floor, Some((1.5707963, 1, Less)));
test(x.clone(), Down, Some((1.5707963, 1, Less)));
test(x.clone(), Ceiling, Some((1.5707964, 1, Greater)));
test(x.clone(), Up, Some((1.5707964, 1, Greater)));
test(x.clone(), Nearest, Some((1.5707964, 1, Greater)));
test(x.clone(), Exact, None);

test(
    Float::from(1000000000u32),
    Nearest,
    Some((1.8626451, 29, Equal)),
);
test(
    Float::exact_from(Natural::from(10u32).pow(52)),
    Nearest,
    Some((1.670478, 172, Greater)),
);

test(Float::exact_from(Natural::from(10u32).pow(52)), Exact, None);

pub const MAX_EXPONENT: i32 = 0x3fff_ffff

pub const MIN_EXPONENT: i32

Trait Implementations

impl Clone for ComparableFloat

fn clone(&self) -> ComparableFloat

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ComparableFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for ComparableFloat

fn deref(&self) -> &Float

Allows a ComparableFloat to dereference to a Float.

use malachite_base::num::basic::traits::One;
use malachite_float::{ComparableFloat, Float};

let x = ComparableFloat(Float::ONE);
assert_eq!(*x, Float::ONE);

type Target = Float

The resulting type after dereferencing.

impl Display for ComparableFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for ComparableFloat

impl EqAbs for ComparableFloat

fn eq_abs(&self, other: &Self) -> bool

Compares the absolute values of two ComparableFloats for equality.

This implementation ignores the IEEE 754 standard in favor of an equality operation that respects the expected properties of symmetry, reflexivity, and transitivity. Using ComparableFloat, NaNs are equal to themselves. There is a single, unique NaN; there’s no concept of signalling NaNs. ComparableFloats with different precisions are unequal.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Examples

use malachite_base::num::basic::traits::{NaN, NegativeZero, One, Two, Zero};
use malachite_float::{ComparableFloat, Float};

assert_eq!(ComparableFloat(Float::NAN), ComparableFloat(Float::NAN));
assert_eq!(ComparableFloat(Float::ZERO), ComparableFloat(Float::ZERO));
assert_eq!(
    ComparableFloat(Float::NEGATIVE_ZERO),
    ComparableFloat(Float::NEGATIVE_ZERO)
);
assert_ne!(
    ComparableFloat(Float::ZERO),
    ComparableFloat(Float::NEGATIVE_ZERO)
);

assert_eq!(ComparableFloat(Float::ONE), ComparableFloat(Float::ONE));
assert_ne!(ComparableFloat(Float::ONE), ComparableFloat(Float::TWO));
assert_ne!(
    ComparableFloat(Float::ONE),
    ComparableFloat(Float::one_prec(100))
);

fn ne_abs(&self, other: &Rhs) -> bool

Compares the absolute values of two numbers for inequality, taking both by reference.

impl Hash for ComparableFloat

fn hash<H: Hasher>(&self, state: &mut H)

Computes a hash of a ComparableFloat.

The hash is compatible with ComparableFloat equality: all NaNs hash to the same value.

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().

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for ComparableFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Ord for ComparableFloat

fn cmp(&self, other: &Self) -> Ordering

Compares two ComparableFloats.

This implementation does not follow the IEEE 754 standard. This is how ComparableFloats are ordered, least to greatest:

• $-\infty$
• Negative nonzero finite floats
• Negative zero
• NaN
• Positive zero
• Positive nonzero finite floats
• $\infty$

When comparing two finite floats with the same numeric value but different precisions, the one with greater precision is ordered to be further from zero.

For different comparison behavior that follows the IEEE 754 standard, consider just using Float.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, OneHalf, Zero,
};
use malachite_float::{ComparableFloat, Float};
use std::cmp::Ordering::*;

assert_eq!(
    ComparableFloat(Float::NAN).partial_cmp(&ComparableFloat(Float::NAN)),
    Some(Equal)
);
assert!(ComparableFloat(Float::ZERO) > ComparableFloat(Float::NEGATIVE_ZERO));
assert!(ComparableFloat(Float::ONE) < ComparableFloat(Float::one_prec(100)));
assert!(ComparableFloat(Float::INFINITY) > ComparableFloat(Float::ONE));
assert!(ComparableFloat(Float::NEGATIVE_INFINITY) < ComparableFloat(Float::ONE));
assert!(ComparableFloat(Float::ONE_HALF) < ComparableFloat(Float::ONE));
assert!(ComparableFloat(Float::ONE_HALF) > ComparableFloat(Float::NEGATIVE_ONE));

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl OrdAbs for ComparableFloat

fn cmp_abs(&self, other: &Self) -> Ordering

Compares the absolute values of two ComparableFloats.

This implementation does not follow the IEEE 754 standard. This is how ComparableFloats are ordered by absolute value, from least to greatest:

• NaN
• Positive and negative zero
• Nonzero finite floats
• $\infty$ and $-\infty$

For different comparison behavior that follows the IEEE 754 standard, consider just using Float.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Examples

use malachite_base::num::basic::traits::{
    Infinity, NaN, NegativeInfinity, NegativeOne, NegativeZero, One, OneHalf, Zero,
};
use malachite_base::num::comparison::traits::PartialOrdAbs;
use malachite_float::{ComparableFloat, Float};
use std::cmp::Ordering::*;

assert_eq!(
    ComparableFloat(Float::NAN).partial_cmp_abs(&ComparableFloat(Float::NAN)),
    Some(Equal)
);
assert_eq!(
    ComparableFloat(Float::ZERO).partial_cmp_abs(&ComparableFloat(Float::NEGATIVE_ZERO)),
    Some(Equal)
);
assert!(ComparableFloat(Float::ONE).lt_abs(&ComparableFloat(Float::one_prec(100))));
assert!(ComparableFloat(Float::INFINITY).gt_abs(&ComparableFloat(Float::ONE)));
assert!(ComparableFloat(Float::NEGATIVE_INFINITY).gt_abs(&ComparableFloat(Float::ONE)));
assert!(ComparableFloat(Float::ONE_HALF).lt_abs(&ComparableFloat(Float::ONE)));
assert!(ComparableFloat(Float::ONE_HALF).lt_abs(&ComparableFloat(Float::NEGATIVE_ONE)));

impl PartialEq for ComparableFloat

fn eq(&self, other: &Self) -> bool

Compares two ComparableFloats for equality.

This implementation ignores the IEEE 754 standard in favor of an equality operation that respects the expected properties of symmetry, reflexivity, and transitivity. Using ComparableFloat, NaNs are equal to themselves. There is a single, unique NaN; there’s no concept of signalling NaNs. Positive and negative zero are two distinct values, not equal to each other. ComparableFloats with different precisions are unequal.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is max(self.significant_bits(), other.significant_bits()).

Examples

use malachite_base::num::basic::traits::{NaN, NegativeZero, One, Two, Zero};
use malachite_float::{ComparableFloat, Float};

assert_eq!(ComparableFloat(Float::NAN), ComparableFloat(Float::NAN));
assert_eq!(ComparableFloat(Float::ZERO), ComparableFloat(Float::ZERO));
assert_eq!(
    ComparableFloat(Float::NEGATIVE_ZERO),
    ComparableFloat(Float::NEGATIVE_ZERO)
);
assert_ne!(
    ComparableFloat(Float::ZERO),
    ComparableFloat(Float::NEGATIVE_ZERO)
);

assert_eq!(ComparableFloat(Float::ONE), ComparableFloat(Float::ONE));
assert_ne!(ComparableFloat(Float::ONE), ComparableFloat(Float::TWO));
assert_ne!(
    ComparableFloat(Float::ONE),
    ComparableFloat(Float::one_prec(100))
);

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for ComparableFloat

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Compares two ComparableFloats.

See the documentation for the Ord implementation.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrdAbs for ComparableFloat

fn partial_cmp_abs(&self, other: &Self) -> Option<Ordering>

Compares the absolute values of two ComparableFloatRefs.

See the documentation for the Ord implementation.

fn lt_abs(&self, other: &Rhs) -> bool

Determines whether the absolute value of one number is less than the absolute value of another.

fn le_abs(&self, other: &Rhs) -> bool

Determines whether the absolute value of one number is less than or equal to the absolute value of another.

fn gt_abs(&self, other: &Rhs) -> bool

Determines whether the absolute value of one number is greater than the absolute value of another.

fn ge_abs(&self, other: &Rhs) -> bool

Determines whether the absolute value of one number is greater than or equal to the absolute value of another.