# Numeric casts

This crate provides casts and checked casts.

## Quick examples

```use az::{Az, OverflowingAs, WrappingAs};
use core::num::Wrapping;

// Panics on overflow with `debug_assertions`, otherwise wraps
assert_eq!(12i32.az::<u32>(), 12u32);

// Always wraps
let wrapped = 1u32.wrapping_neg();
assert_eq!((-1).wrapping_as::<u32>(), wrapped);
assert_eq!((-1).overflowing_as::<u32>(), (wrapped, true));

// Wrapping can also be obtained using `Wrapping`
assert_eq!((-1).az::<Wrapping<u32>>().0, wrapped);```

Conversions from floating-point to integers are also supported. Numbers are rounded towards zero, but the `Round` wrapper can be used to convert floating-point numbers to integers with rounding to the nearest, with ties rounded to even.

```use az::{Az, CheckedAs, Round, SaturatingAs};
use core::f32;

assert_eq!(15.7.az::<i32>(), 15);
assert_eq!(Round(15.5).az::<i32>(), 16);
assert_eq!(1.5e20.saturating_as::<i32>(), i32::max_value());
assert_eq!(f32::NAN.checked_as::<i32>(), None);```

## Implementing casts for other types

To provide casts for another type, you should implement the `Cast` trait and if necessary the `CheckedCast`, `SaturatingCast`, `WrappingCast`, `OverflowingCast` and `UnwrappedCast` traits. The `Az`, `CheckedAs`, `SaturatingAs`, `WrappingAs`, `OverflowingAs` and `UnwrappedAs` traits are already implemented for all types using blanket implementations that make use of the former traits.

The cast traits can also be implemented for references. This can be useful for expensive types that are not `Copy`. For example if you have your own integer type that does not implement `Copy`, you could implement casts like in the following example. (The type `I` could be an expensive type, for example a bignum integer, but for the example it is only a wrapped `i32`.)

```use az::{Az, Cast};
use core::borrow::Borrow;

struct I(i32);
impl Cast<i64> for &'_ I {
fn cast(self) -> i64 { self.0.cast() }
}

let owned = I(12);
assert_eq!((&owned).az::<i64>(), 12);
// borrow can be used if chaining is required
assert_eq!(owned.borrow().az::<i64>(), 12);```

## Using the az crate

The az crate is available on crates.io. To use it in your crate, add it as a dependency inside Cargo.toml:

``````[dependencies]
az = "1.1"
``````

The crate requires rustc version 1.31.0 or later.

This crate is free software: you can redistribute it and/or modify it under the terms of either

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache License, Version 2.0, shall be dual licensed as above, without any additional terms or conditions.

## Structs

 Round Used to convert floating-point numbers to integers with rounding to the nearest, with ties rounded to even.

## Traits

 Az Used to cast values. Cast Used to cast values. CheckedAs Used for checked casts. CheckedCast Used for checked casts. OverflowingAs Used for overflowing casts. OverflowingCast Used for overflowing casts. SaturatingAs Used to cast into the destination type, saturating if the value does not fit. SaturatingCast Used to cast into the destination type, saturating if the value does not fit. UnwrappedAs Used to cast values, panicking if the value does not fit. UnwrappedCast Used to cast values, panicking if the value does not fit. WrappingAs Wrapping cast. WrappingCast Wrapping cast.

## Functions

 cast Casts the value. checked_cast Casts the value, returning `None` if the value does not fit. overflowing_cast Overflowing cast. saturating_cast Casts the value, saturating if the value does not fit. unwrapped_cast Casts the value, panicking if the value does not fit. wrapping_cast Casts the value, wrapping on overflow.