# Struct malachite_nz::natural::Natural

pub struct Natural(_);
Expand description

A natural (non-negative) integer.

Any Natural small enough to fit into a Limb is represented inline. Only Naturals outside this range incur the costs of heap-allocation. Here’s a diagram of a slice of Naturals (using 32-bit limbs) containing the first 8 values of Sylvester’s sequence:

## Implementations

Calculates the approximate natural logarithm of a nonzero Natural.

$f(x) = (1+\epsilon)(\log x)$, where $|\epsilon| < 2^{-52}.$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::float::NiceFloat;
use malachite_nz::natural::Natural;

assert_eq!(NiceFloat(Natural::from(10u32).approx_log()), NiceFloat(2.3025850929940455));
assert_eq!(
NiceFloat(Natural::from(10u32).pow(10000).approx_log()),
NiceFloat(23025.850929940454)
);

This is equivalent to fmpz_dlog from fmpz/dlog.c, FLINT 2.7.1.

Returns a result of a comparison between two Naturals as if each had been multiplied by some power of 2 to bring it into the interval $[1, 2)$.

That is, the comparison is equivalent to a comparison between $f(x)$ and $f(y)$, where $$f(n) = n2^{\lfloor\log_2 n \rfloor}.$$

The multiplication is not actually performed.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Panics

Panics if either argument is zero.

##### Examples
use malachite_nz::natural::Natural;
use std::cmp::Ordering;

// 1 == 1.0 * 2^0, 4 == 1.0 * 2^2
// 1.0 == 1.0
assert_eq!(Natural::from(1u32).cmp_normalized(&Natural::from(4u32)), Ordering::Equal);

// 5 == 1.25 * 2^2, 6 == 1.5 * 2^2
// 1.25 < 1.5
assert_eq!(Natural::from(5u32).cmp_normalized(&Natural::from(6u32)), Ordering::Less);

// 3 == 1.5 * 2^1, 17 == 1.0625 * 2^4
// 1.5 > 1.0625
assert_eq!(Natural::from(3u32).cmp_normalized(&Natural::from(17u32)), Ordering::Greater);

// 9 == 1.125 * 2^3, 36 == 1.125 * 2^5
// 1.125 == 1.125
assert_eq!(Natural::from(9u32).cmp_normalized(&Natural::from(36u32)), Ordering::Equal);

Converts a slice of limbs to a Natural.

The limbs are in ascending order, so that less-significant limbs have lower indices in the input slice.

This function borrows the limbs. If taking ownership of limbs is possible, from_owned_limbs_asc is more efficient.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.len().

This function is more efficient than from_limbs_desc.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert_eq!(Natural::from_limbs_asc(&[]), 0);
assert_eq!(Natural::from_limbs_asc(&[123]), 123);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from_limbs_asc(&[3567587328, 232]), 1000000000000u64);
}

Converts a slice of limbs to a Natural.

The limbs in descending order, so that less-significant limbs have higher indices in the input slice.

This function borrows the limbs. If taking ownership of the limbs is possible, from_owned_limbs_desc is more efficient.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.len().

This function is less efficient than from_limbs_asc.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert_eq!(Natural::from_limbs_desc(&[]), 0);
assert_eq!(Natural::from_limbs_desc(&[123]), 123);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from_limbs_desc(&[232, 3567587328]), 1000000000000u64);
}

Converts a Vec of limbs to a Natural.

The limbs are in ascending order, so that less-significant limbs have lower indices in the input Vec.

This function takes ownership of the limbs. If it’s necessary to borrow the limbs instead, use from_limbs_asc.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.len().

This function is more efficient than from_limbs_desc.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert_eq!(Natural::from_owned_limbs_asc(vec![]), 0);
assert_eq!(Natural::from_owned_limbs_asc(vec![123]), 123);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from_owned_limbs_asc(vec![3567587328, 232]), 1000000000000u64);
}

Converts a Vec of limbs to a Natural.

The limbs are in descending order, so that less-significant limbs have higher indices in the input Vec.

This function takes ownership of the limbs. If it’s necessary to borrow the limbs instead, use from_limbs_desc.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.len().

This function is less efficient than from_limbs_asc.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert_eq!(Natural::from_owned_limbs_desc(vec![]), 0);
assert_eq!(Natural::from_owned_limbs_desc(vec![123]), 123);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from_owned_limbs_desc(vec![232, 3567587328]), 1000000000000u64);
}

Returns the number of limbs of a Natural.

Zero has 0 limbs.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert_eq!(Natural::ZERO.limb_count(), 0);
assert_eq!(Natural::from(123u32).limb_count(), 1);
assert_eq!(Natural::from(10u32).pow(12).limb_count(), 2);
}

Returns a Natural’s scientific mantissa and exponent.

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 ).$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::conversion::traits::SciMantissaAndExponent;
use malachite_base::num::float::NiceFloat;
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

let test = |n: Natural, rm: RoundingMode, out: Option<(f32, u64)>| {
assert_eq!(
n.sci_mantissa_and_exponent_with_rounding(rm)
.map(|(m, e)| (NiceFloat(m), e)),
out.map(|(m, e)| (NiceFloat(m), e))
);
};
test(Natural::from(3u32), RoundingMode::Down, Some((1.5, 1)));
test(Natural::from(3u32), RoundingMode::Ceiling, Some((1.5, 1)));
test(Natural::from(3u32), RoundingMode::Up, Some((1.5, 1)));
test(Natural::from(3u32), RoundingMode::Nearest, Some((1.5, 1)));
test(Natural::from(3u32), RoundingMode::Exact, Some((1.5, 1)));

test(
Natural::from(123u32),
RoundingMode::Floor,
Some((1.921875, 6)),
);
test(
Natural::from(123u32),
RoundingMode::Down,
Some((1.921875, 6)),
);
test(
Natural::from(123u32),
RoundingMode::Ceiling,
Some((1.921875, 6)),
);
test(Natural::from(123u32), RoundingMode::Up, Some((1.921875, 6)));
test(
Natural::from(123u32),
RoundingMode::Nearest,
Some((1.921875, 6)),
);
test(
Natural::from(123u32),
RoundingMode::Exact,
Some((1.921875, 6)),
);

test(
Natural::from(1000000000u32),
RoundingMode::Nearest,
Some((1.8626451, 29)),
);
test(
Natural::from(10u32).pow(52),
RoundingMode::Nearest,
Some((1.670478, 172)),
);

test(Natural::from(10u32).pow(52), RoundingMode::Exact, None);

Constructs a Natural from its scientific mantissa and exponent.

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$. Here, the rational mantissa is provided as a float. If the mantissa is outside the range $[1, 2)$, None is returned.

Some combinations of mantissas and exponents do not specify a Natural, in which case the resulting value is rounded to a Natural using the specified rounding mode. If the rounding mode is Exact but the input does not exactly specify a Natural, None is returned.

$$f(x, r) \approx 2^{e_s}m_s.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Panics

Panics if sci_mantissa is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::conversion::traits::SciMantissaAndExponent;
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;
use std::str::FromStr;

let test = |mantissa: f32, exponent: u64, rm: RoundingMode, out: Option<Natural>| {
assert_eq!(
Natural::from_sci_mantissa_and_exponent_with_rounding(mantissa, exponent, rm),
out
);
};
test(1.5, 1, RoundingMode::Floor, Some(Natural::from(3u32)));
test(1.5, 1, RoundingMode::Down, Some(Natural::from(3u32)));
test(1.5, 1, RoundingMode::Ceiling, Some(Natural::from(3u32)));
test(1.5, 1, RoundingMode::Up, Some(Natural::from(3u32)));
test(1.5, 1, RoundingMode::Nearest, Some(Natural::from(3u32)));
test(1.5, 1, RoundingMode::Exact, Some(Natural::from(3u32)));

test(1.51, 1, RoundingMode::Floor, Some(Natural::from(3u32)));
test(1.51, 1, RoundingMode::Down, Some(Natural::from(3u32)));
test(1.51, 1, RoundingMode::Ceiling, Some(Natural::from(4u32)));
test(1.51, 1, RoundingMode::Up, Some(Natural::from(4u32)));
test(1.51, 1, RoundingMode::Nearest, Some(Natural::from(3u32)));
test(1.51, 1, RoundingMode::Exact, None);

test(
1.670478,
172,
RoundingMode::Nearest,
Some(
Natural::from_str("10000000254586612611935772707803116801852191350456320").unwrap()
),
);

test(2.0, 1, RoundingMode::Floor, None);
test(10.0, 1, RoundingMode::Floor, None);
test(0.5, 1, RoundingMode::Floor, None);

Returns the limbs of a Natural, in ascending order, so that less-significant limbs have lower indices in the output vector.

There are no trailing zero limbs.

This function borrows the Natural. If taking ownership is possible instead, into_limbs_asc is more efficient.

This function is more efficient than to_limbs_desc.

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert!(Natural::ZERO.to_limbs_asc().is_empty());
assert_eq!(Natural::from(123u32).to_limbs_asc(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from(10u32).pow(12).to_limbs_asc(), &[3567587328, 232]);
}

Returns the limbs of a Natural in descending order, so that less-significant limbs have higher indices in the output vector.

There are no leading zero limbs.

This function borrows the Natural. If taking ownership is possible instead, into_limbs_desc is more efficient.

This function is less efficient than to_limbs_asc.

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert!(Natural::ZERO.to_limbs_desc().is_empty());
assert_eq!(Natural::from(123u32).to_limbs_desc(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from(10u32).pow(12).to_limbs_desc(), &[232, 3567587328]);
}

Returns the limbs of a Natural, in ascending order, so that less-significant limbs have lower indices in the output vector.

There are no trailing zero limbs.

This function takes ownership of the Natural. If it’s necessary to borrow instead, use to_limbs_asc.

This function is more efficient than into_limbs_desc.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert!(Natural::ZERO.into_limbs_asc().is_empty());
assert_eq!(Natural::from(123u32).into_limbs_asc(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from(10u32).pow(12).into_limbs_asc(), &[3567587328, 232]);
}

Returns the limbs of a Natural, in descending order, so that less-significant limbs have higher indices in the output vector.

There are no leading zero limbs.

This function takes ownership of the Natural. If it’s necessary to borrow instead, use to_limbs_desc.

This function is less efficient than into_limbs_asc.

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert!(Natural::ZERO.into_limbs_desc().is_empty());
assert_eq!(Natural::from(123u32).into_limbs_desc(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from(10u32).pow(12).into_limbs_desc(), &[232, 3567587328]);
}

Returns a double-ended iterator over the limbs of a Natural.

The forward order is ascending, so that less-significant limbs appear first. There are no trailing zero limbs going forward, or leading zeros going backward.

If it’s necessary to get a Vec of all the limbs, consider using to_limbs_asc, to_limbs_desc, into_limbs_asc, or into_limbs_desc instead.

##### Examples
extern crate itertools;
extern crate malachite_base;

use itertools::Itertools;
use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::integers::PrimitiveInt;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use malachite_nz::platform::Limb;

if Limb::WIDTH == u32::WIDTH {
assert!(Natural::ZERO.limbs().next().is_none());
assert_eq!(Natural::from(123u32).limbs().collect_vec(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(Natural::from(10u32).pow(12).limbs().collect_vec(), &[3567587328, 232]);

assert!(Natural::ZERO.limbs().rev().next().is_none());
assert_eq!(Natural::from(123u32).limbs().rev().collect_vec(), &[123]);
// 10^12 = 232 * 2^32 + 3567587328
assert_eq!(
Natural::from(10u32).pow(12).limbs().rev().collect_vec(),
&[232, 3567587328]
);
}

Returns the number of trailing zeros in the binary expansion of a Natural (equivalently, the multiplicity of 2 in its prime factorization), or None is the Natural is 0.

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.trailing_zeros(), None);
assert_eq!(Natural::from(3u32).trailing_zeros(), Some(0));
assert_eq!(Natural::from(72u32).trailing_zeros(), Some(3));
assert_eq!(Natural::from(100u32).trailing_zeros(), Some(2));
assert_eq!(Natural::from(10u32).pow(12).trailing_zeros(), Some(12));

## Trait Implementations

Adds two Naturals, taking both by reference.

$$f(x, y) = x + y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::ZERO + &Natural::from(123u32), 123);
assert_eq!(&Natural::from(123u32) + &Natural::ZERO, 123);
assert_eq!(&Natural::from(123u32) + &Natural::from(456u32), 579);
assert_eq!(
&Natural::from(10u32).pow(12) + &(Natural::from(10u32).pow(12) << 1),
3000000000000u64
);
The resulting type after applying the + operator.

Adds two Naturals, taking the first by reference and the second by value.

$$f(x, y) = x + y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO + &Natural::from(123u32), 123);
assert_eq!(Natural::from(123u32) + &Natural::ZERO, 123);
assert_eq!(Natural::from(123u32) + &Natural::from(456u32), 579);
assert_eq!(
Natural::from(10u32).pow(12) + &(Natural::from(10u32).pow(12) << 1),
3000000000000u64
);
The resulting type after applying the + operator.

Adds two Naturals, taking the first by value and the second by reference.

$$f(x, y) = x + y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::ZERO + Natural::from(123u32), 123);
assert_eq!(&Natural::from(123u32) + Natural::ZERO, 123);
assert_eq!(&Natural::from(123u32) + Natural::from(456u32), 579);
assert_eq!(
&Natural::from(10u32).pow(12) + (Natural::from(10u32).pow(12) << 1),
3000000000000u64
);
The resulting type after applying the + operator.

Adds two Naturals, taking both by value.

$$f(x, y) = x + y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$ (only if the underlying Vec needs to reallocate)

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO + Natural::from(123u32), 123);
assert_eq!(Natural::from(123u32) + Natural::ZERO, 123);
assert_eq!(Natural::from(123u32) + Natural::from(456u32), 579);
assert_eq!(
Natural::from(10u32).pow(12) + (Natural::from(10u32).pow(12) << 1),
3000000000000u64
);
The resulting type after applying the + operator.

Adds a Natural to a Natural in place, taking the Natural on the right-hand side by reference.

$$x \gets x + y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x += &Natural::from(10u32).pow(12);
x += &(Natural::from(10u32).pow(12) * Natural::from(2u32));
x += &(Natural::from(10u32).pow(12) * Natural::from(3u32));
x += &(Natural::from(10u32).pow(12) * Natural::from(4u32));
assert_eq!(x, 10000000000000u64);

Adds a Natural to a Natural in place, taking the Natural on the right-hand side by value.

$$x \gets x + y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$ (only if the underlying Vec needs to reallocate)

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x += Natural::from(10u32).pow(12);
x += Natural::from(10u32).pow(12) * Natural::from(2u32);
x += Natural::from(10u32).pow(12) * Natural::from(3u32);
x += Natural::from(10u32).pow(12) * Natural::from(4u32);
assert_eq!(x, 10000000000000u64);

Adds a Natural and the product of two other Naturals, taking all three by reference.

$f(x, y, z) = x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

$M(n, m) = O(m + n \log n)$

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

assert_eq!(
(&Natural::from(10u32).pow(12))
65537000000000000u64
);

Adds a Natural and the product of two other Naturals, taking the first by value and the second and third by reference.

$f(x, y, z) = x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(10u32).pow(12)
65537000000000000u64
);

Adds a Natural and the product of two other Naturals, taking the first and third by value and the second by reference.

$f(x, y, z) = x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(10u32).pow(12)
65537000000000000u64
);

Adds a Natural and the product of two other Naturals, taking the first two by value and the third by reference.

$f(x, y, z) = x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(10u32).pow(12)
65537000000000000u64
);

Adds a Natural and the product of two other Naturals, taking all three by value.

$f(x, y, z) = x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(10u32).pow(12)
65537000000000000u64
);

Adds the product of two other Naturals to a Natural in place, taking both Naturals on the right-hand side by reference.

$x \gets x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

let mut x = Natural::from(10u32);
assert_eq!(x, 22);

let mut x = Natural::from(10u32).pow(12);
assert_eq!(x, 65537000000000000u64);

Adds the product of two other Naturals to a Natural in place, taking the first Natural on the right-hand side by reference and the second by value.

$x \gets x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

let mut x = Natural::from(10u32);
assert_eq!(x, 22);

let mut x = Natural::from(10u32).pow(12);
assert_eq!(x, 65537000000000000u64);

Adds the product of two other Naturals to a Natural in place, taking the first Natural on the right-hand side by value and the second by reference.

$x \gets x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

let mut x = Natural::from(10u32);
assert_eq!(x, 22);

let mut x = Natural::from(10u32).pow(12);
assert_eq!(x, 65537000000000000u64);

Adds the product of two other Naturals to a Natural in place, taking both Naturals on the right-hand side by value.

$x \gets x + yz$.

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;

let mut x = Natural::from(10u32);
assert_eq!(x, 22);

let mut x = Natural::from(10u32).pow(12);
assert_eq!(x, 65537000000000000u64);

Converts a Natural to a binary String.

Using the # format flag prepends "0b" to the string.

##### 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
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToBinaryString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::ZERO.to_binary_string(), "0");
assert_eq!(Natural::from(123u32).to_binary_string(), "1111011");
assert_eq!(
Natural::from_str("1000000000000").unwrap().to_binary_string(),
"1110100011010100101001010001000000000000"
);
assert_eq!(format!("{:011b}", Natural::from(123u32)), "00001111011");

assert_eq!(format!("{:#b}", Natural::ZERO), "0b0");
assert_eq!(format!("{:#b}", Natural::from(123u32)), "0b1111011");
assert_eq!(
format!("{:#b}", Natural::from_str("1000000000000").unwrap()),
"0b1110100011010100101001010001000000000000"
);
assert_eq!(format!("{:#011b}", Natural::from(123u32)), "0b001111011");

Provides functions for accessing and modifying the $i$th bit of a Natural, or the coefficient of $2^i$ in its binary expansion.

#### Examples

extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_base::num::logic::traits::BitAccess;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x.assign_bit(2, true);
x.assign_bit(5, true);
x.assign_bit(6, true);
assert_eq!(x, 100);
x.assign_bit(2, false);
x.assign_bit(5, false);
x.assign_bit(6, false);
assert_eq!(x, 0);

let mut x = Natural::ZERO;
x.flip_bit(10);
assert_eq!(x, 1024);
x.flip_bit(10);
assert_eq!(x, 0);

Determines whether the $i$th bit of a Natural, or the coefficient of $2^i$ in its binary expansion, is 0 or 1.

false means 0 and true means 1. Getting bits beyond the Natural’s width is allowed; those bits are false.

Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Then $f(n, j) = (b_j = 1)$.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::logic::traits::BitAccess;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32).get_bit(2), false);
assert_eq!(Natural::from(123u32).get_bit(3), true);
assert_eq!(Natural::from(123u32).get_bit(100), false);
assert_eq!(Natural::from(10u32).pow(12).get_bit(12), true);
assert_eq!(Natural::from(10u32).pow(12).get_bit(100), false);

Sets the $i$th bit of a Natural, or the coefficient of $2^i$ in its binary expansion, to 1.

Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Then $$n \gets \begin{cases} n + 2^j & \text{if} \quad b_j = 0, \\ n & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitAccess;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x.set_bit(2);
x.set_bit(5);
x.set_bit(6);
assert_eq!(x, 100);

Sets the $i$th bit of a Natural, or the coefficient of $2^i$ in its binary expansion, to 0.

Clearing bits beyond the Natural’s width is allowed; since those bits are already false, clearing them does nothing.

Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Then $$n \gets \begin{cases} n - 2^j & \text{if} \quad b_j = 1, \\ n & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitAccess;
use malachite_nz::natural::Natural;

let mut x = Natural::from(0x7fu32);
x.clear_bit(0);
x.clear_bit(1);
x.clear_bit(3);
x.clear_bit(4);
assert_eq!(x, 100);
Sets the bit at index to whichever value bit is. Read more
Sets the bit at index to the opposite of its original value. Read more

Takes the bitwise and of two Naturals, taking both by reference.

$$f(x, y) = x \wedge y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) & &Natural::from(456u32), 72);
assert_eq!(
&Natural::from(10u32).pow(12) & &(Natural::from(10u32).pow(12) - Natural::ONE),
999999995904u64
);
The resulting type after applying the & operator.

Takes the bitwise and of two Naturals, taking the first by value and the second by reference.

$$f(x, y) = x \wedge y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) & &Natural::from(456u32), 72);
assert_eq!(
Natural::from(10u32).pow(12) & &(Natural::from(10u32).pow(12) - Natural::ONE),
999999995904u64
);
The resulting type after applying the & operator.

Takes the bitwise and of two Naturals, taking the first by reference and the seocnd by value.

$$f(x, y) = x \wedge y.$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) & Natural::from(456u32), 72);
assert_eq!(
&Natural::from(10u32).pow(12) & (Natural::from(10u32).pow(12) - Natural::ONE),
999999995904u64
);
The resulting type after applying the & operator.

Takes the bitwise and of two Naturals, taking both by value.

$$f(x, y) = x \wedge y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) & Natural::from(456u32), 72);
assert_eq!(
Natural::from(10u32).pow(12) & (Natural::from(10u32).pow(12) - Natural::ONE),
999999995904u64
);
The resulting type after applying the & operator.

Bitwise-ands a Natural with another Natural in place, taking the Natural on the right-hand side by reference.

$$x \gets x \wedge y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
use malachite_nz::natural::Natural;

let mut x = Natural::from(u32::MAX);
x &= &Natural::from(0xf0ffffffu32);
x &= &Natural::from(0xfff0_ffffu32);
x &= &Natural::from(0xfffff0ffu32);
x &= &Natural::from(0xfffffff0u32);
assert_eq!(x, 0xf0f0_f0f0u32);

Bitwise-ands a Natural with another Natural in place, taking the Natural on the right-hand side by value.

$$x \gets x \wedge y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
use malachite_nz::natural::Natural;

let mut x = Natural::from(u32::MAX);
x &= Natural::from(0xf0ffffffu32);
x &= Natural::from(0xfff0_ffffu32);
x &= Natural::from(0xfffff0ffu32);
x &= Natural::from(0xfffffff0u32);
assert_eq!(x, 0xf0f0_f0f0u32);

Extracts a block of adjacent bits from a Natural, taking the Natural by reference.

The first index is start and last index is end - 1.

Let $n$ be self, and let $p$ and $q$ be start and end, respectively.

Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Then $$f(n, p, q) = \sum_{i=p}^{q-1} 2^{b_{i-p}}.$$

##### 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 start > end.

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitBlockAccess;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits(16, 48), 0xef011234u32);
assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits(4, 16), 0x567u32);
assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits(0, 100), 0xabcdef0112345678u64);
assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits(10, 10), 0);

Extracts a block of adjacent bits from a Natural, taking the Natural by value.

The first index is start and last index is end - 1.

Let $n$ be self, and let $p$ and $q$ be start and end, respectively.

Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Then $$f(n, p, q) = \sum_{i=p}^{q-1} 2^{b_{i-p}}.$$

##### 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().

##### Panics

Panics if start > end.

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitBlockAccess;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits_owned(16, 48), 0xef011234u32);
assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits_owned(4, 16), 0x567u32);
assert_eq!(
Natural::from(0xabcdef0112345678u64).get_bits_owned(0, 100),
0xabcdef0112345678u64
);
assert_eq!(Natural::from(0xabcdef0112345678u64).get_bits_owned(10, 10), 0);

Replaces a block of adjacent bits in a Natural with other bits.

The least-significant end - start bits of bits are assigned to bits start through end - 1, inclusive, of self.

Let $n$ be self and let $m$ be bits, and let $p$ and $q$ be start and end, respectively.

If bits has fewer bits than end - start, the high bits are interpreted as 0. Let $$n = \sum_{i=0}^\infty 2^{b_i},$$ where for all $i$, $b_i\in \{0, 1\}$; so finitely many of the bits are 1, and the rest are 0. Let $$m = \sum_{i=0}^k 2^{d_i},$$ where for all $i$, $d_i\in \{0, 1\}$. Also, let $p, q \in \mathbb{N}$, and let $W$ be max(self.significant_bits(), end + 1).

Then $$n \gets \sum_{i=0}^{W-1} 2^{c_i},$$ where $$\{c_0, c_1, c_2, \ldots, c_ {W-1}\} = \{b_0, b_1, b_2, \ldots, b_{p-1}, d_0, d_1, \ldots, d_{p-q-1}, b_q, \ldots, b_ {W-1}\}.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Panics

Panics if start > end.

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitBlockAccess;
use malachite_nz::natural::Natural;

let mut n = Natural::from(123u32);
n.assign_bits(5, 7, &Natural::from(456u32));
assert_eq!(n, 27);

let mut n = Natural::from(123u32);
n.assign_bits(64, 128, &Natural::from(456u32));
assert_eq!(n.to_string(), "8411715297611555537019");

let mut n = Natural::from(123u32);
n.assign_bits(80, 100, &Natural::from(456u32));
assert_eq!(n.to_string(), "551270173744270903666016379");

Returns a Vec containing the bits of a Natural in ascending order: least- to most-significant.

If the number is 0, the Vec is empty; otherwise, it ends with true.

##### 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
extern crate malachite_base;

use malachite_base::num::logic::traits::BitConvertible;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert!(Natural::ZERO.to_bits_asc().is_empty());
// 105 = 1101001b
assert_eq!(
Natural::from(105u32).to_bits_asc(),
&[true, false, false, true, false, true, true]
);

Returns a Vec containing the bits of a Natural in descending order: most- to least-significant.

If the number is 0, the Vec is empty; otherwise, it begins with true.

##### 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
extern crate malachite_base;

use malachite_base::num::logic::traits::BitConvertible;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert!(Natural::ZERO.to_bits_desc().is_empty());
// 105 = 1101001b
assert_eq!(
Natural::from(105u32).to_bits_desc(),
&[true, true, false, true, false, false, true]
);

Converts an iterator of bits into a Natural. The bits should be in ascending order (least- to most-significant).

$$f((b_i)_ {i=0}^{k-1}) = \sum_{i=0}^{k-1}2^i [b_i],$$ where braces denote the Iverson bracket, which converts a bit to 0 or 1.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.count().

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitConvertible;
use malachite_nz::natural::Natural;
use std::iter::empty;

assert_eq!(Natural::from_bits_asc(empty()), 0);
// 105 = 1101001b
assert_eq!(
Natural::from_bits_asc([true, false, false, true, false, true, true].iter().cloned()),
105
);

Converts an iterator of bits into a Natural. The bits should be in descending order (most- to least-significant).

$$f((b_i)_ {i=0}^{k-1}) = \sum_{i=0}^{k-1}2^{k-i-1} [b_i],$$ where braces denote the Iverson bracket, which converts a bit to 0 or 1.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

where $T$ is time, $M$ is additional memory, and $n$ is xs.count().

##### Examples
extern crate malachite_base;

use malachite_base::num::logic::traits::BitConvertible;
use malachite_nz::natural::Natural;
use std::iter::empty;

assert_eq!(Natural::from_bits_desc(empty()), 0);
// 105 = 1101001b
assert_eq!(
Natural::from_bits_desc([true, true, false, true, false, false, true].iter().cloned()),
105
);

Returns a double-ended iterator over the bits of a Natural.

The forward order is ascending, so that less significant bits appear first. There are no trailing false bits going forward, or leading falses going backward.

If it’s necessary to get a Vec of all the bits, consider using to_bits_asc or to_bits_desc instead.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_base::num::logic::traits::BitIterable;
use malachite_nz::natural::Natural;

assert!(Natural::ZERO.bits().next().is_none());
// 105 = 1101001b
assert_eq!(
Natural::from(105u32).bits().collect::<Vec<bool>>(),
&[true, false, false, true, false, true, true]
);

assert!(Natural::ZERO.bits().next_back().is_none());
// 105 = 1101001b
assert_eq!(
Natural::from(105u32).bits().rev().collect::<Vec<bool>>(),
&[true, true, false, true, false, false, true]
);

Takes the bitwise or of two Naturals, taking both by reference.

$$f(x, y) = x \vee y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) | &Natural::from(456u32), 507);
assert_eq!(
&Natural::from(10u32).pow(12) | &(Natural::from(10u32).pow(12) - Natural::ONE),
1000000004095u64
);
The resulting type after applying the | operator.

Takes the bitwise or of two Naturals, taking the first by value and the second by reference.

$$f(x, y) = x \vee y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) | &Natural::from(456u32), 507);
assert_eq!(
Natural::from(10u32).pow(12) | &(Natural::from(10u32).pow(12) - Natural::ONE),
1000000004095u64
);
The resulting type after applying the | operator.

Takes the bitwise or of two Naturals, taking the first by reference and the second by value.

$$f(x, y) = x \vee y.$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) | Natural::from(456u32), 507);
assert_eq!(
&Natural::from(10u32).pow(12) | (Natural::from(10u32).pow(12) - Natural::ONE),
1000000004095u64
);
The resulting type after applying the | operator.

Takes the bitwise or of two Naturals, taking both by value.

$$f(x, y) = x \vee y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) | Natural::from(456u32), 507);
assert_eq!(
Natural::from(10u32).pow(12) | (Natural::from(10u32).pow(12) - Natural::ONE),
1000000004095u64
);
The resulting type after applying the | operator.

Bitwise-ors a Natural with another Natural in place, taking the Natural on the right-hand side by reference.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x |= &Natural::from(0x0000000fu32);
x |= &Natural::from(0x00000f00u32);
x |= &Natural::from(0x000f_0000u32);
x |= &Natural::from(0x0f000000u32);
assert_eq!(x, 0x0f0f_0f0f);

Bitwise-ors a Natural with another Natural in place, taking the Natural on the right-hand side by value.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x |= Natural::from(0x0000000fu32);
x |= Natural::from(0x00000f00u32);
x |= Natural::from(0x000f_0000u32);
x |= Natural::from(0x0f000000u32);
assert_eq!(x, 0x0f0f_0f0f);

Given a Natural and a starting index, searches the Natural for the smallest index of a false bit that is greater than or equal to the starting index.

Since every Natural has an implicit prefix of infinitely-many zeros, this function always returns a value.

Starting beyond the Natural’s width is allowed; the result is the starting index.

##### 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
extern crate malachite_base;

use malachite_base::num::logic::traits::BitScan;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(0), Some(0));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(20), Some(20));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(31), Some(31));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(32), Some(34));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(33), Some(34));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(34), Some(34));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(35), Some(36));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_false_bit(100), Some(100));

Given a Natural and a starting index, searches the Natural for the smallest index of a true bit that is greater than or equal to the starting index.

If the starting index is greater than or equal to the Natural’s width, the result is None since there are no true bits past that point.

##### 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
extern crate malachite_base;

use malachite_base::num::logic::traits::BitScan;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(0), Some(32));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(20), Some(32));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(31), Some(32));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(32), Some(32));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(33), Some(33));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(34), Some(35));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(35), Some(35));
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(36), None);
assert_eq!(Natural::from(0xb00000000u64).index_of_next_true_bit(100), None);

Takes the bitwise xor of two Naturals, taking both by reference.

$$f(x, y) = x \oplus y.$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) ^ &Natural::from(456u32), 435);
assert_eq!(
&Natural::from(10u32).pow(12) ^ &(Natural::from(10u32).pow(12) - Natural::ONE),
8191
);
The resulting type after applying the ^ operator.

Takes the bitwise xor of two Naturals, taking the first by value and the second by reference.

$$f(x, y) = x \oplus y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) ^ &Natural::from(456u32), 435);
assert_eq!(
Natural::from(10u32).pow(12) ^ &(Natural::from(10u32).pow(12) - Natural::ONE),
8191
);
The resulting type after applying the ^ operator.

Takes the bitwise xor of two Naturals, taking the first by reference and the second by value.

$$f(x, y) = x \oplus y.$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(&Natural::from(123u32) ^ Natural::from(456u32), 435);
assert_eq!(
&Natural::from(10u32).pow(12) ^ (Natural::from(10u32).pow(12) - Natural::ONE),
8191
);
The resulting type after applying the ^ operator.

Takes the bitwise xor of two Naturals, taking both by value.

$$f(x, y) = x \oplus y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::One;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(123u32) ^ Natural::from(456u32), 435);
assert_eq!(
Natural::from(10u32).pow(12) ^ (Natural::from(10u32).pow(12) - Natural::ONE),
8191
);
The resulting type after applying the ^ operator.

Bitwise-xors a Natural with another Natural in place, taking the Natural on the right-hand side by reference.

$$x \gets x \oplus y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x |= Natural::from(0x0000000fu32);
x |= Natural::from(0x00000f00u32);
x |= Natural::from(0x000f_0000u32);
x |= Natural::from(0x0f000000u32);
assert_eq!(x, 0x0f0f_0f0f);

Bitwise-xors a Natural with another Natural in place, taking the Natural on the right-hand side by value.

$$x \gets x \oplus y.$$

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

let mut x = Natural::ZERO;
x ^= Natural::from(0x0000000fu32);
x ^= Natural::from(0x00000f00u32);
x ^= Natural::from(0x000f_0000u32);
x ^= Natural::from(0x0f000000u32);
assert_eq!(x, 0x0f0f_0f0f);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by reference and returning the remainder of the negative of the first number divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = y\left \lceil \frac{x}{y} \right \rceil - x,$$ $$x \gets \left \lceil \frac{x}{y} \right \rceil.$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivAssignNegMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.ceiling_div_assign_neg_mod(&Natural::from(10u32)), 7);
assert_eq!(x, 3);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(
x.ceiling_div_assign_neg_mod(&Natural::from_str("1234567890987").unwrap()),
704498996588u64,
);
assert_eq!(x, 810000006724u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value and returning the remainder of the negative of the first number divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = y\left \lceil \frac{x}{y} \right \rceil - x,$$ $$x \gets \left \lceil \frac{x}{y} \right \rceil.$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivAssignNegMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.ceiling_div_assign_neg_mod(Natural::from(10u32)), 7);
assert_eq!(x, 3);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(
x.ceiling_div_assign_neg_mod(Natural::from_str("1234567890987").unwrap()),
704498996588u64,
);
assert_eq!(x, 810000006724u64);

Divides a Natural by another Natural, taking the first by value and the second by reference and returning the ceiling of the quotient and the remainder of the negative of the first Natural divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lceil \frac{x}{y} \right \rceil, \space y\left \lceil \frac{x}{y} \right \rceil - x \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivNegMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
assert_eq!(
Natural::from(23u32).ceiling_div_neg_mod(&Natural::from(10u32)).to_debug_string(),
"(3, 7)"
);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.ceiling_div_neg_mod(&Natural::from_str("1234567890987").unwrap())
.to_debug_string(),
"(810000006724, 704498996588)"
);

Divides a Natural by another Natural, taking both by reference and returning the ceiling of the quotient and the remainder of the negative of the first Natural divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lceil \frac{x}{y} \right \rceil, \space y\left \lceil \frac{x}{y} \right \rceil - x \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivNegMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
assert_eq!(
(&Natural::from(23u32)).ceiling_div_neg_mod(&Natural::from(10u32)).to_debug_string(),
"(3, 7)"
);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.ceiling_div_neg_mod(&Natural::from_str("1234567890987").unwrap())
.to_debug_string(),
"(810000006724, 704498996588)"
);

Divides a Natural by another Natural, taking the first by reference and the second by value and returning the ceiling of the quotient and the remainder of the negative of the first Natural divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lceil \frac{x}{y} \right \rceil, \space y\left \lceil \frac{x}{y} \right \rceil - x \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivNegMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
assert_eq!(
(&Natural::from(23u32)).ceiling_div_neg_mod(Natural::from(10u32)).to_debug_string(),
"(3, 7)"
);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.ceiling_div_neg_mod(Natural::from_str("1234567890987").unwrap())
.to_debug_string(),
"(810000006724, 704498996588)"
);

Divides a Natural by another Natural, taking both by value and returning the ceiling of the quotient and the remainder of the negative of the first Natural divided by the second.

The quotient and remainder satisfy $x = qy - r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lceil \frac{x}{y} \right \rceil, \space y\left \lceil \frac{x}{y} \right \rceil - x \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingDivNegMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 3 * 10 - 7 = 23
assert_eq!(
Natural::from(23u32).ceiling_div_neg_mod(Natural::from(10u32)).to_debug_string(),
"(3, 7)"
);

// 810000006724 * 1234567890987 - 704498996588 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.ceiling_div_neg_mod(Natural::from_str("1234567890987").unwrap())
.to_debug_string(),
"(810000006724, 704498996588)"
);

Returns the ceiling of the base-$b$ logarithm of a positive Natural.

$f(x, b) = \lceil\log_b x\rceil$.

##### 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 x.significant_bits().

##### Panics

Panics if self is 0 or base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingLogBase;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(80u32).ceiling_log_base(&Natural::from(3u32)), 4);
assert_eq!(Natural::from(81u32).ceiling_log_base(&Natural::from(3u32)), 4);
assert_eq!(Natural::from(82u32).ceiling_log_base(&Natural::from(3u32)), 5);
assert_eq!(Natural::from(4294967296u64).ceiling_log_base(&Natural::from(10u32)), 10);

This is equivalent to fmpz_clog from fmpz/clog.c, FLINT 2.7.1.

Returns the ceiling of the base-2 logarithm of a positive Natural.

$f(x) = \lceil\log_2 x\rceil$.

##### 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().

##### Panics

Panics if self is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingLogBase2;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(3u32).ceiling_log_base_2(), 2);
assert_eq!(Natural::from(100u32).ceiling_log_base_2(), 7);

Returns the ceiling of the base-$2^k$ logarithm of a positive Natural.

$f(x, k) = \lceil\log_{2^k} x\rceil$.

##### 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().

##### Panics

Panics if self is 0 or pow is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingLogBasePowerOf2;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(100u32).ceiling_log_base_power_of_2(2), 4);
assert_eq!(Natural::from(4294967296u64).ceiling_log_base_power_of_2(8), 4);

Returns the ceiling of the $n$th root of a Natural, taking the Natural by reference.

$f(x, n) = \lceil\sqrt[n]{x}\rceil$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingRoot;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(999u16).ceiling_root(3), 10);
assert_eq!(Natural::from(1000u16).ceiling_root(3), 10);
assert_eq!(Natural::from(1001u16).ceiling_root(3), 11);
assert_eq!(Natural::from(100000000000u64).ceiling_root(5), 159);

Returns the ceiling of the $n$th root of a Natural, taking the Natural by value.

$f(x, n) = \lceil\sqrt[n]{x}\rceil$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingRoot;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(999u16).ceiling_root(3), 10);
assert_eq!(Natural::from(1000u16).ceiling_root(3), 10);
assert_eq!(Natural::from(1001u16).ceiling_root(3), 11);
assert_eq!(Natural::from(100000000000u64).ceiling_root(5), 159);

Replaces a Natural with the ceiling of its $n$th root.

$x \gets \lceil\sqrt[n]{x}\rceil$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingRootAssign;
use malachite_nz::natural::Natural;

let mut x = Natural::from(999u16);
x.ceiling_root_assign(3);
assert_eq!(x, 10);

let mut x = Natural::from(1000u16);
x.ceiling_root_assign(3);
assert_eq!(x, 10);

let mut x = Natural::from(1001u16);
x.ceiling_root_assign(3);
assert_eq!(x, 11);

let mut x = Natural::from(100000000000u64);
x.ceiling_root_assign(5);
assert_eq!(x, 159);

Returns the ceiling of the square root of a Natural, taking it by value.

$f(x) = \lceil\sqrt{x}\rceil$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingSqrt;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(99u8).ceiling_sqrt(), 10);
assert_eq!(Natural::from(100u8).ceiling_sqrt(), 10);
assert_eq!(Natural::from(101u8).ceiling_sqrt(), 11);
assert_eq!(Natural::from(1000000000u32).ceiling_sqrt(), 31623);
assert_eq!(Natural::from(10000000000u64).ceiling_sqrt(), 100000);

Returns the ceiling of the square root of a Natural, taking it by value.

$f(x) = \lceil\sqrt{x}\rceil$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingSqrt;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(99u8).ceiling_sqrt(), 10);
assert_eq!(Natural::from(100u8).ceiling_sqrt(), 10);
assert_eq!(Natural::from(101u8).ceiling_sqrt(), 11);
assert_eq!(Natural::from(1000000000u32).ceiling_sqrt(), 31623);
assert_eq!(Natural::from(10000000000u64).ceiling_sqrt(), 100000);

Replaces a Natural with the ceiling of its square root.

$x \gets \lceil\sqrt{x}\rceil$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CeilingSqrtAssign;
use malachite_nz::natural::Natural;

let mut x = Natural::from(99u8);
x.ceiling_sqrt_assign();
assert_eq!(x, 10);

let mut x = Natural::from(100u8);
x.ceiling_sqrt_assign();
assert_eq!(x, 10);

let mut x = Natural::from(101u8);
x.ceiling_sqrt_assign();
assert_eq!(x, 11);

let mut x = Natural::from(1000000000u32);
x.ceiling_sqrt_assign();
assert_eq!(x, 31623);

let mut x = Natural::from(10000000000u64);
x.ceiling_sqrt_assign();
assert_eq!(x, 100000);

Returns the base-$b$ logarithm of a positive Natural. If the Natural is not a power of $b$, then None is returned.

$$f(x, b) = \begin{cases} \operatorname{Some}(\log_b x) & \text{if} \quad \log_b x \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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 x.significant_bits().

##### Panics

Panics if self is 0 or base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedLogBase;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(80u32).checked_log_base(&Natural::from(3u32)), None);
assert_eq!(Natural::from(81u32).checked_log_base(&Natural::from(3u32)), Some(4));
assert_eq!(Natural::from(82u32).checked_log_base(&Natural::from(3u32)), None);
assert_eq!(Natural::from(4294967296u64).checked_log_base(&Natural::from(10u32)), None);

Returns the base-2 logarithm of a positive Natural. If the Natural is not a power of 2, then None is returned.

$$f(x) = \begin{cases} \operatorname{Some}(\log_2 x) & \text{if} \quad \log_2 x \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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().

##### Panics

Panics if self is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedLogBase2;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::from(3u32).checked_log_base_2(), None);
assert_eq!(Natural::from(4u32).checked_log_base_2(), Some(2));
assert_eq!(
Natural::from_str("1267650600228229401496703205376").unwrap().checked_log_base_2(),
Some(100)
);

Returns the base-$2^k$ logarithm of a positive Natural. If the Natural is not a power of $2^k$, then None is returned.

$$f(x, k) = \begin{cases} \operatorname{Some}(\log_{2^k} x) & \text{if} \quad \log_{2^k} x \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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().

##### Panics

Panics if self is 0 or pow is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedLogBasePowerOf2;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::from(100u32).checked_log_base_power_of_2(2), None);
assert_eq!(Natural::from(4294967296u64).checked_log_base_power_of_2(8), Some(4));

Returns the the $n$th root of a Natural, or None if the Natural is not a perfect $n$th power. The Natural is taken by reference.

$$f(x, n) = \begin{cases} \operatorname{Some}(sqrt[n]{x}) & \text{if} \quad \sqrt[n]{x} \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedRoot;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(999u16)).checked_root(3).to_debug_string(), "None");
assert_eq!((&Natural::from(1000u16)).checked_root(3).to_debug_string(), "Some(10)");
assert_eq!((&Natural::from(1001u16)).checked_root(3).to_debug_string(), "None");
assert_eq!((&Natural::from(100000000000u64)).checked_root(5).to_debug_string(), "None");
assert_eq!(
(&Natural::from(10000000000u64)).checked_root(5).to_debug_string(),
"Some(100)"
);

Returns the the $n$th root of a Natural, or None if the Natural is not a perfect $n$th power. The Natural is taken by value.

$$f(x, n) = \begin{cases} \operatorname{Some}(sqrt[n]{x}) & \text{if} \quad \sqrt[n]{x} \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedRoot;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(999u16).checked_root(3).to_debug_string(), "None");
assert_eq!(Natural::from(1000u16).checked_root(3).to_debug_string(), "Some(10)");
assert_eq!(Natural::from(1001u16).checked_root(3).to_debug_string(), "None");
assert_eq!(Natural::from(100000000000u64).checked_root(5).to_debug_string(), "None");
assert_eq!(Natural::from(10000000000u64).checked_root(5).to_debug_string(), "Some(100)");

Returns the the square root of a Natural, or None if it is not a perfect square. The Natural is taken by value.

$$f(x) = \begin{cases} \operatorname{Some}(sqrt{x}) & \text{if} \quad \sqrt{x} \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedSqrt;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(99u8)).checked_sqrt().to_debug_string(), "None");
assert_eq!((&Natural::from(100u8)).checked_sqrt().to_debug_string(), "Some(10)");
assert_eq!((&Natural::from(101u8)).checked_sqrt().to_debug_string(), "None");
assert_eq!((&Natural::from(1000000000u32)).checked_sqrt().to_debug_string(), "None");
assert_eq!(
(&Natural::from(10000000000u64)).checked_sqrt().to_debug_string(),
"Some(100000)"
);

Returns the the square root of a Natural, or None if it is not a perfect square. The Natural is taken by value.

$$f(x) = \begin{cases} \operatorname{Some}(sqrt{x}) & \text{if} \quad \sqrt{x} \in \Z, \\ \operatorname{None} & \textrm{otherwise}. \end{cases}$$

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CheckedSqrt;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(99u8).checked_sqrt().to_debug_string(), "None");
assert_eq!(Natural::from(100u8).checked_sqrt().to_debug_string(), "Some(10)");
assert_eq!(Natural::from(101u8).checked_sqrt().to_debug_string(), "None");
assert_eq!(Natural::from(1000000000u32).checked_sqrt().to_debug_string(), "None");
assert_eq!(Natural::from(10000000000u64).checked_sqrt().to_debug_string(), "Some(100000)");

Subtracts a Natural by another Natural, taking both by reference and returning None if the result is negative.

$$f(x, y) = \begin{cases} \operatorname{Some}(x - y) & \text{if} \quad x \geq y, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSub, Pow};
use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::ZERO).checked_sub(&Natural::from(123u32)).to_debug_string(), "None");
assert_eq!((&Natural::from(123u32)).checked_sub(&Natural::ZERO).to_debug_string(),
"Some(123)");
assert_eq!((&Natural::from(456u32)).checked_sub(&Natural::from(123u32)).to_debug_string(),
"Some(333)");
assert_eq!(
(&(Natural::from(10u32).pow(12) * Natural::from(3u32)))
.checked_sub(&Natural::from(10u32).pow(12)).to_debug_string(),
"Some(2000000000000)"
);

Subtracts a Natural by another Natural, taking the first by value and the second by reference and returning None if the result is negative.

$$f(x, y) = \begin{cases} \operatorname{Some}(x - y) & \text{if} \quad x \geq y, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSub, Pow};
use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.checked_sub(&Natural::from(123u32)).to_debug_string(), "None");
assert_eq!(
Natural::from(123u32).checked_sub(&Natural::ZERO).to_debug_string(),
"Some(123)"
);
assert_eq!(Natural::from(456u32).checked_sub(&Natural::from(123u32)).to_debug_string(),
"Some(333)");
assert_eq!(
(Natural::from(10u32).pow(12) * Natural::from(3u32))
.checked_sub(&Natural::from(10u32).pow(12)).to_debug_string(),
"Some(2000000000000)"
);

Subtracts a Natural by another Natural, taking the first by reference and the second by value and returning None if the result is negative.

$$f(x, y) = \begin{cases} \operatorname{Some}(x - y) & \text{if} \quad x \geq y, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSub, Pow};
use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::ZERO).checked_sub(Natural::from(123u32)).to_debug_string(), "None");
assert_eq!((&Natural::from(123u32)).checked_sub(Natural::ZERO).to_debug_string(),
"Some(123)");
assert_eq!((&Natural::from(456u32)).checked_sub(Natural::from(123u32)).to_debug_string(),
"Some(333)");
assert_eq!(
(&(Natural::from(10u32).pow(12) * Natural::from(3u32)))
.checked_sub(Natural::from(10u32).pow(12)).to_debug_string(),
"Some(2000000000000)"
);

Subtracts a Natural by another Natural, taking both by value and returning None if the result is negative.

$$f(x, y) = \begin{cases} \operatorname{Some}(x - y) & \text{if} \quad x \geq y, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSub, Pow};
use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.checked_sub(Natural::from(123u32)).to_debug_string(), "None");
assert_eq!(
Natural::from(123u32).checked_sub(Natural::ZERO).to_debug_string(),
"Some(123)"
);
assert_eq!(
Natural::from(456u32).checked_sub(Natural::from(123u32)).to_debug_string(),
"Some(333)"
);
assert_eq!(
(Natural::from(10u32).pow(12) * Natural::from(3u32))
.checked_sub(Natural::from(10u32).pow(12)).to_debug_string(),
"Some(2000000000000)"
);

Subtracts a Natural by the product of two other Naturals, taking all three by reference and returning None if the result is negative.

$$f(x, y, z) = \begin{cases} \operatorname{Some}(x - yz) & \text{if} \quad x \geq yz, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

$M(n, m) = O(m + n \log n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSubMul, Pow};
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
(&Natural::from(20u32)).checked_sub_mul(&Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"Some(8)"
);
assert_eq!(
(&Natural::from(10u32)).checked_sub_mul(&Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"None"
);
assert_eq!(
(&Natural::from(10u32).pow(12))
.checked_sub_mul(&Natural::from(0x10000u32), &Natural::from(0x10000u32))
.to_debug_string(),
"Some(995705032704)"
);

Subtracts a Natural by the product of two other Naturals, taking the first by value and the second and third by reference and returning None if the result is negative.

$$f(x, y, z) = \begin{cases} \operatorname{Some}(x - yz) & \text{if} \quad x \geq yz, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Panics

Panics if y * z is greater than self.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSubMul, Pow};
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(20u32).checked_sub_mul(&Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"Some(8)"
);
assert_eq!(
Natural::from(10u32).checked_sub_mul(&Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"None"
);
assert_eq!(
Natural::from(10u32).pow(12)
.checked_sub_mul(&Natural::from(0x10000u32), &Natural::from(0x10000u32))
.to_debug_string(),
"Some(995705032704)"
);

Subtracts a Natural by the product of two other Naturals, taking the first and third by value and the second by reference and returning None if the result is negative.

$$f(x, y, z) = \begin{cases} \operatorname{Some}(x - yz) & \text{if} \quad x \geq yz, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Panics

Panics if y * z is greater than self.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSubMul, Pow};
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(20u32).checked_sub_mul(&Natural::from(3u32), Natural::from(4u32))
.to_debug_string(),
"Some(8)"
);
assert_eq!(
Natural::from(10u32).checked_sub_mul(&Natural::from(3u32), Natural::from(4u32))
.to_debug_string(),
"None"
);
assert_eq!(
Natural::from(10u32).pow(12)
.checked_sub_mul(&Natural::from(0x10000u32), Natural::from(0x10000u32))
.to_debug_string(),
"Some(995705032704)"
);

Subtracts a Natural by the product of two other Naturals, taking the first two by value and the third by reference and returning None if the result is negative.

$$f(x, y, z) = \begin{cases} \operatorname{Some}(x - yz) & \text{if} \quad x \geq yz, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Panics

Panics if y * z is greater than self.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSubMul, Pow};
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(20u32).checked_sub_mul(Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"Some(8)"
);
assert_eq!(
Natural::from(10u32).checked_sub_mul(Natural::from(3u32), &Natural::from(4u32))
.to_debug_string(),
"None"
);
assert_eq!(
Natural::from(10u32).pow(12)
.checked_sub_mul(Natural::from(0x10000u32), &Natural::from(0x10000u32))
.to_debug_string(),
"Some(995705032704)"
);

Subtracts a Natural by the product of two other Naturals, taking all three by value and returning None if the result is negative.

$$f(x, y, z) = \begin{cases} \operatorname{Some}(x - yz) & \text{if} \quad x \geq yz, \\ \operatorname{None} & \text{otherwise}. \end{cases}$$

##### Worst-case complexity

$T(n, m) = O(m + n \log n \log\log n)$

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

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

##### Panics

Panics if y * z is greater than self.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{CheckedSubMul, Pow};
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(20u32).checked_sub_mul(Natural::from(3u32), Natural::from(4u32))
.to_debug_string(),
"Some(8)"
);
assert_eq!(
Natural::from(10u32).checked_sub_mul(Natural::from(3u32), Natural::from(4u32))
.to_debug_string(),
"None"
);
assert_eq!(
Natural::from(10u32).pow(12)
.checked_sub_mul(Natural::from(0x10000u32), Natural::from(0x10000u32))
.to_debug_string(),
"Some(995705032704)"
);
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more

Determines whether an Integer can be converted to a Natural (when the Integer is non-negative). Takes the Integer by reference.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::conversion::traits::ConvertibleFrom;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;

assert_eq!(Natural::convertible_from(&Integer::from(123)), true);
assert_eq!(Natural::convertible_from(&Integer::from(-123)), false);
assert_eq!(Natural::convertible_from(&Integer::from(10u32).pow(12)), true);
assert_eq!(Natural::convertible_from(&-Integer::from(10u32).pow(12)), false);

Determines whether a Natural can be exactly converted to a primitive float.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples

See here.

Determines whether a Natural can be exactly converted to a primitive float.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples

See here.

Determines whether a Natural can be converted to a value of a signed primitive integer type that’s larger than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a signed primitive integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a signed primitive integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a SignedLimb (the signed type whose width is the same as a limb’s).

##### Examples

See here.

Determines whether a Natural can be converted to a value of a signed primitive integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to an isize.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a primitive unsigned integer type that’s larger than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a primitive unsigned integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a primitive unsigned integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a value of a primitive unsigned integer type that’s smaller than a Limb.

##### Examples

See here.

Determines whether a Natural can be converted to a usize.

##### Examples

See here.

Determines whether an Integer can be converted to a Natural (when the Integer is non-negative). Takes the Integer by value.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::conversion::traits::ConvertibleFrom;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;

assert_eq!(Natural::convertible_from(Integer::from(123)), true);
assert_eq!(Natural::convertible_from(Integer::from(-123)), false);
assert_eq!(Natural::convertible_from(Integer::from(10u32).pow(12)), true);
assert_eq!(Natural::convertible_from(-Integer::from(10u32).pow(12)), false);

Determines whether a floating-point value can be exactly converted to a Natural.

##### Examples

See here.

Determines whether a floating-point value can be exactly converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Determines whether a signed primitive integer can be converted to a Natural.

##### Examples

See here.

Returns whether two Naturals are coprime; that is, whether they have no common factor other than 1. The first Natural is taken by value and the second by reference.

Every Natural is coprime with 1. No Natural is coprime with 0, except 1.

$f(x, y) = (\gcd(x, y) = 1)$.

$f(x, y) = ((k,m,n \in \N \land x=km \land y=kn) \implies k=1)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CoprimeWith;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(3u32).coprime_with(&Natural::from(5u32)), true);
assert_eq!(Natural::from(12u32).coprime_with(&Natural::from(90u32)), false);

Returns whether two Naturals are coprime; that is, whether they have no common factor other than 1. Both Naturals are taken by reference.

Every Natural is coprime with 1. No Natural is coprime with 0, except 1.

$f(x, y) = (\gcd(x, y) = 1)$.

$f(x, y) = ((k,m,n \in \N \land x=km \land y=kn) \implies k=1)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CoprimeWith;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(3u32)).coprime_with(Natural::from(5u32)), true);
assert_eq!((&Natural::from(12u32)).coprime_with(Natural::from(90u32)), false);

Returns whether two Naturals are coprime; that is, whether they have no common factor other than 1. The first Natural is taken by reference and the second by value.

Every Natural is coprime with 1. No Natural is coprime with 0, except 1.

$f(x, y) = (\gcd(x, y) = 1)$.

$f(x, y) = ((k,m,n \in \N \land x=km \land y=kn) \implies k=1)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CoprimeWith;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(3u32)).coprime_with(Natural::from(5u32)), true);
assert_eq!((&Natural::from(12u32)).coprime_with(Natural::from(90u32)), false);

Returns whether two Naturals are coprime; that is, whether they have no common factor other than 1. Both Naturals are taken by value.

Every Natural is coprime with 1. No Natural is coprime with 0, except 1.

$f(x, y) = (\gcd(x, y) = 1)$.

$f(x, y) = ((k,m,n \in \N \land x=km \land y=kn) \implies k=1)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::CoprimeWith;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(3u32).coprime_with(Natural::from(5u32)), true);
assert_eq!(Natural::from(12u32).coprime_with(Natural::from(90u32)), false);

Counts the number of ones in the binary expansion of a Natural.

##### 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
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_base::num::basic::traits::Zero;
use malachite_base::num::logic::traits::CountOnes;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.count_ones(), 0);
// 105 = 1101001b
assert_eq!(Natural::from(105u32).count_ones(), 4);
// 10^12 = 1110100011010100101001010001000000000000b
assert_eq!(Natural::from(10u32).pow(12).count_ones(), 13);

Converts a Natural to a String.

This is the same as the Display::fmt implementation.

##### 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 self.significant_bits().

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::ZERO.to_debug_string(), "0");
assert_eq!(Natural::from(123u32).to_debug_string(), "123");
assert_eq!(
Natural::from_str("1000000000000").unwrap().to_debug_string(),
"1000000000000"
);
assert_eq!(format!("{:05?}", Natural::from(123u32)), "00123");

The default value of a Natural, 0.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::{Two, Zero};
use malachite_base::num::conversion::traits::Digits;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.to_digits_asc(&Natural::from(6u32)).to_debug_string(), "[]");
assert_eq!(Natural::TWO.to_digits_asc(&Natural::from(6u32)).to_debug_string(), "[2]");
assert_eq!(
Natural::from(123456u32).to_digits_asc(&Natural::from(3u32)).to_debug_string(),
"[0, 1, 1, 0, 0, 1, 1, 2, 0, 0, 2]"
);

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::{Two, Zero};
use malachite_base::num::conversion::traits::Digits;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.to_digits_desc(&Natural::from(6u32)).to_debug_string(), "[]");
assert_eq!(Natural::TWO.to_digits_desc(&Natural::from(6u32)).to_debug_string(), "[2]");
assert_eq!(
Natural::from(123456u32).to_digits_desc(&Natural::from(3u32)).to_debug_string(),
"[2, 0, 0, 2, 1, 1, 0, 0, 1, 1, 0]"
);

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### Worst-case complexity

$T(n, m) = O(nm (\log (nm))^2 \log\log (nm))$

$M(n, m) = O(nm \log (nm))$

where $T$ is time, $M$ is additional memory, $n$ is digits.count(), and $m$ is base.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::conversion::traits::Digits;
use malachite_base::strings::ToDebugString;
use malachite_base::vecs::vec_from_str;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from_digits_asc(
&Natural::from(64u32),
vec_from_str::<Natural>("[0, 0, 0]").unwrap().into_iter()
).to_debug_string(),
"Some(0)"
);
assert_eq!(
Natural::from_digits_asc(
&Natural::from(3u32),
vec_from_str::<Natural>("[0, 1, 1, 0, 0, 1, 1, 2, 0, 0, 2]").unwrap().into_iter()
).to_debug_string(),
"Some(123456)"
);
assert_eq!(
Natural::from_digits_asc(
&Natural::from(8u32),
vec_from_str::<Natural>("[3, 7, 1]").unwrap().into_iter()
).to_debug_string(),
"Some(123)"
);
assert_eq!(
Natural::from_digits_asc(
&Natural::from(8u32),
vec_from_str::<Natural>("[1, 10, 3]").unwrap().into_iter()
).to_debug_string(),
"None"
);

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### Worst-case complexity

$T(n, m) = O(nm (\log (nm))^2 \log\log (nm))$

$M(n, m) = O(nm \log (nm))$

where $T$ is time, $M$ is additional memory, $n$ is digits.count(), and $m$ is base.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::conversion::traits::Digits;
use malachite_base::strings::ToDebugString;
use malachite_base::vecs::vec_from_str;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from_digits_desc(
&Natural::from(64u32),
vec_from_str::<Natural>("[0, 0, 0]").unwrap().into_iter()
).to_debug_string(),
"Some(0)"
);
assert_eq!(
Natural::from_digits_desc(
&Natural::from(3u32),
vec_from_str::<Natural>("[2, 0, 0, 2, 1, 1, 0, 0, 1, 1, 0]").unwrap().into_iter()
).to_debug_string(),
"Some(123456)"
);
assert_eq!(
Natural::from_digits_desc(
&Natural::from(8u32),
vec_from_str::<Natural>("[1, 7, 3]").unwrap().into_iter()
).to_debug_string(),
"Some(123)"
);
assert_eq!(
Natural::from_digits_desc(
&Natural::from(8u32),
vec_from_str::<Natural>("[3, 10, 1]").unwrap().into_iter()
).to_debug_string(),
"None"
);

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in ascending order (least- to most-significant).

If the Natural is 0, the Vec is empty; otherwise, it ends with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_i = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Returns a Vec containing the digits of a Natural in descending order (most- to least-significant).

If the Natural is 0, the Vec is empty; otherwise, it begins with a nonzero digit.

$f(x, b) = (d_i)_ {i=0}^{k-1}$, where $0 \leq d_i < b$ for all $i$, $k=0$ or $d_{k-1} \neq 0$, and

$$\sum_{i=0}^{k-1}b^i d_{k-i-1} = x.$$

##### 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 self.significant_bits().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in ascending order (least- to most-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^id_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts an iterator of digits into a Natural.

The input digits are in descending order (most- to least-significant). The function returns None if any of the digits are greater than or equal to the base.

$$f((d_i)_ {i=0}^{k-1}, b) = \sum_{i=0}^{k-1}b^{k-i-1}d_i.$$

##### 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 digits.count().

##### Panics

Panics if base is less than 2.

##### Examples

See here.

Converts a Natural to a String.

##### 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 self.significant_bits().

##### Examples
extern crate malachite_base;

use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::ZERO.to_string(), "0");
assert_eq!(Natural::from(123u32).to_string(), "123");
assert_eq!(
Natural::from_str("1000000000000").unwrap().to_string(),
"1000000000000"
);
assert_eq!(format!("{:05}", Natural::from(123u32)), "00123");

Divides a Natural by another Natural, taking the first by value and the second by reference. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(Natural::from(23u32) / &Natural::from(10u32), 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap() /
&Natural::from_str("1234567890987").unwrap(),
810000006723u64
);
The resulting type after applying the / operator.

Divides a Natural by another Natural, taking both by reference. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(&Natural::from(23u32) / &Natural::from(10u32), 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
&Natural::from_str("1000000000000000000000000").unwrap() /
&Natural::from_str("1234567890987").unwrap(),
810000006723u64
);
The resulting type after applying the / operator.

Divides a Natural by another Natural, taking the first by reference and the second by value. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(&Natural::from(23u32) / Natural::from(10u32), 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
&Natural::from_str("1000000000000000000000000").unwrap() /
Natural::from_str("1234567890987").unwrap(),
810000006723u64
);
The resulting type after applying the / operator.

Divides a Natural by another Natural, taking both by value. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left \lfloor \frac{x}{y} \right \rfloor.$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(Natural::from(23u32) / Natural::from(10u32), 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap() /
Natural::from_str("1234567890987").unwrap(),
810000006723u64
);
The resulting type after applying the / operator.

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by reference. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
x /= &Natural::from(10u32);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
x /= &Natural::from_str("1234567890987").unwrap();
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value. The quotient is rounded towards negative infinity. The quotient and remainder (which is not computed) satisfy $x = qy + r$ and $0 \leq r < y$.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
x /= Natural::from(10u32);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
x /= Natural::from_str("1234567890987").unwrap();
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value and returning the remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = x - y\left \lfloor \frac{x}{y} \right \rfloor,$$ $$x \gets \left \lfloor \frac{x}{y} \right \rfloor.$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivAssignMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.div_assign_mod(&Natural::from(10u32)), 3);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(
x.div_assign_mod(&Natural::from_str("1234567890987").unwrap()),
530068894399u64
);
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value and returning the remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = x - y\left \lfloor \frac{x}{y} \right \rfloor,$$ $$x \gets \left \lfloor \frac{x}{y} \right \rfloor.$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivAssignMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.div_assign_mod(Natural::from(10u32)), 3);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(x.div_assign_mod(Natural::from_str("1234567890987").unwrap()), 530068894399u64);
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by reference and returning the remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = x - y\left \lfloor \frac{x}{y} \right \rfloor,$$ $$x \gets \left \lfloor \frac{x}{y} \right \rfloor.$$

For Naturals, div_assign_rem is equivalent to div_assign_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivAssignRem;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.div_assign_rem(&Natural::from(10u32)), 3);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(
x.div_assign_rem(&Natural::from_str("1234567890987").unwrap()),
530068894399u64
);
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value and returning the remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = x - y\left \lfloor \frac{x}{y} \right \rfloor,$$ $$x \gets \left \lfloor \frac{x}{y} \right \rfloor.$$

For Naturals, div_assign_rem is equivalent to div_assign_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivAssignRem;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
let mut x = Natural::from(23u32);
assert_eq!(x.div_assign_rem(Natural::from(10u32)), 3);
assert_eq!(x, 2);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
let mut x = Natural::from_str("1000000000000000000000000").unwrap();
assert_eq!(x.div_assign_rem(Natural::from_str("1234567890987").unwrap()), 530068894399u64);
assert_eq!(x, 810000006723u64);

Divides a Natural by another Natural, taking the first by value and the second by reference. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$f(x, y) = \frac{x}{y}.$$

If you are unsure whether the division will be exact, use self / &other instead. If you’re unsure and you want to know, use self.div_mod(&other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use self.div_round(&other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExact;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
assert_eq!(Natural::from(56088u32).div_exact(&Natural::from(456u32)), 123);

// 123456789000 * 987654321000 = 121932631112635269000000
assert_eq!(
Natural::from_str("121932631112635269000000").unwrap()
.div_exact(&Natural::from_str("987654321000").unwrap()),
123456789000u64
);

Divides a Natural by another Natural, taking both by reference. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$f(x, y) = \frac{x}{y}.$$

If you are unsure whether the division will be exact, use &self / &other instead. If you’re unsure and you want to know, use (&self).div_mod(&other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use (&self).div_round(&other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExact;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
assert_eq!((&Natural::from(56088u32)).div_exact(&Natural::from(456u32)), 123);

// 123456789000 * 987654321000 = 121932631112635269000000
assert_eq!(
(&Natural::from_str("121932631112635269000000").unwrap())
.div_exact(&Natural::from_str("987654321000").unwrap()),
123456789000u64
);

Divides a Natural by another Natural, taking the first by reference and the second by value. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$f(x, y) = \frac{x}{y}.$$

If you are unsure whether the division will be exact, use &self / other instead. If you’re unsure and you want to know, use self.div_mod(other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use (&self).div_round(other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExact;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
assert_eq!((&Natural::from(56088u32)).div_exact(Natural::from(456u32)), 123);

// 123456789000 * 987654321000 = 121932631112635269000000
assert_eq!(
(&Natural::from_str("121932631112635269000000").unwrap())
.div_exact(Natural::from_str("987654321000").unwrap()),
123456789000u64
);

Divides a Natural by another Natural, taking both by value. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$f(x, y) = \frac{x}{y}.$$

If you are unsure whether the division will be exact, use self / other instead. If you’re unsure and you want to know, use self.div_mod(other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use self.div_round(other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExact;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
assert_eq!(Natural::from(56088u32).div_exact(Natural::from(456u32)), 123);

// 123456789000 * 987654321000 = 121932631112635269000000
assert_eq!(
Natural::from_str("121932631112635269000000").unwrap()
.div_exact(Natural::from_str("987654321000").unwrap()),
123456789000u64
);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by reference. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$x \gets \frac{x}{y}.$$

If you are unsure whether the division will be exact, use self /= &other instead. If you’re unsure and you want to know, use self.div_assign_mod(&other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use self.div_round_assign(&other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExactAssign;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
let mut x = Natural::from(56088u32);
x.div_exact_assign(&Natural::from(456u32));
assert_eq!(x, 123);

// 123456789000 * 987654321000 = 121932631112635269000000
let mut x = Natural::from_str("121932631112635269000000").unwrap();
x.div_exact_assign(&Natural::from_str("987654321000").unwrap());
assert_eq!(x, 123456789000u64);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value. The first Natural must be exactly divisible by the second. If it isn’t, this function may panic or return a meaningless result.

$$x \gets \frac{x}{y}.$$

If you are unsure whether the division will be exact, use self /= other instead. If you’re unsure and you want to know, use self.div_assign_mod(other) and check whether the remainder is zero. If you want a function that panics if the division is not exact, use self.div_round_assign(other, RoundingMode::Exact).

##### 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 other is zero. May panic if self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivExactAssign;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 123 * 456 = 56088
let mut x = Natural::from(56088u32);
x.div_exact_assign(Natural::from(456u32));
assert_eq!(x, 123);

// 123456789000 * 987654321000 = 121932631112635269000000
let mut x = Natural::from_str("121932631112635269000000").unwrap();
x.div_exact_assign(Natural::from_str("987654321000").unwrap());
assert_eq!(x, 123456789000u64);

Divides a Natural by another Natural, taking the first by value and the second by reference and returning the quotient and remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
Natural::from(23u32).div_mod(&Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.div_mod(&Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking both by reference and returning the quotient and remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
(&Natural::from(23u32)).div_mod(&Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.div_mod(&Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking the first by reference and the second by value and returning the quotient and remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
(&Natural::from(23u32)).div_mod(Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.div_mod(Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking both by value and returning the quotient and remainder. The quotient is rounded towards negative infinity.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivMod;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(Natural::from(23u32).div_mod(Natural::from(10u32)).to_debug_string(), "(2, 3)");

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.div_mod(Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking the first by value and the second by reference and returning the quotient and remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

For Naturals, div_rem is equivalent to div_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivRem;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
Natural::from(23u32).div_rem(&Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.div_rem(&Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking both by reference and returning the quotient and remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

For Naturals, div_rem is equivalent to div_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivRem;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
(&Natural::from(23u32)).div_rem(&Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.div_rem(&Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking the first by reference and the second by value and returning the quotient and remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

For Naturals, div_rem is equivalent to div_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivRem;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(
(&Natural::from(23u32)).div_rem(Natural::from(10u32)).to_debug_string(),
"(2, 3)"
);

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.div_rem(Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking both by value and returning the quotient and remainder. The quotient is rounded towards zero.

The quotient and remainder satisfy $x = qy + r$ and $0 \leq r < y$.

$$f(x, y) = \left ( \left \lfloor \frac{x}{y} \right \rfloor, \space x - y\left \lfloor \frac{x}{y} \right \rfloor \right ).$$

For Naturals, div_rem is equivalent to div_mod.

##### 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 other is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivRem;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;
use std::str::FromStr;

// 2 * 10 + 3 = 23
assert_eq!(Natural::from(23u32).div_rem(Natural::from(10u32)).to_debug_string(), "(2, 3)");

// 810000006723 * 1234567890987 + 530068894399 = 1000000000000000000000000
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.div_rem(Natural::from_str("1234567890987").unwrap()).to_debug_string(),
"(810000006723, 530068894399)"
);

Divides a Natural by another Natural, taking the first by value and the second by reference and rounding according to a specified rounding mode.

Let $q = \frac{x}{y}$:

$$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = \lfloor q \rfloor.$$

$$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = \lceil q \rceil.$$

$$f(x, y, \mathrm{Nearest}) = \begin{cases} \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2}, \\ \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases}$$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \N$.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRound, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(10u32).div_round(&Natural::from(4u32), RoundingMode::Down), 2);
assert_eq!(
Natural::from(10u32).pow(12).div_round(&Natural::from(3u32), RoundingMode::Floor),
333333333333u64
);
assert_eq!(Natural::from(10u32).div_round(&Natural::from(4u32), RoundingMode::Up), 3);
assert_eq!(
Natural::from(10u32).pow(12).div_round(&Natural::from(3u32), RoundingMode::Ceiling),
333333333334u64);
assert_eq!(Natural::from(10u32).div_round(&Natural::from(5u32), RoundingMode::Exact), 2);
assert_eq!(Natural::from(10u32).div_round(&Natural::from(3u32), RoundingMode::Nearest), 3);
assert_eq!(Natural::from(20u32).div_round(&Natural::from(3u32), RoundingMode::Nearest), 7);
assert_eq!(Natural::from(10u32).div_round(&Natural::from(4u32), RoundingMode::Nearest), 2);
assert_eq!(Natural::from(14u32).div_round(&Natural::from(4u32), RoundingMode::Nearest), 4);

Divides a Natural by another Natural, taking both by reference and rounding according to a specified rounding mode.

Let $q = \frac{x}{y}$:

$$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = \lfloor q \rfloor.$$

$$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = \lceil q \rceil.$$

$$f(x, y, \mathrm{Nearest}) = \begin{cases} \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2}, \\ \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases}$$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \N$.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRound, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(10u32)).div_round(&Natural::from(4u32), RoundingMode::Down), 2);
assert_eq!(
(&Natural::from(10u32).pow(12)).div_round(&Natural::from(3u32), RoundingMode::Floor),
333333333333u64
);
assert_eq!((&Natural::from(10u32)).div_round(&Natural::from(4u32), RoundingMode::Up), 3);
assert_eq!(
(&Natural::from(10u32).pow(12)).div_round(&Natural::from(3u32), RoundingMode::Ceiling),
333333333334u64);
assert_eq!(
(&Natural::from(10u32)).div_round(&Natural::from(5u32), RoundingMode::Exact),
2
);
assert_eq!(
(&Natural::from(10u32)).div_round(&Natural::from(3u32), RoundingMode::Nearest),
3
);
assert_eq!(
(&Natural::from(20u32)).div_round(&Natural::from(3u32), RoundingMode::Nearest),
7
);
assert_eq!(
(&Natural::from(10u32)).div_round(&Natural::from(4u32), RoundingMode::Nearest),
2
);
assert_eq!(
(&Natural::from(14u32)).div_round(&Natural::from(4u32), RoundingMode::Nearest),
4
);

Divides a Natural by another Natural, taking the first by reference and the second by value and rounding according to a specified rounding mode.

Let $q = \frac{x}{y}$:

$$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = \lfloor q \rfloor.$$

$$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = \lceil q \rceil.$$

$$f(x, y, \mathrm{Nearest}) = \begin{cases} \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2}, \\ \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases}$$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \N$.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRound, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(10u32)).div_round(Natural::from(4u32), RoundingMode::Down), 2);
assert_eq!(
(&Natural::from(10u32).pow(12)).div_round(Natural::from(3u32), RoundingMode::Floor),
333333333333u64
);
assert_eq!((&Natural::from(10u32)).div_round(Natural::from(4u32), RoundingMode::Up), 3);
assert_eq!(
(&Natural::from(10u32).pow(12)).div_round(Natural::from(3u32), RoundingMode::Ceiling),
333333333334u64);
assert_eq!((&Natural::from(10u32)).div_round(Natural::from(5u32), RoundingMode::Exact), 2);
assert_eq!(
(&Natural::from(10u32)).div_round(Natural::from(3u32), RoundingMode::Nearest),
3
);
assert_eq!(
(&Natural::from(20u32)).div_round(Natural::from(3u32), RoundingMode::Nearest),
7
);
assert_eq!(
(&Natural::from(10u32)).div_round(Natural::from(4u32), RoundingMode::Nearest),
2
);
assert_eq!(
(&Natural::from(14u32)).div_round(Natural::from(4u32), RoundingMode::Nearest),
4
);

Divides a Natural by another Natural, taking both by value and rounding according to a specified rounding mode.

Let $q = \frac{x}{y}$:

$$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = \lfloor q \rfloor.$$

$$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = \lceil q \rceil.$$

$$f(x, y, \mathrm{Nearest}) = \begin{cases} \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2}, \\ \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even}, \\ \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases}$$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \N$.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRound, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(10u32).div_round(Natural::from(4u32), RoundingMode::Down), 2);
assert_eq!(
Natural::from(10u32).pow(12).div_round(Natural::from(3u32), RoundingMode::Floor),
333333333333u64
);
assert_eq!(Natural::from(10u32).div_round(Natural::from(4u32), RoundingMode::Up), 3);
assert_eq!(
Natural::from(10u32).pow(12).div_round(Natural::from(3u32), RoundingMode::Ceiling),
333333333334u64);
assert_eq!(Natural::from(10u32).div_round(Natural::from(5u32), RoundingMode::Exact), 2);
assert_eq!(Natural::from(10u32).div_round(Natural::from(3u32), RoundingMode::Nearest), 3);
assert_eq!(Natural::from(20u32).div_round(Natural::from(3u32), RoundingMode::Nearest), 7);
assert_eq!(Natural::from(10u32).div_round(Natural::from(4u32), RoundingMode::Nearest), 2);
assert_eq!(Natural::from(14u32).div_round(Natural::from(4u32), RoundingMode::Nearest), 4);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by reference and rounding according to a specified rounding mode.

See the DivRound documentation for details.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRoundAssign, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

let mut n = Natural::from(10u32);
n.div_round_assign(&Natural::from(4u32), RoundingMode::Down);
assert_eq!(n, 2);

let mut n = Natural::from(10u32).pow(12);
n.div_round_assign(&Natural::from(3u32), RoundingMode::Floor);
assert_eq!(n, 333333333333u64);

let mut n = Natural::from(10u32);
n.div_round_assign(&Natural::from(4u32), RoundingMode::Up);
assert_eq!(n, 3);

let mut n = Natural::from(10u32).pow(12);
n.div_round_assign(&Natural::from(3u32), RoundingMode::Ceiling);
assert_eq!(n, 333333333334u64);

let mut n = Natural::from(10u32);
n.div_round_assign(&Natural::from(5u32), RoundingMode::Exact);
assert_eq!(n, 2);

let mut n = Natural::from(10u32);
n.div_round_assign(&Natural::from(3u32), RoundingMode::Nearest);
assert_eq!(n, 3);

let mut n = Natural::from(20u32);
n.div_round_assign(&Natural::from(3u32), RoundingMode::Nearest);
assert_eq!(n, 7);

let mut n = Natural::from(10u32);
n.div_round_assign(&Natural::from(4u32), RoundingMode::Nearest);
assert_eq!(n, 2);

let mut n = Natural::from(14u32);
n.div_round_assign(&Natural::from(4u32), RoundingMode::Nearest);
assert_eq!(n, 4);

Divides a Natural by another Natural in place, taking the Natural on the right-hand side by value and rounding according to a specified rounding mode.

See the DivRound documentation for details.

##### 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 other is zero, or if rm is Exact but self is not divisible by other.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivRoundAssign, Pow};
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

let mut n = Natural::from(10u32);
n.div_round_assign(Natural::from(4u32), RoundingMode::Down);
assert_eq!(n, 2);

let mut n = Natural::from(10u32).pow(12);
n.div_round_assign(Natural::from(3u32), RoundingMode::Floor);
assert_eq!(n, 333333333333u64);

let mut n = Natural::from(10u32);
n.div_round_assign(Natural::from(4u32), RoundingMode::Up);
assert_eq!(n, 3);

let mut n = Natural::from(10u32).pow(12);
n.div_round_assign(Natural::from(3u32), RoundingMode::Ceiling);
assert_eq!(n, 333333333334u64);

let mut n = Natural::from(10u32);
n.div_round_assign(Natural::from(5u32), RoundingMode::Exact);
assert_eq!(n, 2);

let mut n = Natural::from(10u32);
n.div_round_assign(Natural::from(3u32), RoundingMode::Nearest);
assert_eq!(n, 3);

let mut n = Natural::from(20u32);
n.div_round_assign(Natural::from(3u32), RoundingMode::Nearest);
assert_eq!(n, 7);

let mut n = Natural::from(10u32);
n.div_round_assign(Natural::from(4u32), RoundingMode::Nearest);
assert_eq!(n, 2);

let mut n = Natural::from(14u32);
n.div_round_assign(Natural::from(4u32), RoundingMode::Nearest);
assert_eq!(n, 4);

Returns whether a Natural is divisible by another Natural; in other words, whether the first is a multiple of the second. The first Naturals is taken by reference and the second by value.

This means that zero is divisible by any Natural, including zero; but a nonzero Natural is never divisible by zero.

It’s more efficient to use this function than to compute the remainder and check whether it’s zero.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivisibleBy;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::ZERO.divisible_by(&Natural::ZERO), true);
assert_eq!(Natural::from(100u32).divisible_by(&Natural::from(3u32)), false);
assert_eq!(Natural::from(102u32).divisible_by(&Natural::from(3u32)), true);
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.divisible_by(&Natural::from_str("1000000000000").unwrap()),
true
);

Returns whether a Natural is divisible by another Natural; in other words, whether the first is a multiple of the second. Both Naturals are taken by reference.

This means that zero is divisible by any Natural, including zero; but a nonzero Natural is never divisible by zero.

It’s more efficient to use this function than to compute the remainder and check whether it’s zero.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivisibleBy;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!((&Natural::ZERO).divisible_by(&Natural::ZERO), true);
assert_eq!((&Natural::from(100u32)).divisible_by(&Natural::from(3u32)), false);
assert_eq!((&Natural::from(102u32)).divisible_by(&Natural::from(3u32)), true);
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.divisible_by(&Natural::from_str("1000000000000").unwrap()),
true
);

Returns whether a Natural is divisible by another Natural; in other words, whether the first is a multiple of the second. The first Naturals are taken by reference and the second by value.

This means that zero is divisible by any Natural, including zero; but a nonzero Natural is never divisible by zero.

It’s more efficient to use this function than to compute the remainder and check whether it’s zero.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivisibleBy;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!((&Natural::ZERO).divisible_by(Natural::ZERO), true);
assert_eq!((&Natural::from(100u32)).divisible_by(Natural::from(3u32)), false);
assert_eq!((&Natural::from(102u32)).divisible_by(Natural::from(3u32)), true);
assert_eq!(
(&Natural::from_str("1000000000000000000000000").unwrap())
.divisible_by(Natural::from_str("1000000000000").unwrap()),
true
);

Returns whether a Natural is divisible by another Natural; in other words, whether the first is a multiple of the second. Both Naturals are taken by value.

This means that zero is divisible by any Natural, including zero; but a nonzero Natural is never divisible by zero.

It’s more efficient to use this function than to compute the remainder and check whether it’s zero.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::DivisibleBy;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::ZERO.divisible_by(Natural::ZERO), true);
assert_eq!(Natural::from(100u32).divisible_by(Natural::from(3u32)), false);
assert_eq!(Natural::from(102u32).divisible_by(Natural::from(3u32)), true);
assert_eq!(
Natural::from_str("1000000000000000000000000").unwrap()
.divisible_by(Natural::from_str("1000000000000").unwrap()),
true
);

Returns whether a Natural is divisible by $2^k$.

$f(x, k) = (2^k|x)$.

$f(x, k) = (\exists n \in \N : \ x = n2^k)$.

If self is 0, the result is always true; otherwise, it is equivalent to self.trailing_zeros().unwrap() <= pow, but more efficient.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::{DivisibleByPowerOf2, Pow};
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!(Natural::ZERO.divisible_by_power_of_2(100), true);
assert_eq!(Natural::from(100u32).divisible_by_power_of_2(2), true);
assert_eq!(Natural::from(100u32).divisible_by_power_of_2(3), false);
assert_eq!(Natural::from(10u32).pow(12).divisible_by_power_of_2(12), true);
assert_eq!(Natural::from(10u32).pow(12).divisible_by_power_of_2(13), false);

Computes the double factorial of a number.

$$f(n) = n!! = n \times (n - 2) \times (n - 4) \times \cdots \times i,$$ where $i$ is 1 if $n$ is odd and $2$ if $n$ is even.

TODO

##### Examples
use malachite_base::num::arithmetic::traits::DoubleFactorial;
use malachite_nz::natural::Natural;

assert_eq!(Natural::double_factorial(0), 1);
assert_eq!(Natural::double_factorial(1), 1);
assert_eq!(Natural::double_factorial(2), 2);
assert_eq!(Natural::double_factorial(3), 3);
assert_eq!(Natural::double_factorial(4), 8);
assert_eq!(Natural::double_factorial(5), 15);
assert_eq!(Natural::double_factorial(6), 48);
assert_eq!(Natural::double_factorial(7), 105);
assert_eq!(
Natural::double_factorial(99).to_string(),
"2725392139750729502980713245400918633290796330545803413734328823443106201171875"
);
assert_eq!(
Natural::double_factorial(100).to_string(),
"34243224702511976248246432895208185975118675053719198827915654463488000000000000"
);

This is equivalent to mpz_2fac_ui from mpz/2fac_ui.c, GMP 6.2.1.

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first number is taken by value and the second and third by reference.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Integer::from(123).eq_mod(&Integer::from(223), &Natural::from(100u32)),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
&Integer::from_str("-999999012346").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
&Integer::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first and third numbers are taken by value and the second by reference.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Integer::from(123).eq_mod(&Integer::from(223), Natural::from(100u32)),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
&Integer::from_str("-999999012346").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
&Integer::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first is taken by value and the second and third by reference.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from(123u32).eq_mod(&Natural::from(223u32), &Natural::from(100u32)),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
&Natural::from_str("2000000987654").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
&Natural::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first and third are taken by value and the second by reference.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from(123u32).eq_mod(&Natural::from(223u32), Natural::from(100u32)),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
&Natural::from_str("2000000987654").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
&Natural::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. All three numbers are taken by reference.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Integer::from(123)).eq_mod(&Integer::from(223), &Natural::from(100u32)),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
&Integer::from_str("-999999012346").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
&Integer::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first two numbers are taken by reference and the third by value.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Integer::from(123)).eq_mod(&Integer::from(223), Natural::from(100u32)),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
&Integer::from_str("-999999012346").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
&Integer::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. All three are taken by reference.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Natural::from(123u32)).eq_mod(&Natural::from(223u32), &Natural::from(100u32)),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
&Natural::from_str("2000000987654").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
&Natural::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first and second are taken by reference and the third by value.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Natural::from(123u32)).eq_mod(&Natural::from(223u32), Natural::from(100u32)),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
&Natural::from_str("2000000987654").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
&Natural::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first two numbers are taken by value and the third by reference.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Integer::from(123).eq_mod(Integer::from(223), &Natural::from(100u32)),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
Integer::from_str("-999999012346").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
Integer::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first and third numbers are taken by reference and the third by value.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Integer::from(123)).eq_mod(Integer::from(223), &Natural::from(100u32)),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
Integer::from_str("-999999012346").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
Integer::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. The first number is taken by reference and the second and third by value.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Integer::from(123)).eq_mod(Integer::from(223), Natural::from(100u32)),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
Integer::from_str("-999999012346").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Integer::from_str("1000000987654").unwrap()).eq_mod(
Integer::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether an Integer is equivalent to another Integer modulo a Natural; that is, whether the difference between the two Integers is a multiple of the Natural. All three numbers are taken by value.

Two Integers are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Integer::from(123).eq_mod(Integer::from(223), Natural::from(100u32)),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
Integer::from_str("-999999012346").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Integer::from_str("1000000987654").unwrap().eq_mod(
Integer::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first two are taken by value and the third by reference.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from(123u32).eq_mod(Natural::from(223u32), &Natural::from(100u32)),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
Natural::from_str("2000000987654").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
Natural::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first and third are taken by reference and the second by value.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Natural::from(123u32)).eq_mod(Natural::from(223u32), &Natural::from(100u32)),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
Natural::from_str("2000000987654").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
Natural::from_str("2000000987655").unwrap(),
&Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. The first is taken by reference and the second and third by value.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
(&Natural::from(123u32)).eq_mod(Natural::from(223u32), Natural::from(100u32)),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
Natural::from_str("2000000987654").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
(&Natural::from_str("1000000987654").unwrap()).eq_mod(
Natural::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether a Natural is equivalent to another Natural modulo a third; that is, whether the difference between the first two is a multiple of the third. All three are taken by value.

Two Naturals are equal to each other modulo 0 iff they are equal.

$f(x, y, m) = (x \equiv y \mod m)$.

$f(x, y, m) = (\exists k \in \Z : x - y = km)$.

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqMod;
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(
Natural::from(123u32).eq_mod(Natural::from(223u32), Natural::from(100u32)),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
Natural::from_str("2000000987654").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
true
);
assert_eq!(
Natural::from_str("1000000987654").unwrap().eq_mod(
Natural::from_str("2000000987655").unwrap(),
Natural::from_str("1000000000000").unwrap()
),
false
);

Returns whether one Natural is equal to another modulo $2^k$; that is, whether their $k$ least-significant bits are equal.

$f(x, y, k) = (x \equiv y \mod 2^k)$.

$f(x, y, k) = (\exists n \in \Z : x - y = n2^k)$.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::EqModPowerOf2;
use malachite_base::num::basic::traits::Zero;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::ZERO).eq_mod_power_of_2(&Natural::from(256u32), 8), true);
assert_eq!(
(&Natural::from(0b1101u32)).eq_mod_power_of_2(&Natural::from(0b10101u32), 3),
true
);
assert_eq!(
(&Natural::from(0b1101u32)).eq_mod_power_of_2(&Natural::from(0b10101u32), 4),
false
);

Computes the GCD (greatest common divisor) of two Naturals $a$ and $b$, and also the coefficients $x$ and $y$ in Bézout’s identity $ax+by=\gcd(a,b)$. Both Naturals are taken by reference.

The are infinitely many $x$, $y$ that satisfy the identity for any $a$, $b$, so the full specification is more detailed:

• $f(0, 0) = (0, 0, 0)$.
• $f(a, ak) = (a, 1, 0)$ if $a > 0$ and $k \neq 1$.
• $f(bk, b) = (b, 0, 1)$ if $b > 0$.
• $f(a, b) = (g, x, y)$ if $a \neq 0$ and $b \neq 0$ and $\gcd(a, b) \neq \min(a, b)$, where $g = \gcd(a, b) \geq 0$, $ax + by = g$, $x \leq \lfloor b/g \rfloor$, and $y \leq \lfloor a/g \rfloor$.
##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::ExtendedGcd;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
(&Natural::from(3u32)).extended_gcd(&Natural::from(5u32)).to_debug_string(),
"(1, 2, -1)"
);
assert_eq!(
(&Natural::from(240u32)).extended_gcd(&Natural::from(46u32)).to_debug_string(),
"(2, -9, 47)"
);

Computes the GCD (greatest common divisor) of two Naturals $a$ and $b$, and also the coefficients $x$ and $y$ in Bézout’s identity $ax+by=\gcd(a,b)$. The first Natural is taken by value and the second by reference.

The are infinitely many $x$, $y$ that satisfy the identity for any $a$, $b$, so the full specification is more detailed:

• $f(0, 0) = (0, 0, 0)$.
• $f(a, ak) = (a, 1, 0)$ if $a > 0$ and $k \neq 1$.
• $f(bk, b) = (b, 0, 1)$ if $b > 0$.
• $f(a, b) = (g, x, y)$ if $a \neq 0$ and $b \neq 0$ and $\gcd(a, b) \neq \min(a, b)$, where $g = \gcd(a, b) \geq 0$, $ax + by = g$, $x \leq \lfloor b/g \rfloor$, and $y \leq \lfloor a/g \rfloor$.
##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::ExtendedGcd;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(3u32).extended_gcd(&Natural::from(5u32)).to_debug_string(),
"(1, 2, -1)"
);
assert_eq!(
Natural::from(240u32).extended_gcd(&Natural::from(46u32)).to_debug_string(),
"(2, -9, 47)"
);

Computes the GCD (greatest common divisor) of two Naturals $a$ and $b$, and also the coefficients $x$ and $y$ in Bézout’s identity $ax+by=\gcd(a,b)$. The first Natural is taken by reference and the second by value.

The are infinitely many $x$, $y$ that satisfy the identity for any $a$, $b$, so the full specification is more detailed:

• $f(0, 0) = (0, 0, 0)$.
• $f(a, ak) = (a, 1, 0)$ if $a > 0$ and $k \neq 1$.
• $f(bk, b) = (b, 0, 1)$ if $b > 0$.
• $f(a, b) = (g, x, y)$ if $a \neq 0$ and $b \neq 0$ and $\gcd(a, b) \neq \min(a, b)$, where $g = \gcd(a, b) \geq 0$, $ax + by = g$, $x \leq \lfloor b/g \rfloor$, and $y \leq \lfloor a/g \rfloor$.
##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::ExtendedGcd;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
(&Natural::from(3u32)).extended_gcd(Natural::from(5u32)).to_debug_string(),
"(1, 2, -1)"
);
assert_eq!(
(&Natural::from(240u32)).extended_gcd(Natural::from(46u32)).to_debug_string(),
"(2, -9, 47)"
);

Computes the GCD (greatest common divisor) of two Naturals $a$ and $b$, and also the coefficients $x$ and $y$ in Bézout’s identity $ax+by=\gcd(a,b)$. Both Naturals are taken by value.

The are infinitely many $x$, $y$ that satisfy the identity for any $a$, $b$, so the full specification is more detailed:

• $f(0, 0) = (0, 0, 0)$.
• $f(a, ak) = (a, 1, 0)$ if $a > 0$ and $k \neq 1$.
• $f(bk, b) = (b, 0, 1)$ if $b > 0$.
• $f(a, b) = (g, x, y)$ if $a \neq 0$ and $b \neq 0$ and $\gcd(a, b) \neq \min(a, b)$, where $g = \gcd(a, b) \geq 0$, $ax + by = g$, $x \leq \lfloor b/g \rfloor$, and $y \leq \lfloor a/g \rfloor$.
##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::ExtendedGcd;
use malachite_base::strings::ToDebugString;
use malachite_nz::natural::Natural;

assert_eq!(
Natural::from(3u32).extended_gcd(Natural::from(5u32)).to_debug_string(),
"(1, 2, -1)"
);
assert_eq!(
Natural::from(240u32).extended_gcd(Natural::from(46u32)).to_debug_string(),
"(2, -9, 47)"
);

Computes the factorial of a number.

$$f(n) = n! = 1 \times 2 \times 3 \times \cdots \times n.$$

TODO

##### Examples
use malachite_base::num::arithmetic::traits::Factorial;
use malachite_nz::natural::Natural;

assert_eq!(Natural::factorial(0), 1);
assert_eq!(Natural::factorial(1), 1);
assert_eq!(Natural::factorial(2), 2);
assert_eq!(Natural::factorial(3), 6);
assert_eq!(Natural::factorial(4), 24);
assert_eq!(Natural::factorial(5), 120);
assert_eq!(
Natural::factorial(100).to_string(),
"9332621544394415268169923885626670049071596826438162146859296389521759999322991560894\
1463976156518286253697920827223758251185210916864000000000000000000000000"
);

This is equivalent to mpz_fac_ui from mpz/fac_ui.c, GMP 6.2.1.

Returns the floor of the base-$b$ logarithm of a positive Natural.

$f(x, b) = \lfloor\log_b x\rfloor$.

##### 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 x.significant_bits().

##### Panics

Panics if self is 0 or base is less than 2.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorLogBase;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(80u32).floor_log_base(&Natural::from(3u32)), 3);
assert_eq!(Natural::from(81u32).floor_log_base(&Natural::from(3u32)), 4);
assert_eq!(Natural::from(82u32).floor_log_base(&Natural::from(3u32)), 4);
assert_eq!(Natural::from(4294967296u64).floor_log_base(&Natural::from(10u32)), 9);

This is equivalent to fmpz_flog from fmpz/flog.c, FLINT 2.7.1.

Returns the floor of the base-2 logarithm of a positive Natural.

$f(x) = \lfloor\log_2 x\rfloor$.

##### Panics

Panics if self is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorLogBase2;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(3u32).floor_log_base_2(), 1);
assert_eq!(Natural::from(100u32).floor_log_base_2(), 6);

Returns the floor of the base-$2^k$ logarithm of a positive Natural.

$f(x, k) = \lfloor\log_{2^k} x\rfloor$.

##### Panics

Panics if self is 0 or pow is 0.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorLogBasePowerOf2;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(100u32).floor_log_base_power_of_2(2), 3);
assert_eq!(Natural::from(4294967296u64).floor_log_base_power_of_2(8), 4);

Returns the floor of the $n$th root of a Natural, taking the Natural by reference.

$f(x, n) = \lfloor\sqrt[n]{x}\rfloor$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorRoot;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(999u16)).floor_root(3), 9);
assert_eq!((&Natural::from(1000u16)).floor_root(3), 10);
assert_eq!((&Natural::from(1001u16)).floor_root(3), 10);
assert_eq!((&Natural::from(100000000000u64)).floor_root(5), 158);

Returns the floor of the $n$th root of a Natural, taking the Natural by value.

$f(x, n) = \lfloor\sqrt[n]{x}\rfloor$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorRoot;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(999u16).floor_root(3), 9);
assert_eq!(Natural::from(1000u16).floor_root(3), 10);
assert_eq!(Natural::from(1001u16).floor_root(3), 10);
assert_eq!(Natural::from(100000000000u64).floor_root(5), 158);

Replaces a Natural with the floor of its $n$th root.

$x \gets \lfloor\sqrt[n]{x}\rfloor$.

##### 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 self.significant_bits().

##### Panics

Panics if exp is zero.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorRootAssign;
use malachite_nz::natural::Natural;

let mut x = Natural::from(999u16);
x.floor_root_assign(3);
assert_eq!(x, 9);

let mut x = Natural::from(1000u16);
x.floor_root_assign(3);
assert_eq!(x, 10);

let mut x = Natural::from(1001u16);
x.floor_root_assign(3);
assert_eq!(x, 10);

let mut x = Natural::from(100000000000u64);
x.floor_root_assign(5);
assert_eq!(x, 158);

Returns the floor of the square root of a Natural, taking it by value.

$f(x) = \lfloor\sqrt{x}\rfloor$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorSqrt;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(99u8)).floor_sqrt(), 9);
assert_eq!((&Natural::from(100u8)).floor_sqrt(), 10);
assert_eq!((&Natural::from(101u8)).floor_sqrt(), 10);
assert_eq!((&Natural::from(1000000000u32)).floor_sqrt(), 31622);
assert_eq!((&Natural::from(10000000000u64)).floor_sqrt(), 100000);

Returns the floor of the square root of a Natural, taking it by value.

$f(x) = \lfloor\sqrt{x}\rfloor$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorSqrt;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(99u8).floor_sqrt(), 9);
assert_eq!(Natural::from(100u8).floor_sqrt(), 10);
assert_eq!(Natural::from(101u8).floor_sqrt(), 10);
assert_eq!(Natural::from(1000000000u32).floor_sqrt(), 31622);
assert_eq!(Natural::from(10000000000u64).floor_sqrt(), 100000);

Replaces a Natural with the floor of its square root.

$x \gets \lfloor\sqrt{x}\rfloor$.

##### 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().

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::FloorSqrtAssign;
use malachite_nz::natural::Natural;

let mut x = Natural::from(99u8);
x.floor_sqrt_assign();
assert_eq!(x, 9);

let mut x = Natural::from(100u8);
x.floor_sqrt_assign();
assert_eq!(x, 10);

let mut x = Natural::from(101u8);
x.floor_sqrt_assign();
assert_eq!(x, 10);

let mut x = Natural::from(1000000000u32);
x.floor_sqrt_assign();
assert_eq!(x, 31622);

let mut x = Natural::from(10000000000u64);
x.floor_sqrt_assign();
assert_eq!(x, 100000);

Converts a Natural to an Integer, taking the Natural by reference.

##### Worst-case complexity

$T(n) = O(n)$

$M(n) = O(n)$

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

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;

assert_eq!(Integer::from(&Natural::from(123u32)), 123);
assert_eq!(Integer::from(&Natural::from(10u32).pow(12)), 1000000000000u64);

Converts a Natural to an Integer, taking the Natural by value.

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Pow;
use malachite_nz::integer::Integer;
use malachite_nz::natural::Natural;

assert_eq!(Integer::from(Natural::from(123u32)), 123);
assert_eq!(Integer::from(Natural::from(10u32).pow(12)), 1000000000000u64);

Converts an unsigned primitive integer to a Natural, where the integer’s width is larger than a Limb’s.

This implementation is general enough to also work for usize, regardless of whether it is equal in width to Limb.

##### Examples

See here.

Converts an unsigned primitive integer to a Natural, where the integer’s width is smaller than a Limb’s.

##### Examples

See here.

Converts an unsigned primitive integer to a Natural, where the integer’s width is smaller than a Limb’s.

##### Examples

See here.

Converts a Limb to a Natural.

##### Examples

See here.

Converts an unsigned primitive integer to a Natural, where the integer’s width is smaller than a Limb’s.

##### Examples

See here.

Converts an unsigned primitive integer to a Natural, where the integer’s width is larger than a Limb’s.

This implementation is general enough to also work for usize, regardless of whether it is equal in width to Limb.

##### Examples

See here.

Converts a string, possibly in scientfic notation, to a Natural.

Use FromSciStringOptions to specify the base (from 2 to 36, inclusive) and the rounding mode, in case rounding is necessary because the string represents a non-integer.

If the base is greater than 10, the higher digits are represented by the letters 'a' through 'z' or 'A' through 'Z'; the case doesn’t matter and doesn’t need to be consistent.

Exponents are allowed, and are indicated using the character 'e' or 'E'. If the base is 15 or greater, an ambiguity arises where it may not be clear whether 'e' is a digit or an exponent indicator. To resolve this ambiguity, always use a '+' or '-' sign after the exponent indicator when the base is 15 or greater.

The exponent itself is always parsed using base 10.

Decimal (or other-base) points are allowed. These are most useful in conjunction with exponents, but they may be used on their own. If the string represents a non-integer, the rounding mode specified in options is used to round to an integer.

If the string is unparseable, None is returned. None is also returned if the rounding mode in options is Exact, but rounding is necessary.

##### Worst-case complexity

$T(n, m) = O(m^n n \log m (\log n + \log\log m))$

$M(n, m) = O(m^n n \log m)$

where $T$ is time, $M$ is additional memory, $n$ is s.len(), and $m$ is options.base.

##### Examples
extern crate malachite_base;

use malachite_base::num::conversion::string::options::FromSciStringOptions;
use malachite_base::num::conversion::traits::FromSciString;
use malachite_base::rounding_modes::RoundingMode;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from_sci_string("123").unwrap(), 123);
assert_eq!(Natural::from_sci_string("123.5").unwrap(), 124);
assert_eq!(Natural::from_sci_string("-123.5"), None);
assert_eq!(Natural::from_sci_string("1.23e10").unwrap(), 12300000000u64);

let mut options = FromSciStringOptions::default();
assert_eq!(Natural::from_sci_string_with_options("123.5", options).unwrap(), 124);

options.set_rounding_mode(RoundingMode::Floor);
assert_eq!(Natural::from_sci_string_with_options("123.5", options).unwrap(), 123);

options = FromSciStringOptions::default();
options.set_base(16);
assert_eq!(Natural::from_sci_string_with_options("ff", options).unwrap(), 255);

options = FromSciStringOptions::default();
options.set_base(36);
assert_eq!(Natural::from_sci_string_with_options("1e5", options).unwrap(), 1805);
assert_eq!(Natural::from_sci_string_with_options("1e+5", options).unwrap(), 60466176);
assert_eq!(Natural::from_sci_string_with_options("1e-5", options).unwrap(), 0);
Converts a &str, possibly in scientific notation, to a number, using the default FromSciStringOptions. Read more

Converts an string to a Natural.

If the string does not represent a valid Natural, an Err is returned. To be valid, the string must be nonempty and only contain the chars '0' through '9'. Leading zeros are allowed.

##### 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 s.len().

##### Examples
use malachite_nz::natural::Natural;
use std::str::FromStr;

assert_eq!(Natural::from_str("123456").unwrap(), 123456);
assert_eq!(Natural::from_str("00123456").unwrap(), 123456);
assert_eq!(Natural::from_str("0").unwrap(), 0);

assert!(Natural::from_str("").is_err());
assert!(Natural::from_str("a").is_err());
assert!(Natural::from_str("-5").is_err());
The associated error which can be returned from parsing.

Converts an string, in a specified base, to a Natural.

If the string does not represent a valid Natural, an Err is returned. To be valid, the string must be nonempty and only contain the chars '0' through '9', 'a' through 'z', and 'A' through 'Z'; and only characters that represent digits smaller than the base are allowed. Leading zeros are always allowed.

##### 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 s.len().

##### Panics

Panics if base is less than 2 or greater than 36.

##### Examples
extern crate malachite_base;

use malachite_base::num::conversion::traits::{Digits, FromStringBase};
use malachite_nz::natural::Natural;

assert_eq!(Natural::from_string_base(10, "123456").unwrap(), 123456);
assert_eq!(Natural::from_string_base(10, "00123456").unwrap(), 123456);
assert_eq!(Natural::from_string_base(16, "0").unwrap(), 0);

assert!(Natural::from_string_base(10, "").is_none());
assert!(Natural::from_string_base(10, "a").is_none());
assert!(Natural::from_string_base(10, "-5").is_none());
assert!(Natural::from_string_base(2, "2").is_none());

Computes the GCD (greatest common divisor) of two Naturals, taking both by reference.

The GCD of 0 and $n$, for any $n$, is 0. In particular, $\gcd(0, 0) = 0$, which makes sense if we interpret “greatest” to mean “greatest by the divisibility order”.

$$f(x, y) = \gcd(x, y).$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Gcd;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(3u32)).gcd(&Natural::from(5u32)), 1);
assert_eq!((&Natural::from(12u32)).gcd(&Natural::from(90u32)), 6);

Computes the GCD (greatest common divisor) of two Naturals, taking the first by value and the second by reference.

The GCD of 0 and $n$, for any $n$, is 0. In particular, $\gcd(0, 0) = 0$, which makes sense if we interpret “greatest” to mean “greatest by the divisibility order”.

$$f(x, y) = \gcd(x, y).$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Gcd;
use malachite_nz::natural::Natural;

assert_eq!(Natural::from(3u32).gcd(&Natural::from(5u32)), 1);
assert_eq!(Natural::from(12u32).gcd(&Natural::from(90u32)), 6);

Computes the GCD (greatest common divisor) of two Naturals, taking the first by reference and the second by value.

The GCD of 0 and $n$, for any $n$, is 0. In particular, $\gcd(0, 0) = 0$, which makes sense if we interpret “greatest” to mean “greatest by the divisibility order”.

$$f(x, y) = \gcd(x, y).$$

##### 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()).

##### Examples
extern crate malachite_base;

use malachite_base::num::arithmetic::traits::Gcd;
use malachite_nz::natural::Natural;

assert_eq!((&Natural::from(3u32)).gcd(Natural::from(5u32)), 1);
assert_eq!((&Natural::from(12u32)).gcd(Natural::from(90u32)), 6);

Computes the GCD (greatest common divisor) of two Naturals, taking both by value.

The GCD of 0 and $n$, for any $n$, is 0. In particular, $\gcd(0, 0) = 0$, which makes sense if we interpret “greatest” to mean “greatest by the divisibility order”.

$$f(x, y) = \gcd(x, y).$$

##### 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.significa