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:

extern crate cast;

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:

extern crate cast;

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:

extern crate cast;

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.

extern crate cast;

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

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
isize	Checked cast function
u8	Checked cast function
u16	Checked cast function
u32	Checked cast function
u64	Checked cast function
usize	Checked cast function