Expand description
§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.
§Features
This crate exposes the following feature flags. The default is NO features.
zeroize
- ImplementsZeroize
forArray<T: Zeroize, U>
§License
Licensed under either of:
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.
§Usage
The two core types in this crate are as follows:
Array<T, U>
: wrapper for[T; N]
whereU
is anArraySize
provided bytypenum
whose associatedArraySize::ArrayType<T>
determines the inner array size.ArrayN<T, N>
: type alias forArray
which is const generic aroundconst N: usize
. This provides a linkage between const generics andtypenum
.
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]);
§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 and
easier-to-audit.
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.
Migrating should hopefully be relatively painless with the following
substitutions in your .rs
files:
- Replace
generic_array
withhybrid_array
- Replace
GenericArray<T, U>
withArray<T, U>
- Replace
ArrayLength<T>
withArraySize
- Replace usages of the
Concat
andSplit
traits withArray::concat
andArray::split
- Replace
<U as ArrayLength<T>>::ArrayType
with<U as ArraySize>::ArrayType<T>
- Replace usages of the
arr![N; A, B, C]
macro withArray([A, B, C])
If you have any questions, please start a discussion.
Re-exports§
pub use typenum;
Modules§
- Supported array sizes:
typenum::Unsigned
types with anArraySize
impl.
Structs§
Array
is a newtype for an inner[T; N]
array whereN
is determined by a genericArraySize
parameter, which is a marker trait for a numeric value determined by ZSTs that impl thetypenum::Unsigned
trait.- Couldn’t construct an array from an iterator because the number of items in the iterator didn’t match the array size.
Traits§
- Associates an
ArraySize
with a given type.