# `ToonEx.Btoon.ElementType`
[🔗](https://github.com/ohhi-vn/toon_ex/blob/v1.6.0/lib/toon_ex/btoon/element_type.ex#L1)

Element type selectors and raw numeric encoding helpers.

Element types cover the fixed-width numeric types shared by TypedArray
payloads and Schema fields (`:int8`, `:uint8`, `:int16`, `:uint16`,
`:int32`, `:uint32`, `:int64`, `:uint64`, `:float32`, `:float64`) plus
the composite types used only by Schema fields (`:null`, `:bool`,
`:string`, `:binary`, `:array`, `:object`).

All multi-byte values are little-endian (see `ToonEx.Btoon` design notes).

## Deterministic type selection

`detect_type/1` maps a homogeneous numeric list to the narrowest integer
type that represents every value losslessly — signed preferred when a
signed and an unsigned type of the same width both fit — or `:float32`
when every float survives the float32 round-trip and `:float64`
otherwise. Every list therefore has exactly one encoding.

# `numeric`

```elixir
@type numeric() ::
  :int8
  | :uint8
  | :int16
  | :uint16
  | :int32
  | :uint32
  | :int64
  | :uint64
  | :float32
  | :float64
```

Numeric element types (typed arrays and raw buffers).

# `buffer_to_list`

```elixir
@spec buffer_to_list(ToonEx.Btoon.Types.element_type(), binary()) :: [number()]
```

Decodes a raw buffer into a list of numbers.

Uses binary comprehensions: one linear pass with no per-element
sub-binary construction.

# `decode_raw`

```elixir
@spec decode_raw(ToonEx.Btoon.Types.element_type(), binary()) :: {number(), binary()}
```

Decodes the first element of a buffer, returning `{value, rest}`.

# `detect_object_table`

```elixir
@spec detect_object_table([%{optional(String.t()) => term()}]) ::
  {:ok, [String.t()], [ToonEx.Btoon.Types.element_type()], [[number()]]}
  | :error
```

Detects whether a list of maps is a valid columnar object table.

All maps must share the same (sorted) key set and each column must be a
homogeneous numeric column. Returns `{:ok, names, types, columns}` or `:error`.

# `detect_type`

```elixir
@spec detect_type([number()], boolean()) ::
  {:ok, ToonEx.Btoon.Types.element_type()} | :error
```

Detects the narrowest element type for a homogeneous numeric list.

Returns `{:ok, type}` or `:error` when the list is empty, mixed, or
contains integers outside the representable range. Follows the
narrowest-lossless rule: unsigned types are used when the values are all
non-negative and no signed type of the same width fits; `:uint64` is only
returned when `allow_uint64` is set (ObjectTable columns allow it,
TypedArray buffers do not).

# `element_size`

```elixir
@spec element_size(ToonEx.Btoon.Types.element_type()) :: pos_integer()
```

Alias of `size/1` for numeric types (raises for composite types).

# `encode_raw`

```elixir
@spec encode_raw(ToonEx.Btoon.Types.element_type(), number()) :: binary()
```

Encodes a single number to its raw little-endian representation.

# `f32_exact?`

```elixir
@spec f32_exact?(float()) :: boolean()
```

Whether a double survives the IEEE-754 float32 round-trip exactly.

# `int_range`

```elixir
@spec int_range(ToonEx.Btoon.Types.element_type()) :: {integer(), integer()} | nil
```

Integer range for a numeric type: `{min, max}` for integer types,
`nil` for float types.

# `list_to_buffer`

```elixir
@spec list_to_buffer(ToonEx.Btoon.Types.element_type(), [number()]) :: binary()
```

Encodes a list of numbers into a contiguous raw buffer.

# `numeric?`

```elixir
@spec numeric?(ToonEx.Btoon.Types.element_type()) :: boolean()
```

Whether the type is a fixed-width numeric type.

# `size`

```elixir
@spec size(ToonEx.Btoon.Types.element_type()) :: non_neg_integer()
```

Element size in bytes (0 for variable-length composite types).

# `type_atom`

```elixir
@spec type_atom(byte()) :: ToonEx.Btoon.Types.element_type()
```

Maps a wire selector byte to a type atom. Raises `ArgumentError` for
unknown selectors.

# `type_atom_or_nil`

```elixir
@spec type_atom_or_nil(byte()) :: ToonEx.Btoon.Types.element_type() | nil
```

Maps a wire selector byte to a type atom or `nil`.

# `type_byte`

```elixir
@spec type_byte(ToonEx.Btoon.Types.element_type()) :: byte() | nil
```

Maps a numeric type atom to its wire selector byte.

Returns `nil` for unknown or composite types.

# `typed_array_type?`

```elixir
@spec typed_array_type?(ToonEx.Btoon.Types.element_type()) :: boolean()
```

Whether the type may appear as a TypedArray element type.

---

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