pub trait Byteable {
type ByteArray: ByteArray;
const BYTE_SIZE: usize = <Self::ByteArray>::BYTE_SIZE;
// Required methods
fn to_byte_array(self) -> Self::ByteArray;
fn from_byte_array(byte_array: Self::ByteArray) -> Self;
}Expand description
A trait for types that can be converted to and from a byte array.
The Byteable trait provides a zero-overhead, zero-copy conversion between Rust types
and their byte representations. This is particularly useful for:
- Binary file I/O
- Network protocols
- Low-level system programming
- Memory-mapped files
- Interfacing with C libraries
§Associated Types
ByteArray: The type of the byte array representation. Usually[u8; N]whereNis the size of the type in bytes.
§Associated Constants
BYTE_SIZE: The size of the type in bytes. This is automatically derived fromByteArray::BYTE_SIZE.
§Methods
to_byte_array: Converts the value into its byte array representationfrom_byte_array: Constructs a value from its byte array representation
§Safety
While the trait itself is safe, implementations often use unsafe code internally
(particularly via the #[derive(Byteable)] macro). The derive macro automatically handles
memory layout and endianness conversion. Users must ensure:
- All fields are primitive types or use endianness attributes
- All byte patterns are valid for the field types
- No types with invalid bit patterns are used (e.g.,
bool,char, enums)
§Implementations
The trait is implemented for:
- All primitive numeric types (
u8,i32,f64, etc.) - Fixed-size arrays of
Byteabletypes BigEndian<T>andLittleEndian<T>wrappers- Custom types via
#[derive(Byteable)]with automatic endianness handling
§Examples
§Using primitive types
use byteable::Byteable;
let value: u32 = 0x12345678;
let bytes = value.to_byte_array();
// On little-endian systems
#[cfg(target_endian = "little")]
assert_eq!(bytes, [0x78, 0x56, 0x34, 0x12]);
let restored = u32::from_byte_array(bytes);
assert_eq!(restored, value);§Using with custom types
use byteable::Byteable;
#[derive(Byteable, Debug, PartialEq, Clone, Copy)]
struct Color {
r: u8,
g: u8,
b: u8,
a: u8,
}
let color = Color { r: 255, g: 128, b: 64, a: 255 };
let bytes = color.to_byte_array();
assert_eq!(bytes, [255, 128, 64, 255]);
let restored = Color::from_byte_array(bytes);
assert_eq!(restored, color);§Using with arrays
use byteable::Byteable;
let values: [u16; 3] = [1, 2, 3];
let byte_array = values.to_byte_array();
// byte_array is [[u8; 2]; 3] - array of byte arrays
let restored = <[u16; 3]>::from_byte_array(byte_array);
assert_eq!(restored, values);Provided Associated Constants§
Required Associated Types§
Required Methods§
Sourcefn to_byte_array(self) -> Self::ByteArray
fn to_byte_array(self) -> Self::ByteArray
Converts this value into a byte array.
§Examples
use byteable::Byteable;
let value: u16 = 0x1234;
let bytes = value.to_byte_array();Sourcefn from_byte_array(byte_array: Self::ByteArray) -> Self
fn from_byte_array(byte_array: Self::ByteArray) -> Self
Constructs a value from a byte array.
§Examples
use byteable::Byteable;
let bytes = [0x34, 0x12];
let value = u16::from_byte_array(bytes);
#[cfg(target_endian = "little")]
assert_eq!(value, 0x1234);Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.