Module casts

Helpers for performing lossless integer casts.

The as keyword can be used to perform casts between integer types, but it unfortunately makes no distinction between casts that are lossless, and casts from a larger type into a smaller one that might silently strip data away. Thus, its use in the kernel is discouraged in favor of From implementations.

Conversely, there are casts that are lossless depending on the build architecture (such as casting usize to u64 on 32 or 64 bit archs), but not supported by From implementations in the standard library because they are not portable. It does however make sense for the kernel to support these, if only for code that is architecture-specific.

This module provides ways to perform such conversions safely:

• A series of const functions (e.g. usize_as_u64) supporting safe conversions in const context. Conversions supported by From implementations in the standard library are also covered as the From trait cannot be used in const context.
• Two extension traits, FromSafeCast and IntoSafeCast, providing conversion methods similar to From and Into for conversions that are safe to perform in the kernel, but not supported by the standard library.
• Another series of const functions (e.g. u64_into_u8) supporting the conversion of a const value from a larger type into a smaller one, provided the value fits into the destination type. This is useful if a constant is defined as a larger type, but needs to be used as a smaller one.
• An arch sub-module, defining more conversion functions that are only guaranteed to be lossless for a given pointer size. These can only be used in code that is specific to a given pointer size.

Examples

use kernel::num::casts::{self, FromSafeCast, IntoSafeCast};

// Conversion from const context.
const USIZED_CONST: usize = casts::u8_as_usize(255u8);

// Non-const conversions.
let a = u64::from_safe_cast(4096usize);
let b: u64 = 4096usize.into_safe_cast();

Modules

• arch
  Conversions that are only lossless for the current architecture.

Traits

• FromSafeCast
  Extension trait providing guaranteed lossless cast to Self from T.
• IntoSafeCast
  Counterpart to the FromSafeCast trait, i.e. this trait is to FromSafeCast what Into is to From.

Functions

• u8_as_u16
  Losslessly converts a u8 into a u16.
• u8_as_u32
  Losslessly converts a u8 into a u32.
• u8_as_u64
  Losslessly converts a u8 into a u64.
• u8_as_usize
  Losslessly converts a u8 into a usize.
• u16_as_u32
  Losslessly converts a u16 into a u32.
• u16_as_u64
  Losslessly converts a u16 into a u64.
• u16_as_usize
  Losslessly converts a u16 into a usize.
• u16_into_u8
  Performs a build-time safe conversion of a u16 constant value into a u8.
• u32_as_u64
  Losslessly converts a u32 into a u64.
• u32_as_usize
  Losslessly converts a u32 into a usize.
• u32_into_u8
  Performs a build-time safe conversion of a u32 constant value into a u8.
• u32_into_u16
  Performs a build-time safe conversion of a u32 constant value into a u16.
• u64_into_u8
  Performs a build-time safe conversion of a u64 constant value into a u8.
• u64_into_u16
  Performs a build-time safe conversion of a u64 constant value into a u16.
• u64_into_u32
  Performs a build-time safe conversion of a u64 constant value into a u32.
• usize_as_u64
  Losslessly converts a usize into a u64.
• usize_into_u8
  Performs a build-time safe conversion of a usize constant value into a u8.
• usize_into_u16
  Performs a build-time safe conversion of a usize constant value into a u16.
• usize_into_u32
  Performs a build-time safe conversion of a usize constant value into a u32.