# Crate fixed_capacity_vec

source ·## Expand description

`FixedCapacityVec`

- like a `Vec`

but with capacity fixed at compile-time

`FixedCapacityVec`

is a simple special-purpose data structure.
One use case is applications which want to incrementally construct
a nontrivial fixed-size table.

### Relationship to types from `std`

All of the following types store only the actual buffer on the heap, and they are interconvertible without copying the data.

Type | Size and representation (as eg on stack) | Full? | Mutability |
---|---|---|---|

`Vec` | 3 words: pointer, length, capacity | maybe | indefinitely appendable |

`Box<[T]>` | 2 words: pointer, length = capacity | always | length fixed at runtime |

`FixedCapacityVec<T, N>` | 2 words: pointer, length | maybe | appendable, but capacity fixed at compile time |

`Box<[T; N]>` | 1 word: pointer | always | length fixed at compile time |

```
Vec<T> HEAP Box<[T]> HEAP
+----------+ +------------+ +----------+ +----------+
| pointer -----> | T | | pointer -----> | T |
| length | | T ... | | length | | T ... |
| capacity | +--length----+ +----------+ +--length--+
+----------+ | (spare) |
+--capacity--+
FixedCapacityVec<T, N> HEAP Box<[T; N]> HEAP
+----------+ +-------------+ +----------+ +---------+
| pointer -----> | T | | pointer -----> | T |
| length | | T ... | +----------+ | T ... |
+----------+ |--length-----| +--N------+
| (spare) |
+--N----------|
```

### Relationship to some other crates’ vec-like types

`FixedCapacityVec`

serves a different purpose to
`ArrayVec`

and
`SmallVec`

.

The data for a `FixedCapacityVec`

always lives on the heap.

The advantage of a `FixedCapacityVec`

over `Vec`

is that the size
of the `FixedCapacityVec`

itself is small,
and that the capacity does not need to be represented or looked up.
And it can be converted very cheaply to a boxed array,
or to a `Vec`

or boxed slice,
without copying.

`ArrayVec`

is also a fixed-capacity vec-like structure.
But the data for an `ArrayVec`

lives next to the metadata.
So to convert a full `ArrayVec`

to a boxed array,
the data must be copied.
Even if it was a full `Box<ArrayVec<..>>`

,
at the very least, its allocation would have to be shrunk.
One of `ArrayVec`

’s use cases is its ability to
incrementally construct (usually short) arrays without heap allocation.

`SmallVec`

’s benefit is that a small amount of data can be stored on the stack,
not that the `SmallVec`

itself is particularly small;
indeed, both the `ArrayVec`

and `SmallVec`

are big enough for `N`

items `T`

.

```
ArrayVec<T, N> SmallVec<[T; N]> SmallVec<[T; N]>
+-----------+ +--------------+ +---------------+ HEAP
| T | | length <= N | | capacity > N | +------------+
| T ... | +--0-----------+ | pointer ----------> | T |
+--length---+ | T | OR | length | | T ... |
| (uninit) | | T ... | +---------------+ +--length----+
+--N--------+ |--length------| | (unused) | | (uninit) |
| length | | (spare) | | | +--capacity--+
+-----------+ +--N-----------+ +---------------+
```

## Structs

- Like
`Vec`

with a capacity fixed at compile time - Error returned by
`try_push_or_discard()`