Crate cast

Ergonomic, checked cast functions for primitive types

This crate provides one checked cast function for each numeric primitive. Use these functions to perform a cast from any other numeric primitive:

use cast::{u8, u16, Error};

// Infallible operations, like integer promotion, are equivalent to a normal
// cast with `as`
assert_eq!(u16(0u8), 0u16);

// Everything else will return a `Result` depending on the success of the
// operation
assert_eq!(u8(0u16), Ok(0u8));
assert_eq!(u8(256u16), Err(Error::Overflow));
assert_eq!(u8(-1i8), Err(Error::Underflow));
assert_eq!(u8(1. / 0.), Err(Error::Infinite));
assert_eq!(u8(0. / 0.), Err(Error::NaN));

There are no namespace problems between these functions, the “primitive modules” in core/std and the built-in primitive types, so all them can be in the same scope:

use std::u8;
use cast::{u8, u16};

// `u8` as a type
let x: u8 = 0;
// `u8` as a module
let y = u16(u8::MAX);
// `u8` as a function
let z = u8(y).unwrap();

The checked cast functionality is also usable with type aliases via the cast static method:

use std::os::raw::c_ulonglong;
// NOTE avoid shadowing `std::convert::From` - cf. rust-lang/rfcs#1311
use cast::From as _0;

assert_eq!(c_ulonglong::cast(0u8), 0u64);

This crate also provides a From trait that can be used, for example, to create a generic function that accepts any type that can be infallibly casted to u32.

fn to_u32<T>(x: T) -> u32
    // reads as: "where u32 can be casted from T with output u32"
    where u32: cast::From<T, Output=u32>,
{
    cast::u32(x)
}

assert_eq!(to_u32(0u8), 0u32);
assert_eq!(to_u32(1u16), 1u32);
assert_eq!(to_u32(2u32), 2u32);

// to_u32(-1i32);  // Compile error

Minimal Supported Rust Version

This crate is guaranteed to compile as a dependency on stable Rust 1.31 and up. It’s not guaranteed that cargo test-ing this crate follows the MSRV. It might compile on older versions but that may change in any new patch release.

Building without std

This crate can be used without Rust’s std crate by declaring it as follows in your Cargo.toml:

cast = { version = "*", default-features = false }

Enums

• Error
  Cast errors

Traits

• From
  The “cast from” operation

Functions

• f32
  Checked cast function
• f64
  Checked cast function
• i8
  Checked cast function
• i16
  Checked cast function
• i32
  Checked cast function
• i64
  Checked cast function
• i128
  Checked cast function
• isize
  Checked cast function
• u8
  Checked cast function
• u16
  Checked cast function
• u32
  Checked cast function
• u64
  Checked cast function
• u128
  Checked cast function
• usize
  Checked cast function