type_vec/
lib.rs

1//! The crate demonstrates a type-safe vector with type-level length.
2//!
3//! ## The type-safe vector type
4//! The vector type has a type-level length, which length can be either dynamic or static.
5//! That is, the length can be given in compile time or is only known in runtime.
6//!
7//! ```rust
8//! use type_vec::{Vect, Dyn};
9//! use typenum::consts::*; // imports U0
10//!
11//! // vector with static length
12//! let vec = Vect::<usize, U0>::new();
13//!
14//! // vector with dynamic length
15//! let vec = Vect::<usize, Dyn>::new();
16//! ```
17//!
18//! ## Type-inferred and type-checked vector operations
19//! The vector supports common operations, such as `push`, `pop` and `insert`.
20//! The output length is inferred in compile time on each vector operation.
21//! Thus, you can gain the benefit of type safety to avoid common errors.
22//!
23//! ```rust
24//! use type_vec::Vect;
25//! use typenum::consts::*;
26//!
27//! let vec = Vect::<usize, U0>::new();
28//! let vec: Vect<usize, U1> = vec.push(3);
29//! let vec: Vect<usize, U2> = vec.push(1);
30//!
31//! // This line does not compile due to incorrect output length assumption.
32//! /* let vec: Vect<usize, U2> = vec.push(1); */
33//!
34//! // You can omit the type annotation and leave it to compiler
35//! let (vec, item) = vec.pop();
36//! let (vec, item) = vec.pop();
37//!
38//! // This line causes compile error because we cannot pop an empty vector.
39//! /* let vec = vec.pop(); */
40//! ```
41//!
42//! ## Zero-abstraction and efficient implementation
43//! The design promises zero-abstraction. Whenever the length is known in compile time,
44//! it picks the more efficient implementation.
45//! Let's see the element accessing using [get](Vect::get). If the index is static,
46//! The index is checked against the length in compile time, and returns the element directly
47//! if it compiles. Otherwise, it returns an `Option<&T>` like usual [Vec].
48//!
49//! ```rust
50//! use type_vec::Vect;
51//! use typenum::consts::*;
52//!
53//! let vec = Vect::<usize, U0>::new();
54//! let vec: Vect<usize, U1> = vec.push(3);
55//! let vec: Vect<usize, U2> = vec.push(1);
56//! let vec: Vect<usize, U3> = vec.push(4);
57//!
58//! // get element by static index
59//! // the index is checked in compile time and returns the element directly
60//! let elem = vec.get(U1::new());
61//! assert_eq!(elem, &1);
62//!
63//! // get element by dynamic index
64//! // it returns an `Option` depending on the index
65//! let elem = vec.get(1);
66//! assert_eq!(elem, Some(&1));
67//! ```
68//!
69//! ## How it works
70//! The construction of the vector type heavily relies on the
71//! [TYP type-level programming langauge](https://github.com/jerry73204/typ).
72//! It enables complex type-level computation done by simple Rusty syntax.
73//! Those interested can read the [TYP book](https://github.com/jerry73204/typ-book/).
74
75pub(crate) mod common;
76pub mod impls;
77pub mod size;
78pub mod vect;
79
80pub use size::{Dyn, Size};
81pub use vect::Vect;
type_vec/lib.rs

type_vec/
lib.rs
