# Encoding

> UForm for Rust

One verb per input form, each spelled as in C, and each taking its inputs, the `Outputs` to keep, a config, and last the arena:

- `text_encode(texts, ..)` takes UTF-8 texts, a byte per token, since models are tokenizer-free.
- `image_encode(files, ..)` takes JPEG, PNG or WebP files.
- `image_encode_pixels(pixels, heights, widths, ..)` takes interleaved 8-bit RGB, `heights[i]` rows of `widths[i]` pixels per item.
- `video_encode(files, ..)` takes MP4 or WebM clips.
- `audio_encode(files, ..)` takes WAV, FLAC, MP3 or Opus recordings.
- `audio_encode_samples(samples, sample_rate, ..)` takes mono `f32` samples.

A batch is a slice, array or `Vec` of separate items, `&str`, `String`, `&[u8]` or `Vec<u8>`, or `&[f32]` and `Vec<f32>` for samples, gathered into one tape with one copy.
A `(data, offsets)` pair, the data and `count + 1` offsets, is lent to the library as a tape without a copy, once the binding checks the offsets stay inside the data:

```rust
let tape = (b"first documentthe second".as_slice(), [0usize, 14, 24]);
let encoded = model.text_encode(tape, Outputs::STATES, Scalar::BF16, &mut arena)?;
let states = encoded.states.expect("STATES were asked for");
let offsets = states.offsets()?;                              // item `i` spans rows `offsets[i]` up to `offsets[i + 1]`
let second = states.item(1)?;                                 // the rows of one item, as `Rows`
```

`Outputs::EMBEDDINGS` is the default, `|` joins it with `Outputs::STATES` and `Outputs::TOKEN_VECTORS`, and a surface left out answers `None` and costs nothing past the final norm.
Token vectors are the token head's unit rows, one per state, which late-interaction rerankers score; a model without the head answers `Status::Unsupported`.
Every bare `Scalar` converts into the verb's config, the scalar every output lands as; the config's other fields reach the knobs:

```rust
let mut stats = TextEncodeStats::default();
let mut handler = |completed, total| if completed * 2 < total { ControlFlow::Continue(()) } else { ControlFlow::Break(()) };
let config = TextEncodeConfig { stats: Some(&mut stats), progress: Some(&mut handler), ..TextEncodeConfig::from(Scalar::F32) };
let encoded = model.text_encode(&texts, Outputs::EMBEDDINGS, config, &mut arena);
```

`Rows` reports its `count`, `columns`, `stride` and `scalar`, and reads as bytes through `as_bytes` or as values through `values::<f32>()`, refused when the rows hold another scalar type.
`RowsTape` adds the `offsets` and an `item` per input.
A handler answering `ControlFlow::Break` stops the call, which fails with `Status::Cancelled` and publishes nothing.

`text_choose(texts, choices, ..)` scores each item's legal choices, one byte each, through one forward, and answers a `Tape` of one `f32` probability per choice that sums to one per item:

```rust
let config = TextChooseConfig { temperature_groups: &[0, 1], ..TextChooseConfig::default() };
let probabilities = model.text_choose(&["keep this candidate?", "expand which neighbour?"], &["yn", "ABCD"], config, &mut arena)?;
let expand: &[f32] = probabilities.item(1)?;                  // the probabilities of 'A' through 'D'
```

Each group is a question type below the model's `choice_temperature_groups`, and a model without the byte decoder answers `Status::Unsupported`.

`use uform::AudioEncode;`

`use uform::AudioEncodeConfig;`

`use uform::AudioEncodeSamples;`

`use uform::AudioEncodeSamplesConfig;`

`use uform::AudioEncodeStats;`

`use uform::EncodeVerbs;`

`use uform::Encoded;`

`use uform::ImageEncode;`

`use uform::ImageEncodeConfig;`

`use uform::ImageEncodePixels;`

`use uform::ImageEncodePixelsConfig;`

`use uform::ImageEncodeStats;`

`use uform::Outputs;`

`use uform::TextEncode;`

`use uform::TextEncodeConfig;`

`use uform::TextEncodeStats;`

`use uform::VideoEncode;`

`use uform::VideoEncodeConfig;`

`use uform::VideoEncodeStats;`

`use uform::Element;`

`use uform::Rows;`

`use uform::RowsTape;`

`use uform::Scalar;`

`use uform::Tape;`

## AudioEncode

An audio forward over encoded recordings; see [`EncodeVerbs::audio_encode`](#audio_encode).

```rust
pub struct AudioEncode<'config, 'arena, Recordings>
```

Calls `uform_audio_encode`.

## AudioEncodeConfig

The scalar and the knobs of [`EncodeVerbs::audio_encode`](#audio_encode); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct AudioEncodeConfig<'config>
```

Mirrors `uform_audio_encode_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut AudioEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## AudioEncodeSamples

An audio forward over decoded samples; see [`EncodeVerbs::audio_encode_samples`](#audio_encode_samples).

```rust
pub struct AudioEncodeSamples<'config, 'arena, Samples>
```

Calls `uform_audio_encode_samples`.

## AudioEncodeSamplesConfig

The scalar and the knobs of [`EncodeVerbs::audio_encode_samples`](#audio_encode_samples); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct AudioEncodeSamplesConfig<'config>
```

Mirrors `uform_audio_encode_samples_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut AudioEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## AudioEncodeStats

What an audio call reports beside its outputs, overwritten by the call.

```rust
pub struct AudioEncodeStats
```

Mirrors `uform_audio_encode_stats_t`.

- `truncated` `usize`: Items cut at the model's context in frames.
- `tokens` `usize`: Frames the call encoded, after truncation.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`

## EncodeVerbs

Every encode verb, written once for every receiver: `&Model` blocks on the calling thread, and the [`On`](https://www.unum.cloud/docs/uform/rust/receivers-and-deferred-calls.md#On) that [`Model::on`](https://www.unum.cloud/docs/uform/rust/training.md#on) or [`Model::deferred`](https://www.unum.cloud/docs/uform/rust/training.md#deferred) makes runs on an executor.

```rust
pub trait EncodeVerbs<'model>: ModelVerbs<'model>
```

Every verb takes its inputs, the [`Outputs`](#Outputs) to keep, a config every bare [`Scalar`](#Scalar)
converts into, and last the [`Arena`](https://www.unum.cloud/docs/uform/rust/arenas.md#Arena) its [`Encoded`](#Encoded) result borrows. A blocking receiver
answers what the call produced; a deferring one answers a [`Deferred`](https://www.unum.cloud/docs/uform/rust/errors.md#Deferred) and
takes owned inputs.

Rust-only; implemented for every receiver of [`ModelVerbs`](https://www.unum.cloud/docs/uform/rust/models.md#ModelVerbs).

Implementors: - `impl<'model, Receiver: [ModelVerbs](https://www.unum.cloud/docs/uform/rust/models.md#ModelVerbs)<'model>> [EncodeVerbs](#EncodeVerbs)<'model> for Receiver`

## text_encode

Encodes UTF-8 texts through one forward, a token per byte.

```rust
fn text_encode<'config, 'arena, Texts: TapeView<u8>>(
    self,
    texts: Texts,
    outputs: Outputs,
    config: impl Into<TextEncodeConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, TextEncode<'config, 'arena, Texts>>
where
    Self::Completion: Accepts<Texts> + Accepts<TextEncodeConfig<'config>>,
```

Calls `uform_text_encode`.

## text_choose

Scores each item's legal choices through one forward: `texts` are UTF-8 states, each ending where its choice goes, and `choices` holds each item's legal bytes, one choice per byte.

```rust
fn text_choose<'config, 'arena, Texts: TapeView<u8>, Choices: TapeView<u8>>(
    self,
    texts: Texts,
    choices: Choices,
    config: impl Into<TextChooseConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, TextChoose<'config, 'arena, Texts, Choices>>
where
    Self::Completion: Accepts<Texts> + Accepts<Choices> + Accepts<TextChooseConfig<'config>>,
```

Answers one probability per choice in `choices` order, a softmax over the item's choices
alone at its question type's calibrated inverse temperature.

A state longer than the model's context loses its head, never its end, and a model without
the byte decoder fails the call with [`Status::Unsupported`](https://www.unum.cloud/docs/uform/rust/errors.md#Unsupported).

Calls `uform_text_choose`.

## image_encode

Decodes and encodes JPEG, PNG or WebP files; an undecodable file fails the call with [`Status::Malformed`](https://www.unum.cloud/docs/uform/rust/errors.md#Malformed).

```rust
fn image_encode<'config, 'arena, Images: TapeView<u8>>(
    self,
    images: Images,
    outputs: Outputs,
    config: impl Into<ImageEncodeConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, ImageEncode<'config, 'arena, Images>>
where
    Self::Completion: Accepts<Images> + Accepts<ImageEncodeConfig<'config>>,
```

Calls `uform_image_encode`.

## image_encode_pixels

Encodes decoded images of interleaved 8-bit RGB, item `i` holding `heights[i]` rows of `widths[i]` pixels; an item of another length fails with [`Status::ShapeMismatch`](https://www.unum.cloud/docs/uform/rust/errors.md#ShapeMismatch).

```rust
fn image_encode_pixels<'config, 'arena, Pixels: TapeView<u8>, Heights: AsRef<[u32]>, Widths: AsRef<[u32]>>(
    self,
    pixels: Pixels,
    heights: Heights,
    widths: Widths,
    outputs: Outputs,
    config: impl Into<ImageEncodePixelsConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, ImageEncodePixels<'config, 'arena, Pixels, Heights, Widths>>
where
    Self::Completion: Accepts<Pixels> + Accepts<Heights> + Accepts<Widths> + Accepts<ImageEncodePixelsConfig<'config>>,
```

Calls `uform_image_encode_pixels`.

## video_encode

Decodes and encodes MP4 or WebM clips.

```rust
fn video_encode<'config, 'arena, Videos: TapeView<u8>>(
    self,
    videos: Videos,
    outputs: Outputs,
    config: impl Into<VideoEncodeConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, VideoEncode<'config, 'arena, Videos>>
where
    Self::Completion: Accepts<Videos> + Accepts<VideoEncodeConfig<'config>>,
```

Calls `uform_video_encode`.

## audio_encode

Decodes and encodes WAV, FLAC, MP3 or Opus recordings, resampled to mono.

```rust
fn audio_encode<'config, 'arena, Recordings: TapeView<u8>>(
    self,
    recordings: Recordings,
    outputs: Outputs,
    config: impl Into<AudioEncodeConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, AudioEncode<'config, 'arena, Recordings>>
where
    Self::Completion: Accepts<Recordings> + Accepts<AudioEncodeConfig<'config>>,
```

Calls `uform_audio_encode`.

## audio_encode_samples

Encodes decoded mono recordings sharing one `sample_rate`, resampled to the model's rate where it differs.

```rust
fn audio_encode_samples<'config, 'arena, Samples: TapeView<f32>>(
    self,
    samples: Samples,
    sample_rate: u32,
    outputs: Outputs,
    config: impl Into<AudioEncodeSamplesConfig<'config>>,
    arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, AudioEncodeSamples<'config, 'arena, Samples>>
where
    Self::Completion: Accepts<Samples> + Accepts<AudioEncodeSamplesConfig<'config>>,
```

Calls `uform_audio_encode_samples`.

## Encoded

What an encode verb wrote into the arena it borrows: the surfaces its [`Outputs`](#Outputs) named.

```rust
pub struct Encoded<'arena>
```

Rust-only.

- `embeddings` `Option<Rows<'arena>>`: One pooled embedding of the model's dimensions per item, without normalization.
- `states` `Option<RowsTape<'arena>>`: One final-norm state per token left after truncation, item by item.
- `token_vectors` `Option<RowsTape<'arena>>`: One unit vector of the model's token width per token left after truncation, the prefix
included, item by item.

## ImageEncode

An image forward over encoded files; see [`EncodeVerbs::image_encode`](#image_encode).

```rust
pub struct ImageEncode<'config, 'arena, Images>
```

Calls `uform_image_encode`.

## ImageEncodeConfig

The scalar and the knobs of [`EncodeVerbs::image_encode`](#image_encode); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct ImageEncodeConfig<'config>
```

Mirrors `uform_image_encode_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut ImageEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## ImageEncodePixels

An image forward over decoded pixels; see [`EncodeVerbs::image_encode_pixels`](#image_encode_pixels).

```rust
pub struct ImageEncodePixels<'config, 'arena, Pixels, Heights, Widths>
```

Calls `uform_image_encode_pixels`.

## ImageEncodePixelsConfig

The scalar and the knobs of [`EncodeVerbs::image_encode_pixels`](#image_encode_pixels); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct ImageEncodePixelsConfig<'config>
```

Mirrors `uform_image_encode_pixels_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut ImageEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## ImageEncodeStats

What an image call reports beside its outputs, overwritten by the call.

```rust
pub struct ImageEncodeStats
```

Mirrors `uform_image_encode_stats_t`.

- `truncated` `usize`: Items whose patch grid was cut at the model's context.
- `tokens` `usize`: Patches the call encoded, after truncation.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`

## Outputs

The surfaces an encode verb keeps from its one forward, named after the C fields they fill; [`Outputs::default`](#Outputs) keeps the embeddings alone.

```rust
pub struct Outputs(_);
```

Rust-only; decides which of the C `embeddings`, `states` and `token_vectors` pointers
a verb passes.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Hash`, `Default`, `BitOr`, `BitOrAssign`, `Debug`

## EMBEDDINGS

One pooled embedding per item, past the attention pool and the projection head.

```rust
pub const EMBEDDINGS: Outputs = _;
```

## STATES

One final-norm state per token left after truncation.

```rust
pub const STATES: Outputs = _;
```

## TOKEN_VECTORS

One unit vector of the token head per token left after truncation, the surface late-interaction rerankers score; a model without a token head fails the call with [`Status::Unsupported`](https://www.unum.cloud/docs/uform/rust/errors.md#Unsupported).

```rust
pub const TOKEN_VECTORS: Outputs = _;
```

## contains

Whether every surface `other` names is kept.

```rust
pub const fn contains(self, other: Outputs) -> bool
```

## TextEncode

A text forward; see [`EncodeVerbs::text_encode`](#text_encode).

```rust
pub struct TextEncode<'config, 'arena, Texts>
```

Calls `uform_text_encode`.

## TextEncodeConfig

The scalar and the knobs of [`EncodeVerbs::text_encode`](#text_encode); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct TextEncodeConfig<'config>
```

Mirrors `uform_text_encode_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to; a stopped call reports
[`Status::Cancelled`](https://www.unum.cloud/docs/uform/rust/errors.md#Cancelled) and leaves no outputs.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut TextEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## TextEncodeStats

What a text call reports beside its outputs, overwritten by the call.

```rust
pub struct TextEncodeStats
```

Mirrors `uform_text_encode_stats_t`.

- `truncated` `usize`: Items cut at the model's context.
- `tokens` `usize`: Tokens the call encoded, after truncation.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`

## VideoEncode

A video forward over encoded clips; see [`EncodeVerbs::video_encode`](#video_encode).

```rust
pub struct VideoEncode<'config, 'arena, Videos>
```

Calls `uform_video_encode`.

## VideoEncodeConfig

The scalar and the knobs of [`EncodeVerbs::video_encode`](#video_encode); a bare [`Scalar`](#Scalar) is the whole config.

```rust
pub struct VideoEncodeConfig<'config>
```

Mirrors `uform_video_encode_t`.

- `outputs_scalar` `Scalar`: The scalar type every output lands as.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the items encoded and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut VideoEncodeStats>`: Where the truncation report lands, overwritten by the call.

Implements: `From<[Scalar](#Scalar)>`

## VideoEncodeStats

What a video call reports beside its outputs, overwritten by the call.

```rust
pub struct VideoEncodeStats
```

Mirrors `uform_video_encode_stats_t`.

- `truncated` `usize`: Items cut at the model's context in tubes.
- `tokens` `usize`: Tubes the call encoded, after truncation.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`

## Element

A scalar type a tape holds or a run of rows reads as, tied to the [`Scalar`](#Scalar) the C interface tags its buffers with.

```rust
pub unsafe trait Element: Copy + 'static
```

Rust-only.

#### Safety The associated scalar must describe the type's in-memory encoding exactly; the library

reads raw buffers under that tag.

Implementors: - `impl [Element](#Element) for f64`
- `impl [Element](#Element) for f32`
- `impl [Element](#Element) for i8`
- `impl [Element](#Element) for i32`
- `impl [Element](#Element) for u8`

## SCALAR

The tag the C interface knows this type by.

```rust
const SCALAR: Scalar;
```

## Rows

Rows a call wrote into the arena it borrows, one per item, packed.

```rust
pub struct Rows<'arena>
```

Mirrors `uform_rows_view_t`.

## count

Rows the call wrote.

```rust
pub fn count(&self) -> usize
```

## columns

Values per row, the model's embedding dimensions.

```rust
pub fn columns(&self) -> usize
```

## stride

Bytes between the starts of consecutive rows.

```rust
pub fn stride(&self) -> usize
```

## scalar

The scalar type the rows hold.

```rust
pub fn scalar(&self) -> Option<Scalar>
```

## as_ptr

The first row, in host or device memory, for handing to another library as it is.

```rust
pub fn as_ptr(&self) -> *const c_void
```

## as_bytes

Every row's bytes end to end, refused with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn as_bytes(&self) -> Result<&'arena [u8]>
```

## values

Every row's values end to end, refused with [`Status::InvalidArgument`](https://www.unum.cloud/docs/uform/rust/errors.md#InvalidArgument) when the rows hold another scalar type, and with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn values<Value: Element>(&self) -> Result<&'arena [Value]>
```

## RowsTape

Rows a call wrote into the arena it borrows, as many per item as the item had tokens left after truncation, end to end, with one more offset than items.

```rust
pub struct RowsTape<'arena>
```

Mirrors `uform_rows_tape_view_t`.

## count

Items the call encoded.

```rust
pub fn count(&self) -> usize
```

## offsets

The call's count plus one non-decreasing offsets, in rows, refused with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn offsets(&self) -> Result<&'arena [usize]>
```

## rows

Every item's rows end to end, refused with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn rows(&self) -> Result<Rows<'arena>>
```

## item

The rows of one item, refused with [`Status::InvalidArgument`](https://www.unum.cloud/docs/uform/rust/errors.md#InvalidArgument) when [`item`](#item) is not below [`RowsTape::count`](#count), and with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn item(&self, item: usize) -> Result<Rows<'arena>>
```

## Scalar

Scalar types a model computes in and its outputs land as, numbered as USearch numbers them, so a run of embeddings is a run USearch indexes without conversion.

```rust
pub enum Scalar
```

Sub-byte kinds pack several dimensions per byte, as their `xN` suffixes spell. The C enum
reserves the numbering gaps for kinds that have not landed yet, so this one is open.

Mirrors `uform_scalar_t`.

- `F64` = `1`: IEEE-754 binary64.
- `F32` = `2`: IEEE-754 binary32.
- `BF16` = `3`: Truncated f32 with an 8-bit exponent and a 7-bit mantissa.
- `F16` = `4`: IEEE-754 binary16.
- `E5M2` = `5`: FP8 with a 5-bit exponent: ±57344, with infinities and NaNs.
- `E4M3` = `6`: FP8 with a 4-bit exponent: ±448, no infinities, and two NaN codes.
- `E3M2` = `7`: FP6 with a 3-bit exponent, byte-aligned with two padding bits.
- `E2M3` = `8`: FP6 with a 2-bit exponent, byte-aligned with two padding bits.
- `I8` = `10`: 8-bit signed integer.
- `I4x2` = `11`: Two signed nibbles per byte, even dimensions in the low nibble.
- `I32` = `12`: 32-bit signed integer.
- `U8` = `20`: 8-bit unsigned integer - the element of UTF-8 text and of encoded files.
- `U4x2` = `21`: Two unsigned nibbles per byte, even dimensions in the low nibble.
- `U1x8` = `22`: Eight single-bit dimensions per byte, the sign of each embedding dimension - the form
USearch's Hamming and Jaccard metrics score.

Implements: `From<[Scalar](#Scalar)>`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Hash`, `Display`, `FromStr`

## Tape

Values a call wrote into the arena it borrows, a ragged run per item, end to end, with one more offset than items.

```rust
pub struct Tape<'arena>
```

Mirrors `uform_tape_view_t`.

## count

Items the call wrote.

```rust
pub fn count(&self) -> usize
```

## scalar

The scalar type the values are.

```rust
pub fn scalar(&self) -> Option<Scalar>
```

## offsets

The call's count plus one non-decreasing offsets, in values, refused with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn offsets(&self) -> Result<&'arena [usize]>
```

## values

Every item's values end to end, refused with [`Status::InvalidArgument`](https://www.unum.cloud/docs/uform/rust/errors.md#InvalidArgument) when the tape holds another scalar type, and with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn values<Value: Element>(&self) -> Result<&'arena [Value]>
```

## item

The values of one item, refused with [`Status::InvalidArgument`](https://www.unum.cloud/docs/uform/rust/errors.md#InvalidArgument) when [`item`](#item) is not below [`Tape::count`](#count) or the tape holds another scalar type, and with [`Status::Device`](https://www.unum.cloud/docs/uform/rust/errors.md#Device) over device memory.

```rust
pub fn item<Value: Element>(&self, item: usize) -> Result<&'arena [Value]>
```