Crate hybrid_array 

RustCrypto: Hybrid Const Generic / Typenum Arrays

Hybrid array type combining const generics with the expressiveness of typenum-based constraints, providing an alternative to generic-array and a incremental transition path to const generics.

About

This crate uses typenum to enable the following features which aren’t yet possible with the stable implementation of const generics:

• #60551: Associated constants in traits can not be used in const generics
• #76560: Complex generic constants: feature(generic_const_exprs)

Internally the crate is built on const generics and provides traits which make it possible to convert between const generic types and typenum types.

Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Features

This crate exposes the following feature flags. The default is NO features.

• bytemuck: impls the Pod and Zeroable traits
• serde: impls the Deserialize and Serialize traits for Array
• zeroize: impls Zeroize for Array<T: Zeroize, U>

Usage

The two core types in this crate are as follows:

• Array<T, U>: wrapper for [T; N] where U is an ArraySize provided by typenum whose associated ArraySize::ArrayType<T> determines the inner array size.
• ArrayN<T, N>: type alias for Array which is const generic around const N: usize. This provides a linkage between const generics and typenum.

The Array type has an inner pub [T; N] field, which means writing a literal can be expressed as follows:

use hybrid_array::{Array, sizes::U4};

let arr: Array<u8, U4> = Array([1, 2, 3, 4]);

About typenum

The typenum crate provides a type-level implementation of numbers and arithmetic operations.

While typenum can be used to express arbitrary integers using the type system, the hybrid-array crate is limited to the array sizes in the sizes module, which have names like U0, U1, U2, U3, etc. All supported sizes will have an impl of ArraySize, which is the trait providing linkage between typenum-based types and core arrays / const generics.

ArraySize bounds on the typenum::Unsigned trait, which can be used to obtain integer sizes of arrays via associated constants. For example, to obtain the size of an ArraySize as a usize, use the associated typenum::Unsigned::USIZE constant.

AsArrayRef and AsArrayMut traits

These traits simplify obtaining references to Array and are impl’d for both Array and [T; N]. They’re analogous to traits like AsRef and AsMut.

They make it possible to write code which uses [T; N] or &[T; N] in the external facing API which can obtain references to &Array and call other functions which accept such references, without the caller having to use Array in their code and while still supporting generic sizes.

For more information and a code example, see AsArrayRef.

Relationship with generic-array

hybrid-array is directly inspired by the generic-array crate.

However, where generic-array predates const generics and uses a core which is built on unsafe code, hybrid-array’s core implementation is built on safe code and const generic implementations. This allows the inner [T; N] field of an Array to be pub as noted above, and in general for the implementation to be significantly simpler, easier-to-audit, and with significantly less use of unsafe.

The only places hybrid-array uses unsafe are where it is absolutely necessary, primarily for reference conversions between Array<T, U> and [T; N], and also to provide features which are not yet stable in core/std, such as Array::try_from_fn.

Migrating from generic-array

NOTE: this guide assumes a migration from generic-array v0.14

hybrid-array has been designed to largely be a drop-in replacement for generic-array, albeit with a public inner array type and significantly less unsafe code.

The bulk of the migration work can be accomplished by making the following find/replace-style substitutions in your .rs files:

• Replace generic_array with hybrid_array
• Replace GenericArray<T, U> with Array<T, U>
• Replace ArrayLength<T> with ArraySize
• Replace usages of the Concat and Split traits with Array::concat and Array::split
• Replace <U as ArrayLength<T>>::ArrayType with <U as ArraySize>::ArrayType<T>
• Replace usages of the arr![N; A, B, C] macro with Array([A, B, C])

If you have any questions, please start a discussion.

Re-exports

pub use typenum;

Modules

sizes

Supported array sizes: typenum::Unsigned types with an ArraySize impl.

Structs

Array

Array is a newtype for an inner [T; N] array where N is determined by a generic ArraySize parameter, which is a marker trait for a numeric value determined by ZSTs that impl the typenum::Unsigned trait.

TryFromIteratorError

Couldn’t construct an array from an iterator because the number of items in the iterator didn’t match the array size.

Traits

ArraySize

Trait which associates a usize size and ArrayType with a typenum-provided Unsigned integer.

AsArrayMut

Obtain a &mut Array reference for a given type.

AsArrayRef

Obtain an &Array reference for a given type.

AssocArraySize

Associates an ArraySize with a given type. Can be used to accept [T; N] const generic arguments and convert to Array internally.

Type Aliases

ArrayN

Type alias for Array which is const generic around a size N, ala [T; N].