Source code
Revision control
Copy as Markdown
Other Tools
//! A small Rust library that allows users to interpret arrays of bytes
//! as certain kinds of structures safely.
//!
//! This crate provides an unsafe trait [`Plain`](trait.Plain.html), which the user
//! of the crate uses to mark types for which operations of this library are safe.
//! See [`Plain`](trait.Plain.html) 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).
//!
//! # Purpose
//!
//! In low level systems development, it is sometimes necessary to
//! interpret locations in memory as data structures. Functions of
//! this crate serve to avoid pitfalls associated with that, without
//! having to resort to big, full-featured (de)serialization libraries.
//!
//! On the other hand, this crate contains no provisions when it comes
//! to handling differences in encoding and byte ordering between
//! platforms. As such, it is entirely unsuitable for processing
//! external data such as file contents or network packets.
//!
//! # 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;
//! use std::mem;
//!
//!
//! #[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 {}
//!
//! impl ELF64Header {
//! fn from_bytes(buf: &[u8]) -> &ELF64Header {
//! plain::from_bytes(buf).expect("The buffer is either too short or not aligned!")
//! }
//!
//! fn from_mut_bytes(buf: &mut [u8]) -> &mut ELF64Header {
//! plain::from_mut_bytes(buf).expect("The buffer is either too short or not aligned!")
//! }
//!
//! fn copy_from_bytes(buf: &[u8]) -> ELF64Header {
//! let mut h = ELF64Header::default();
//! h.copy_from_bytes(buf).expect("The buffer is too short!");
//! h
//! }
//! }
//!
//! # fn process_elf(elf: &ELF64Header) {}
//!
//! // Conditional copying for ultimate hackery.
//! fn opportunistic_elf_processing(buf: &[u8]) {
//! if plain::is_aligned::<ELF64Header>(buf) {
//! // No copy necessary.
//! let elf_ref = ELF64Header::from_bytes(buf);
//! process_elf(elf_ref);
//! } else {
//! // Not aligned properly, copy to stack first.
//! let elf = ELF64Header::copy_from_bytes(buf);
//! process_elf(&elf);
//! }
//! }
//!
//! #[repr(C)]
//! #[derive(Default, Copy, Clone)]
//! struct ArrayEntry {
//! pub name: [u8; 32],
//! 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,
//! }
//! }
//!
//! fn array_from_unaligned_bytes(buf: &[u8]) -> Vec<ArrayEntry> {
//! let length = buf.len() / mem::size_of::<ArrayEntry>();
//! let mut result = vec![ArrayEntry::default(); length];
//! (&mut result).copy_from_bytes(buf).expect("Cannot fail here.");
//! result
//! }
//!
//! # fn main() {}
//!
//! ```
//!
//!
//! 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
//! 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_...
#![no_std]
mod error;
pub use error::Error;
mod plain;
pub use plain::Plain;
mod methods;
pub use methods::{as_bytes, as_mut_bytes, copy_from_bytes, from_bytes, from_mut_bytes, is_aligned,
slice_from_bytes, slice_from_bytes_len, slice_from_mut_bytes,
slice_from_mut_bytes_len};
#[cfg(test)]
#[macro_use]
extern crate std;
#[cfg(test)]
mod tests;