# `TFLiteElixir.TFLiteTensor`
[🔗](https://github.com/cocoa-xu/tflite_elixir/blob/main/lib/tflite_elixir/tflite_tensor.ex#L1)

A typed multi-dimensional array used in Tensorflow Lite.

A `%TFLiteTensor{}` is a snapshot of the tensor's metadata plus a live handle
to it. `type/1`, `dims/1`, `shape/1` and `quantization_params/1` answer from
the snapshot; `to_binary/2`, `to_nx/2` and `set_data/2` go through the handle.
The two can disagree after `TFLiteElixir.Interpreter.resize_input_tensor/3`,
which moves the interpreter's tensors and retires every handle taken before
it: the snapshot still reports the old shape while the handle reports that it
has been retired. Fetch the tensor again with
`TFLiteElixir.Interpreter.tensor/2` after a resize, or pass `tensor.reference`
to ask the interpreter directly.

# `nif_error`

```elixir
@type nif_error() :: {:error, String.t()}
```

# `nif_resource_ok`

```elixir
@type nif_resource_ok() :: {:ok, reference()}
```

# `tensor_type`

```elixir
@type tensor_type() ::
  :no_type
  | {:f, 32}
  | {:s, 32}
  | {:u, 8}
  | {:s, 64}
  | :string
  | :bool
  | {:s, 16}
  | {:c, 64}
  | {:s, 8}
  | {:f, 16}
  | {:f, 64}
  | {:c, 128}
  | {:u, 64}
  | :resource
  | :variant
  | {:u, 32}
  | {:u, 16}
  | {:bf, 16}
  | {:f, 8}
  | {:f8_e4m3fn, 8}
  | :unknown
```

# `dims`

```elixir
@spec dims(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | {:error, String.t()}
) :: [integer()] | {:error, String.t()}
@spec dims(reference()) :: [integer()] | nif_error()
```

Get the dimensions (C++) API

Given a struct this answers the snapshot taken when the struct was built, so
it does not follow a later `TFLiteElixir.Interpreter.resize_input_tensor/3`.
Sizing a buffer from a stale answer is the way this bites: the dimensions
still multiply out to the old byte count while `set_data/2` on the same
struct answers `{:error, _}`. Pass `tensor.reference` to ask the interpreter.

# `quantization_params`

```elixir
@spec quantization_params(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | reference()
  | {:error, String.t()}
) ::
  %TFLiteElixir.TFLiteQuantizationParams{
    quantized_dimension: term(),
    scale: term(),
    zero_point: term()
  }
  | nif_error()
```

Get the quantization params

Given a struct this answers the snapshot; pass `tensor.reference` to ask the
interpreter, which reports a retired handle rather than stale params.

# `set_data`

```elixir
@spec set_data(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | reference()
  | {:error, String.t()},
  binary()
  | %Nx.Tensor{
      data: term(),
      donatable?: term(),
      names: term(),
      shape: term(),
      type: term(),
      vectorized_axes: term()
    }
) :: :ok | nif_error()
```

Set tensor data

# `shape`

```elixir
@spec shape(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | {:error, String.t()}
) :: tuple() | {:error, String.t()}
@spec shape(reference()) :: tuple() | nif_error()
```

Get the tensor shape

Given a struct this answers the snapshot; pass `tensor.reference` to ask the
interpreter, which reports a retired handle rather than a stale shape.

# `to_binary`

```elixir
@spec to_binary(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | reference()
  | {:error, String.t()},
  non_neg_integer()
) :: binary() | {:error, String.t()}
```

Get binary data

# `to_nx`

```elixir
@spec to_nx(
  reference()
  | %TFLiteElixir.TFLiteTensor{
      index: term(),
      name: term(),
      quantization_params: term(),
      reference: term(),
      shape: term(),
      shape_signature: term(),
      sparsity_params: term(),
      type: term()
    }
  | {:error, String.t()},
  Keyword.t()
) ::
  %Nx.Tensor{
    data: term(),
    donatable?: term(),
    names: term(),
    shape: term(),
    type: term(),
    vectorized_axes: term()
  }
  | {:error, String.t()}
```

Convert `TFLiteElixir.TFLiteTensor` to `Nx.Tensor`

# `type`

```elixir
@spec type(
  %TFLiteElixir.TFLiteTensor{
    index: term(),
    name: term(),
    quantization_params: term(),
    reference: term(),
    shape: term(),
    shape_signature: term(),
    sparsity_params: term(),
    type: term()
  }
  | {:error, String.t()}
) :: tensor_type() | {:error, String.t()}
@spec type(reference()) :: tensor_type() | nif_error()
```

Get the data type

Given a struct this answers the snapshot; pass `tensor.reference` to ask the
interpreter, which reports a retired handle rather than a stale type.

---

*Consult [api-reference.md](api-reference.md) for complete listing*