[−][src]Crate maligned

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 Definitions

A1k	Type alias for A1024 in kilobytes
A2k	Type alias for A2048 in kilobytes
A4k	Type alias for A4096 in kilobytes
A8k	Type alias for A8192 in kilobytes
A16k	Type alias for A16384 in kilobytes
A32k	Type alias for A32768 in kilobytes
A64k	Type alias for A65536 in kilobytes
A128K	Type alias for A131072 in kilobytes
Bit16	Type alias for A2 in bits
Bit32	Type alias for A4 in bits
Bit64	Type alias for A8 in bits
Bit128	Type alias for A16 in bits
Bit256	Type alias for A32 in bits
Bit512	Type alias for A64 in bits
Bit1024	Type alias for A128 in bits
Bit2048	Type alias for A256 in bits
Bit4096	Type alias for A512 in bits
Bit8192	Type alias for A1024 in bits
Bit16384	Type alias for A2048 in bits
Bit32768	Type alias for A4096 in bits
Bit65536	Type alias for A8192 in bits
Bit131072	Type alias for A16384 in bits
Bit262144	Type alias for A32768 in bits
Bit524288	Type alias for A65536 in bits
Bit1048576	Type alias for A131072 in bits