pub unsafe trait FromBytes {
// Provided methods
fn read_from<B: ByteSlice>(bytes: B) -> Option<Self>
where Self: Sized { ... }
fn read_from_prefix<B: ByteSlice>(bytes: B) -> Option<Self>
where Self: Sized { ... }
fn read_from_suffix<B: ByteSlice>(bytes: B) -> Option<Self>
where Self: Sized { ... }
fn new_zeroed() -> Self
where Self: Sized { ... }
fn new_box_zeroed() -> Box<Self>
where Self: Sized { ... }
fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
where Self: Sized { ... }
fn new_vec_zeroed(len: usize) -> Vec<Self>
where Self: Sized { ... }
}Expand description
Types for which any byte pattern is valid.
WARNING: Do not implement this trait yourself! Instead, use
#[derive(FromBytes)].
FromBytes types can safely be deserialized from an untrusted sequence of
bytes because any byte sequence corresponds to a valid instance of the type.
FromBytes is ignorant of byte order. For byte order-aware types, see the
byteorder module.
Safety
If T: FromBytes, then unsafe code may assume that it is sound to treat any
initialized sequence of bytes of length size_of::<T>() as a T. If a type
is marked as FromBytes which violates this contract, it may cause
undefined behavior.
If a type has the following properties, then it is safe to implement
FromBytes for that type:
- If the type is a struct:
- All of its fields must implement
FromBytes
- All of its fields must implement
- If the type is an enum:
- It must be a C-like enum (meaning that all variants have no fields)
- It must have a defined representation (
reprsC,u8,u16,u32,u64,usize,i8,i16,i32,i64, orisize). - The maximum number of discriminants must be used (so that every possible
bit pattern is a valid one). Be very careful when using the
C,usize, orisizerepresentations, as their size is platform-dependent.
Rationale
Why isn’t an explicit representation required for structs?
Per the Rust reference,
The representation of a type can change the padding between fields, but does not change the layout of the fields themselves.
Since the layout of structs only consists of padding bytes and field bytes,
a struct is soundly FromBytes if:
- its padding is soundly
FromBytes, and - its fields are soundly
FromBytes.
The answer to the first question is always yes: padding bytes do not have any validity constraints. A discussion of this question in the Unsafe Code Guidelines Working Group concluded that it would be virtually unimaginable for future versions of rustc to add validity constraints to padding bytes.
Whether a struct is soundly FromBytes therefore solely depends on whether
its fields are FromBytes.
Provided Methods§
sourcefn read_from<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
fn read_from<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
Reads a copy of Self from bytes.
If bytes.len() != size_of::<Self>(), read_from returns None.
sourcefn read_from_prefix<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
fn read_from_prefix<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
Reads a copy of Self from the prefix of bytes.
read_from_prefix reads a Self from the first size_of::<Self>()
bytes of bytes. If bytes.len() < size_of::<Self>(), it returns
None.
sourcefn read_from_suffix<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
fn read_from_suffix<B: ByteSlice>(bytes: B) -> Option<Self>where
Self: Sized,
Reads a copy of Self from the suffix of bytes.
read_from_suffix reads a Self from the last size_of::<Self>()
bytes of bytes. If bytes.len() < size_of::<Self>(), it returns
None.
sourcefn new_zeroed() -> Selfwhere
Self: Sized,
fn new_zeroed() -> Selfwhere
Self: Sized,
Creates an instance of Self from zeroed bytes.
sourcefn new_box_zeroed() -> Box<Self>where
Self: Sized,
fn new_box_zeroed() -> Box<Self>where
Self: Sized,
Creates a Box<Self> from zeroed bytes.
This function is useful for allocating large values on the heap and
zero-initializing them, without ever creating a temporary instance of
Self on the stack. For example, <[u8; 1048576]>::new_box_zeroed()
will allocate [u8; 1048576] directly on the heap; it does not require
storing [u8; 1048576] in a temporary variable on the stack.
On systems that use a heap implementation that supports allocating from
pre-zeroed memory, using new_box_zeroed (or related functions) may
have performance benefits.
Note that Box<Self> can be converted to Arc<Self> and other
container types without reallocation.
Panics
Panics if allocation of size_of::<Self>() bytes fails.
sourcefn new_box_slice_zeroed(len: usize) -> Box<[Self]>where
Self: Sized,
fn new_box_slice_zeroed(len: usize) -> Box<[Self]>where
Self: Sized,
Creates a Box<[Self]> (a boxed slice) from zeroed bytes.
This function is useful for allocating large values of [Self] on the
heap and zero-initializing them, without ever creating a temporary
instance of [Self; _] on the stack. For example,
u8::new_box_slice_zeroed(1048576) will allocate the slice directly on
the heap; it does not require storing the slice on the stack.
On systems that use a heap implementation that supports allocating from
pre-zeroed memory, using new_box_slice_zeroed may have performance
benefits.
If Self is a zero-sized type, then this function will return a
Box<[Self]> that has the correct len. Such a box cannot contain any
actual information, but its len() property will report the correct
value.
Panics
- Panics if
size_of::<Self>() * lenoverflows. - Panics if allocation of
size_of::<Self>() * lenbytes fails.
sourcefn new_vec_zeroed(len: usize) -> Vec<Self>where
Self: Sized,
fn new_vec_zeroed(len: usize) -> Vec<Self>where
Self: Sized,
Creates a Vec<Self> from zeroed bytes.
This function is useful for allocating large values of Vecs and
zero-initializing them, without ever creating a temporary instance of
[Self; _] (or many temporary instances of Self) on the stack. For
example, u8::new_vec_zeroed(1048576) will allocate directly on the
heap; it does not require storing intermediate values on the stack.
On systems that use a heap implementation that supports allocating from
pre-zeroed memory, using new_vec_zeroed may have performance benefits.
If Self is a zero-sized type, then this function will return a
Vec<Self> that has the correct len. Such a Vec cannot contain any
actual information, but its len() property will report the correct
value.
Panics
- Panics if
size_of::<Self>() * lenoverflows. - Panics if allocation of
size_of::<Self>() * lenbytes fails.