# type-vec: a type-safe vector with type-level length in Rust

## Usage

Include the crate in your `Cargo.toml`.

```toml
type-vec = "0.1"
```

## Features

### The type-safe vector type

The vector type has a type-level length, which length can be either dynamic or static.
That is, the length can be given in compile time or is only known in runtime.

```rust
use type_vec::{Vect, Dyn};
use typenum::consts::*; // imports U0

// vector with static length
let vec = Vect::<usize, U0>::new();

// vector with dynamic length
let vec = Vect::<usize, Dyn>::new();
```

### Type-inferred and type-checked vector operations

The vector supports common operations, such as `push`, `pop` and `insert`.
The output length is inferred in compile time on each vector operation.
Thus, you can gain the benefit of type safety to avoid common errors.

```rust
use type_vec::Vect;
use typenum::consts::*;

let vec = Vect::<usize, U0>::new();
let vec: Vect<usize, U1> = vec.push(3);
let vec: Vect<usize, U2> = vec.push(1);

// This line does not compile due to incorrect output length assumption.
/* let vec: Vect<usize, U2> = vec.push(1); */

// You can omit the type annotation and leave it to compiler
let (vec, item) = vec.pop();
let (vec, item) = vec.pop();

// This line causes compile error because we cannot pop an empty vector.
/* let vec = vec.pop(); */
```

### Zero-abstraction and efficient implementation

The design promises zero-abstraction. Whenever the length is known in compile time,
it picks the more efficient implementation.
Let's see the element accessing using [get](Vect::get). If the index is static,
The index is checked against the length in compile time, and returns the element directly
if it compiles. Otherwise, it returns an `Option<&T>` like usual [Vec].

```rust
use type_vec::Vect;
use typenum::consts::*;

let vec = Vect::<usize, U0>::new();
let vec: Vect<usize, U1> = vec.push(3);
let vec: Vect<usize, U2> = vec.push(1);
let vec: Vect<usize, U3> = vec.push(4);

// get element by static index
// the index is checked in compile time and returns the element directly
let elem = vec.get(U1::new());
assert_eq!(elem, &1);

// get element by dynamic index
// it returns an `Option` depending on the index
let elem = vec.get(1);
assert_eq!(elem, Some(&1));
```

## How it works
The construction of the vector type heavily relies on the
[TYP type-level programming langauge](https://github.com/jerry73204/typ).
It enables complex type-level computation done by simple Rusty syntax.
Those interested can read the [TYP book](https://github.com/jerry73204/typ-book/).

## License

MIT license. See the [LICENSE](LICENSE.txt) file.