Crate plain [−] [src]
A small Rust library that allows users to reinterpret data of certain types safely.
This crate provides an unsafe trait Plain
, which the user
of the crate uses to mark types for which operations of this library are safe.
See Plain
for the contractual obligation.
Other than that, everything else in this crate is perfectly safe to use as long
as the Plain
trait is not implemented on inadmissible types (similar to how
Send
and Sync
in the standard library work).
Examples
To start using the crate, simply do extern crate plain;
.
If you want your plain types to have methods from this crate, also include use plain.Plain;
.
Then it's just a matter of marking the right types and using them.
extern crate plain; use plain::Plain; #[repr(C)] #[derive(Default)] struct ELF64Header { pub e_ident: [u8; 16], pub e_type: u16, pub e_machine: u16, pub e_version: u32, pub e_entry: u64, pub e_phoff: u64, pub e_shoff: u64, pub e_flags: u32, pub e_ehsize: u16, pub e_phentsize: u16, pub e_phnum: u16, pub e_shentsize: u16, pub e_shnum: u16, pub e_shstrndx: u16, } // SAFE: ELF64Header satisfies all the requirements of `Plain`. unsafe impl Plain for ELF64Header {} fn reinterpret_buffer(buf: &[u8]) -> &ELF64Header { match plain::from_bytes(buf) { Err(_) => panic!("The buffer is either too short or not aligned!"), Ok(elfref) => elfref, } } fn copy_from_buffer(buf: &[u8]) -> ELF64Header { let mut h = ELF64Header::default(); h.as_mut_bytes().copy_from_slice(buf); h } #[repr(C)] struct ArrayEntry { pub name: [u8; 64], pub tag: u32, pub score: u32, } // SAFE: ArrayEntry satisfies all the requirements of `Plain`. unsafe impl Plain for ArrayEntry {} fn array_from_bytes(buf: &[u8]) -> &[ArrayEntry] { // NOTE: length is not a concern here, // since slice_from_bytes() can return empty slice. match plain::slice_from_bytes(buf) { Err(_) => panic!("The buffer is not aligned!"), Ok(arr) => arr, } }
Comparison to pod
pod
is another crate created to help working with plain data.
The major difference between pod
and plain
is scope.
plain
currently provides only a few functions (+method wrappers) and its implementation
involves very few lines of unsafe code. It can be used in no_std
code. Also, it doesn't
deal with endianness in any way,
so it is only suitable for certain kinds of low-level work.
pod
, on the other hand, provides a wide arsenal
of various methods, most of which may be unnecessary for a given use case.
It has dependencies on std
as well as other crates, but among other things
it provides tools to handle endianness properly.
In short, plain
is much, much plainer...
Enums
Error |
Traits
Plain |
A trait for plain reinterpretable data. |
Functions
as_bytes |
Safely converts a reference to an immutable byte slice of appropriate length. |
as_mut_bytes |
Safely converts a reference to a mutable byte slice of appropriate length. |
from_bytes |
Safely converts a byte slice to a reference. |
from_mut_bytes |
See |
slice_from_bytes |
Similar to |
slice_from_bytes_len |
Same as |
slice_from_mut_bytes |
See |
slice_from_mut_bytes_len |