Crate asbytes

Expand description

§Module :: asbytes

The asbytes crate provides a convenient trait, AsBytes, for viewing common data structures as raw byte slices (&[u8]). It focuses on types that are safe to represent as bytes (Plain Old Data, or POD), leveraging the safety guarantees of the underlying bytemuck crate.

§Why `asbytes`?

While bytemuck provides the core functionality for safe byte-level casting (like bytemuck::cast_slice for collections and bytemuck::bytes_of for single items), asbytes offers a unified trait-based approach for common use cases:

Consistency: The AsBytes trait provides a single method, .as_bytes(), that works consistently across supported types like Vec<T>, slices (&[T]), arrays ([T; N]), and single POD items wrapped in a tuple (T,).
Readability: Calling .as_bytes() clearly signals the intent to get the raw byte representation, which is useful for tasks like serialization, hashing, or interfacing with low-level APIs (graphics, networking, etc.).
Simpler Generics: Functions can accept T: AsBytes to work generically with the byte representation of different compatible data structures.
Convenience: The trait also provides .byte_size() and .len() methods for easily getting the size in bytes and the number of elements, respectively.

Essentially, asbytes acts as a focused convenience layer on top of bytemuck for the specific task of viewing data as bytes via a consistent trait method.

§How asbytes Differs from bytemuck

While bytemuck offers safe transmutation via its Pod trait and functions like cast_slice, it does not expose a dedicated trait for converting data structures into byte slices. asbytes introduces the AsBytes trait, abstracting these conversions and providing additional conveniences—such as direct byte size computation—on top of bytemuck’s proven foundation.

§Example

// Make sure bytemuck is available for derives
extern crate bytemuck;
use asbytes::AsBytes; // Import the trait

// Define a POD struct
#[ repr( C ) ]
#[ derive( Clone, Copy, bytemuck::Pod, bytemuck::Zeroable ) ]
struct Point
{
  x : f32,
  y : f32,
}

fn main()
{
  // --- Collections ---
  let points_vec : Vec< Point > = vec![ Point { x : 1.0, y : 2.0 }, Point { x : 3.0, y : 4.0 } ];
  let points_slice : &[ Point ] = &points_vec[ .. ];
  let points_array : [ Point; 1 ] = [ Point { x : 5.0, y : 6.0 } ];

  let vec_bytes = points_vec.as_bytes();
  let slice_bytes = points_slice.as_bytes();
  let array_bytes = points_array.as_bytes();

  println!( "Vec Bytes: length={}, data={:?}", points_vec.byte_size(), vec_bytes );
  println!( "Slice Bytes: length={}, data={:?}", slice_bytes.byte_size(), slice_bytes );
  println!( "Array Bytes: length={}, data={:?}", points_array.byte_size(), array_bytes );
  println!( "Vec Element Count: {}", points_vec.len() ); // Output: 2
  println!( "Array Element Count: {}", points_array.len() ); // Output: 1

  // --- Single POD Item (using tuple trick) ---
  let single_point = Point { x : -1.0, y : -2.0 };
  let single_point_tuple = ( single_point, ); // Wrap in a single-element tuple

  let point_bytes = single_point_tuple.as_bytes();
  println!( "Single Point Bytes: length={}, data={:?}", single_point_tuple.byte_size(), point_bytes );
  println!( "Single Point Element Count: {}", single_point_tuple.len() ); // Output: 1

  let scalar_tuple = ( 12345u32, );
  let scalar_bytes = scalar_tuple.as_bytes();
  println!( "Scalar Bytes: length={}, data={:?}", scalar_tuple.byte_size(), scalar_bytes );
}

§To add to your project

cargo add asbytes

§Try out from the repository

git clone https://github.com/Wandalen/wTools
cd wTools
cd examples/asbytes
cargo run

Modules§

checked: Checked versions of the casting functions exposed in crate root that support CheckedBitPattern types.
dependency: Namespace with dependencies.
exposed: Exposed namespace of the module.
orphan: Orphan namespace of the module.
own: Own namespace of the module.
prelude: Prelude to use essentials: use my_module::prelude::*.

Macros§

offset_of: Find the offset in bytes of the given $field of $Type. Requires an already initialized $instance value to work with.

Enums§

PodCastError: The things that can go wrong when casting between Pod data forms.

Traits§

AnyBitPattern: Marker trait for “plain old data” types that are valid for any bit pattern.
AsBytes: Trait for converting data to byte slices. This trait abstracts the conversion of types that implement Pod into their raw byte representation.
CheckedBitPattern: A marker trait that allows types that have some invalid bit patterns to be used in places that otherwise require AnyBitPattern or Pod types by performing a runtime check on a perticular set of bits. This is particularly useful for types like fieldless (‘C-style’) enums, char, bool, and structs containing them.
Contiguous: A trait indicating that:
NoUninit: Marker trait for “plain old data” types with no uninit (or padding) bytes.
Pod: Marker trait for “plain old data”.
PodInOption: Trait for types which are Pod when wrapped in Option.
TransparentWrapper: A trait which indicates that a type is a #[repr(transparent)] wrapper around the Inner value.
Zeroable: Trait for types that can be safely created with zeroed.
ZeroableInOption: Trait for types which are Zeroable when wrapped in Option.

Functions§

bytes_of: Re-interprets &T as &[u8].
bytes_of_mut: Re-interprets &mut T as &mut [u8].
cast: Cast A into B
cast_mut: Cast &mut A into &mut B.
cast_ref: Cast &A into &B.
cast_slice: Cast &[A] into &[B].
cast_slice_mut: Cast &mut [A] into &mut [B].
fill_zeroes: Fill all bytes of slice with zeroes (see Zeroable).
from_bytes: Re-interprets &[u8] as &T.
from_bytes_mut: Re-interprets &mut [u8] as &mut T.
pod_align_to: As align_to, but safe because of the Pod bound.
pod_align_to_mut: As align_to_mut, but safe because of the Pod bound.
pod_read_unaligned: Reads the slice into a T value.
try_cast: Try to cast A into B.
try_cast_mut: Try to convert a &mut A into &mut B.
try_cast_ref: Try to convert a &A into &B.
try_cast_slice: Try to convert &[A] into &[B] (possibly with a change in length).
try_cast_slice_mut: Try to convert &mut [A] into &mut [B] (possibly with a change in length).
try_from_bytes: Re-interprets &[u8] as &T.
try_from_bytes_mut: Re-interprets &mut [u8] as &mut T.
try_pod_read_unaligned: Reads from the bytes as if they were a T.
write_zeroes: Fill all bytes of target with zeroes (see Zeroable).

Derive Macros§

AnyBitPattern: Derive the AnyBitPattern trait for a struct
CheckedBitPattern: Derive the CheckedBitPattern trait for a struct or enum.
Contiguous: Derive the Contiguous trait for an enum
NoUninit: Derive the NoUninit trait for a struct or enum
Pod: Derive the Pod trait for a struct
TransparentWrapper: Derive the TransparentWrapper trait for a struct
Zeroable: Derive the Zeroable trait for a struct

Crate asbytesCopy item path