# num - Rust
API documentation for the Rust `num` crate.
Keywords: rust, rustlang, rust-lang, num

# Crate num [−] [src]

A collection of numeric types and traits for Rust.

This includes new types for big integers, rationals, and complex numbers, new traits for generic programming on numeric properties like `Integer`, and generic range iterators.

## Example

This example uses the BigRational type and Newton's method to approximate a square root to arbitrary precision:

    extern crate num;

    use num::FromPrimitive;
    use num::bigint::BigInt;
    use num::rational::{Ratio, BigRational};

    fn approx_sqrt(number: u64, iterations: usize) -> BigRational {
        let start: Ratio<BigInt> = Ratio::from_integer(FromPrimitive::from_u64(number).unwrap());
        let mut approx = start.clone();

        for _ in 0..iterations {
            approx = (&approx + (&start / &approx)) /
                Ratio::from_integer(FromPrimitive::from_u64(2).unwrap());
        }

        approx
    }

    fn main() {
        println!("{}", approx_sqrt(10, 4)); // prints 4057691201/1283082416
    }

## Compatibility

The `num` crate is tested for rustc 1.8 and greater.

## Modules

bigint |
cast |
complex |
integer |
iter |
pow |
rational |
traits |

## Structs

BigInt | A big signed integer type.
BigUint | A big unsigned integer type.
Complex | A complex number in Cartesian form.

## Traits

Bounded | Numbers which have upper and lower bounds
CheckedAdd | Performs addition that returns `None` instead of wrapping around on overflow.
CheckedDiv | Performs division that returns `None` instead of panicking on division by zero and instead of wrapping around on underflow and overflow.
CheckedMul | Performs multiplication that returns `None` instead of wrapping around on underflow or overflow.
CheckedSub | Performs subtraction that returns `None` instead of wrapping around on underflow.
Float | Generic trait for floating point numbers
FromPrimitive | A generic trait for converting a number to a value.
Integer |
Num | The base trait for numeric types, covering `0` and `1` values, comparisons, basic numeric operations, and string conversion.
NumCast | An interface for casting between machine scalars.
One | Defines a multiplicative identity element for `Self`.
PrimInt |
Saturating | Saturating math operations
Signed | Useful functions for signed numbers (i.e. numbers that can be negative).
ToPrimitive | A generic trait for converting a value to a number.
Unsigned | A trait for values which cannot be negative
Zero | Defines an additive identity element for `Self`.

## Functions

abs | Computes the absolute value.
abs_sub | The positive difference of two numbers.
checked_pow | Raises a value to the power of exp, returning `None` if an overflow occurred.
clamp | A value bounded by a minimum and a maximum
one | Returns the multiplicative identity, `1`.
range | Returns an iterator over the given range [start, stop) (that is, starting at start (inclusive), and ending at stop (exclusive)).
range_inclusive | Return an iterator over the range [start, stop]
range_step | Return an iterator over the range [start, stop) by `step`. It handles overflow by stopping.
range_step_inclusive | Return an iterator over the range [start, stop] by `step`. It handles overflow by stopping.
signum | Returns the sign of the number.
zero | Returns the additive identity, `0`.

## Type Definitions

BigRational | Alias for arbitrary precision rationals.
Rational | Alias for a `Ratio` of machine-sized integers.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)