Numeric casts

This crate provides casts and checked casts.

What’s new

Version 1.3.0 news (2026-01-19)

• The crate now requires rustc version 1.85.0 or later.
• The StrictCast, StrictAs and StrictCastFrom traits were added to replace UnwrappedCast, UnwrappedAs and UnwrappedCastFrom, which will be deprecated in version 1.4.0.
• The strict_cast function was added to replace unwrapped_cast, which will be deprecated in version 1.4.0.
• The experimental feature nightly-float was added.

Other releases

Details on other releases can be found in RELEASES.md.

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, StrictCast, SaturatingCast, WrappingCast and OverflowingCast traits. The Az, CheckedAs, StrictAs, SaturatingAs, WrappingAs and OverflowingAs 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.3"

The crate requires rustc version 1.85.0 or later.

Experimental optional features

It is not considered a breaking change if the following experimental features are removed. The removal of experimental features would however require a minor version bump. Similarly, on a minor version bump, optional dependencies can be updated to an incompatible newer version.

1. nightly-float, disabled by default. This requires the nightly compiler, and implements casts for the experimental f16 and f128 primitives. (The plan is to always implement the conversions and comparisons and remove this experimental feature once the primitives are stabilized.)

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.