# `Ash.UUIDv7`
[🔗](https://github.com/ash-project/ash/blob/v3.23.1/lib/ash/uuid_v7.ex#L5)

Helpers for working with UUIDs version 7.

[RFC 9562](https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-7)

Used for generating UUIDs version 7 with increased clock precision for better monotonicity,
as described by method 3 of the [Section 6.2](https://www.rfc-editor.org/rfc/rfc9562#name-monotonicity-and-counters

Inspired by the work of [Ryan Winchester](https://github.com/ryanwinchester/) on [uuidv7](https://github.com/ryanwinchester/uuidv7)

## Examples

    iex> UUIDv7.generate()
    "018e90d8-06e8-7f9f-bfd7-6730ba98a51b"

    iex> UUIDv7.bingenerate()
    <<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>

# `raw`

```elixir
@type raw() :: &lt;&lt;_::128&gt;&gt;
```

A raw binary representation of a UUID.

# `t`

```elixir
@type t() :: &lt;&lt;_::288&gt;&gt;
```

A hex-encoded UUID string.

# `bingenerate`

```elixir
@spec bingenerate() :: raw()
```

Generates a version 7 UUID in the binary format.

Optionally accepts a `DateTime` to embed a specific timestamp, which is useful
when migrating existing records and you need to preserve their original creation order.

## Examples

    iex> UUIDv7.bingenerate()
    <<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>

# `bingenerate`

```elixir
@spec bingenerate(DateTime.t()) :: raw()
```

# `decode`

```elixir
@spec decode(t() | raw()) :: raw() | :error
```

Decode a string representation of a UUID to the raw binary version.

## Example

    iex> UUIDv7.decode("018e90d8-06e8-7f9f-bfd7-6730ba98a51b")
    <<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>

# `encode`

```elixir
@spec encode(t() | raw()) :: t() | :error
```

Encode a raw UUID to the string representation.

## Example

    iex> UUIDv7.encode(<<1, 142, 144, 216, 6, 232, 127, 159, 191, 215, 103, 48, 186, 152, 165, 27>>)
    "018e90d8-06e8-7f9f-bfd7-6730ba98a51b"

# `extract_timestamp`

```elixir
@spec extract_timestamp(t() | raw()) :: integer()
```

Extract the millisecond timestamp from the UUID.

## Example

    iex> UUIDv7.extract_timestamp("018ecb40-c457-73e6-a400-000398daddd9")
    1712807003223

# `generate`

```elixir
@spec generate() :: t()
```

Generates a version 7 UUID using submilliseconds for increased clock precision.

Optionally accepts a `DateTime` to embed a specific timestamp, which is useful
when migrating existing records and you need to preserve their original creation order.

## Examples

    iex> UUIDv7.generate()
    "018e90d8-06e8-7f9f-bfd7-6730ba98a51b"

    iex> UUIDv7.generate(~U[2024-01-01 00:00:00Z])
    "018cfa9b-b400-7e72-a400-000398daddd9"

# `generate`

```elixir
@spec generate(DateTime.t()) :: t()
```

---

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