Crate cast

source ·
Expand description

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

Cast errors

Traits

The “cast from” operation

Functions

Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function
Checked cast function