Crate maligned

Expand description

A library for getting aligned vectors, slices, and arrays of bytes or any other type

The A* structs are aligned as indicated and hold a single array of bytes of the same size. These implement the Alignment trait that can be used for always aligned byte arrays for faster memory copies or copies by hardware. The arrays are accessible as slices using as_bytes() or as_bytes_mut() or by dereferencing the struct.

let alignment_256 = A256::default();

assert_eq!(std::mem::size_of::<A256>(), std::mem::size_of_val(alignment_256.as_bytes()));
assert_eq!(alignment_256.as_bytes().as_ptr() as usize % std::mem::size_of::<A256>(), 0);

If you need more than a single Alignment of bytes you can create a vector of them and that can be converted into a normal byte slice that always has the first byte aligned.

let mut v = vec![A512::default(); 100];
assert_eq!(v.as_bytes().len(), std::mem::size_of::<A512>() * 100);
assert_eq!(v.as_bytes().as_ptr() as usize % std::mem::align_of::<A512>(), 0);

v.as_bytes_mut()[512] = 42;
assert_eq!(v[1][0], 42);

There is also a wrapper Aligned that aligns any type to a specified alignment

// aligned() is an alias for Aligned::new()
let a: Aligned<A32, [u8; 24]> = aligned([0; 24]);
assert_eq!(std::mem::align_of_val(&a), 32);
assert_eq!(&*a as *const u8 as usize % std::mem::align_of::<A32>(), 0);

If the alloc feature is enabled (it is by default) then there are a few more functions available. align_first returns an empty Vec with a capacity of at least capacity bytes. Two type parameters are currently required, though the first can be set to _, because of the current interaction between impl traits and generics.

let v: Vec<u8> = align_first::<u8, A256>(1009);
assert_eq!(v.as_ptr() as usize % 256, 0);
assert_eq!(v.capacity(), 1009);

align_first_boxed, align_first_boxed_default, and align_first_boxed_cloned all return a Box<[T]> with the first element aligned to at least Alignment bytes.

// 3 type parameters. The last one should always be _ until impl traits and generics interact better
let boxed: Box<[Option<u128>]> = align_first_boxed::<_, A512, _>(101, |_|Some(42));
let defaulted: Box<[Option<u128>]> = align_first_boxed_default::<_, A128>(101);
let cloned: Box<[Option<u128>]> = align_first_boxed_cloned::<_, Bit512>(101, Some(42));

assert_eq!(&*boxed, &vec![Some(42); 101][..]);
assert_eq!(&boxed, &cloned);
assert_eq!(boxed.len(), 101);
assert_eq!(defaulted.len(), 101);
assert_eq!(cloned.len(), 101);
assert_eq!(&*defaulted, &vec![None; 101][..]);

Modules§

prelude: allow * imports

Structs§

A2: Struct representing an alignment of 2
A4: Struct representing an alignment of 4
A8: Struct representing an alignment of 8
A16: Struct representing an alignment of 16
A32: Struct representing an alignment of 32
A64: Struct representing an alignment of 64
A128: Struct representing an alignment of 128
A256: Struct representing an alignment of 256
A512: Struct representing an alignment of 512
A1024: Struct representing an alignment of 1024
A2048: Struct representing an alignment of 2048
A4096: Struct representing an alignment of 4096
A8192: Struct representing an alignment of 8192
A16384: Struct representing an alignment of 16384
A32768: Struct representing an alignment of 32768
A65536: Struct representing an alignment of 65536
A131072: Struct representing an alignment of 131_072
Aligned: Wrapper type that aligns T to at least Alignment It adds no size to the layout of the struct if the size is a multiple of the alignment, otherwise the size is rounded up to the next multiple of the alignment
FromByteSliceError: Representation of failure to convert from a byte slice to some alignment type.

Traits§

Alignment: Marker trait used for bounds. All structs that implement this trait have their size and alignment equal.
AsBytes: Trait that allows reinterpretation of a struct as bytes. This is unsafe since the returned slice must always have a length equal to the size of the struct and because every bit pattern within the structs size must be valid.
AsBytesMut: Trait that allows reinterpretation of a mutable struct as mutable bytes. This is unsafe since the returned slice must always have a length equal to the size of the struct and because every bit pattern within the structs size must be valid.

Functions§

align_first: Aligns the first element in a Vec<T> to A. If the alignment of A is less than the alignment of T then a Vec<T> with capacity t_capacity is returned. This method is safe because structs are always aligned to a power of two so aligning the first item in a Vec<T> to a higher alignment will always be aligned correctly.
align_first_boxed: Aligns types and initializes memory to the return value provided by the closure. Since boxed slices can never re-allocate the first item will always be aligned.
align_first_boxed_cloned: Aligns types and initializes all values to clones of initial then returns a boxed slice. Since boxed slices can never re-allocate the first item will always be aligned.
align_first_boxed_default: Aligns types and initializes memory to default then returns a boxed slice. Since boxed slices can never re-allocate the first item will always be aligned.
aligned: Convenience function for creating a new Aligned Because of the current interaction between generics and impl arguments the function requires both types to be given, though the second one can be given the default _ To align a byte array to a 256 bit boundary

Type Aliases§