Numeric casts

This crate provides casts and checked casts.

What’s new

Version 1.1.2 news (2021-08-23)

• Now the [Debug] implementation for Round outputs the value only without “Round()” around it.

Version 1.1.1 news (2021-03-25)

• The track_caller attribute is now applied to panicking functions if supported by the compiler.

Version 1.1.0 news (2021-02-03)

• Unwrapped casts were added, which panic on overflow even when debug assertions are not enabled.
  • UnwrappedCast
  • UnwrappedAs
  • unwrapped_cast

Other releases

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

Quick examples

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

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

// Always wraps let wrapped = 1u32.wrappingneg(); asserteq!((-1).wrappingas::(), wrapped); asserteq!((-1).overflowing_as::(), (wrapped, true));

// Wrapping can also be obtained using Wrapping assert_eq!((-1).az::>().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.

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

asserteq!(15.7.az::(), 15); asserteq!(Round(15.5).az::(), 16); asserteq!(1.5e20.saturatingas::(), i32::maxvalue()); asserteq!(f32::NAN.checked_as::(), 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. (I could be an expensive type, for example a bignum integer, but for the example it is only a wrapped [i32].)

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

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

let owned = I(12); assert_eq!(owned.borrow().az::(), 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]:

toml [dependencies] az = "1.1"

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.