mem_cmp/lib.rs
1//! Safe memory comparison between types.
2//!
3//! Types found in this crate serve as safe wrappers around `memcmp` operations.
4//!
5//! # Usage
6//!
7//! This crate is available [on crates.io][crate] and can be used by adding the
8//! following to your project's `Cargo.toml`:
9//!
10//! ```toml
11//! [dependencies]
12//! mem_cmp = "0.1.4"
13//! ```
14//!
15//! and this to your crate root:
16//!
17//! ```
18//! extern crate mem_cmp;
19//! # fn main() {}
20//! ```
21//!
22//! # Comparing Memory
23//!
24//! The [`MemOrd`] trait provides convenience around the result of a `memcmp`
25//! call by returning an `Ordering`.
26//!
27//! If the only thing that matters is equality, [`MemEq`] is also available.
28//!
29//! ```
30//! use mem_cmp::*;
31//!
32//! let a = [0u8; 256];
33//! let b = [0u32; 64];
34//! let c = [4u32; 64];
35//!
36//! assert!(a.mem_eq(&b));
37//! assert!(a.mem_neq(&c));
38//!
39//! // Also works with types of different sizes:
40//! assert!(a.mem_neq(&42));
41//! ```
42//!
43//! # Safety
44//!
45//! Generally, comparing memory directly is safe. However, there are cases where
46//! undefined behavior may be encountered.
47//!
48//! - **Types with padding:**
49//!
50//! One such case is with types where the inner values are padded for
51//! alignment. Such a type would be `(u8, u32)`. It has an alignment of 4
52//! bytes, resulting in 3 bytes of padding between the first value and the
53//! second. It's up to the compiler to decide what the byte values are for
54//! the padding.
55//!
56//! [crate]: https://crates.io/crates/mem_cmp
57//! [`MemEq`]: trait.MemEq.html
58//! [`MemOrd`]: trait.MemOrd.html
59
60#![no_std]
61#![cfg_attr(feature = "simd", feature(repr_simd))]
62#![cfg_attr(feature = "specialization", feature(specialization))]
63
64#[cfg(feature = "simd")]
65extern crate simd;
66
67mod ext;
68mod mem_eq;
69mod mem_ord;
70mod mem_ordered;
71
72pub use mem_eq::*;
73pub use mem_ord::*;
74pub use mem_ordered::*;