Expand description
§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.2"
The crate requires rustc version 1.31.0 or later.
§License
This crate is free software: you can redistribute it and/or modify it under the terms of either
- the Apache License, Version 2.0 or
- the MIT License
at your option.
§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§
- Used to convert floating-point numbers to integers with rounding to the nearest, with ties rounded to even.
Traits§
- Used to cast values.
- Used to cast values.
- Used to cast values.
- Used for checked casts.
- Used for checked casts.
- Used for checked casts.
- Used for overflowing casts.
- Used for overflowing casts.
- Used for overflowing casts.
- Used to cast into the destination type, saturating if the value does not fit.
- Used to cast into the destination type, saturating if the value does not fit.
- Used to cast, saturating if the value does not fit.
- Used to cast values, panicking if the value does not fit.
- Used to cast values, panicking if the value does not fit.
- Used to cast values, panicking if the value does not fit.
- Wrapping cast.
- Wrapping cast.
- Wrapping cast.
Functions§
- Casts the value.
- Casts the value, returning
None
if the value does not fit. - Overflowing cast.
- Casts the value, saturating if the value does not fit.
- Casts the value, panicking if the value does not fit.
- Casts the value, wrapping on overflow.