A boxed UUID — a struct that wraps the raw 16-byte binary.
Version-agnostic: any 16-byte UUID (v1, v4, v7, …) can live inside. The version is encoded in the bytes themselves, so the struct doesn't need to know which generator produced it.
Why a struct?
Plain hex strings ("019d...") force a binary ↔ hex round-trip on
every Ecto insert. %UUID{bytes: <<_::128>>} carries the raw bytes and
only formats to hex on to_string/1, inspect/1, or JSON encoding —
so the formatting cost is paid once, when something actually displays
the value, instead of on every database write.
Use with Ecto
See UUIDv7.Boxed for an Ecto type that autogenerates %UUID{} values
with version 7 timestamps.
Constructing
UUID.wrap(<<_::128>> = raw_bytes)
UUID.parse("019d2566-fe40-7000-8000-000000000000")
UUIDv7.Boxed.autogenerate()Summary
Functions
Builds a %UUID{} from a 16-byte raw binary or a 36-char hex string.
Parses a 36-char hex string into a %UUID{}.
Renders the boxed UUID as its canonical hex string.
Returns the raw 16-byte binary inside a %UUID{}.
Types
Functions
Builds a %UUID{} from a 16-byte raw binary or a 36-char hex string.
Raises ArgumentError on anything else — use parse/1 for the
{:ok, _} | :error variant.
Examples
iex> UUID.new("018e90d8-06e8-7f9f-bfd7-6730ba98a51b") |> UUID.to_string()
"018e90d8-06e8-7f9f-bfd7-6730ba98a51b"
iex> raw = <<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>
iex> UUID.new(raw).bytes == raw
trueParses a 36-char hex string into a %UUID{}.
Returns {:ok, %UUID{}} or :error. Mirrors Date.from_iso8601/1.
Example
iex> {:ok, uuid} = UUID.parse("018e90d8-06e8-7f9f-bfd7-6730ba98a51b")
iex> uuid.bytes
<<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>Renders the boxed UUID as its canonical hex string.
@spec unwrap(t()) :: <<_::128>>
Returns the raw 16-byte binary inside a %UUID{}.