# `Stamp`
[🔗](https://github.com/a3kov/stamp/blob/main/lib/stamp.ex#L1)

Stamp is a fast and flexible Snowflake-flavored ID generator based on 8-byte
integers with optional encoding.

# `t`

```elixir
@type t() :: %Stamp{
  node: non_neg_integer() | nil,
  partition: non_neg_integer() | nil,
  sequence: non_neg_integer(),
  time: non_neg_integer()
}
```

# `value`

```elixir
@type value() :: non_neg_integer() | String.t()
```

# `datetime`

```elixir
@spec datetime(value(), Stamp.Config.t()) :: DateTime.t()
```

Returns UTC DateTime stored in the id.
This function is for non-Ecto uses. For Ecto fields use `datetime/3`.
Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in integer or string form (strictly according to config)

  - `config` - `Stamp.Config` structure containing parameters for the stamp.

# `datetime`

```elixir
@spec datetime(value(), module(), atom()) :: DateTime.t() | :no_return
```

Returns UTC DateTime stored in the field. Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in "loaded" form.

  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

# `next_field_id`

```elixir
@spec next_field_id(module(), atom(), Keyword.t()) :: value() | :no_return
```

Generates next id for the field. Raises `ArgumentError` on errors.

Arguments:
  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

  - `opts` - generation options (same options as in `next_id/3`).

# `next_id`

```elixir
@spec next_id(any(), Stamp.Config.t(), Keyword.t()) :: value() | :no_return
```

Generates next id using provided sequence_id and configuration.
This function is for non-Ecto uses. For Ecto fields use `next_field_id/3`.

Arguments:
  - `sequence_id` - unique term used to create sequence for the stamps.
    Stamps using different `sequence_id` are supposed to be used in
    separate contexts and can have intersecting values without causing
    issues. Do not include config parameters in it - it's done automatically
    by the library. Good examples: `:comment_id`, `{Comment, :id}`.

  - `config` - `Stamp.Config` structure containing parameters for
    generating the ID.

  - `opts` - generation options.

Supported options:
  - `time` - OS time in milliseconds, using unix epoch. When provided,
    Stamp will try to use it for the generation instead of calling
    `System.os_time/1`. The number must fit in `time_bits` without
    overflow.

  - `partition` - integer number of the partition that will be used instead
    of calling `partition_fun/0` from the config, if the partitioning
    is enabled. The number must fit in `partition_bits` without overflow.

# `partition`

```elixir
@spec partition(value(), Stamp.Config.t()) :: non_neg_integer() | nil
```

Returns partition stored in the id, or nil if the stamp is not partitioned.
This function is for non-Ecto uses. For Ecto fields use `partition/3`.
Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in integer or string form (strictly according to config)

  - `config` - `Stamp.Config` structure containing parameters for the stamp.

# `partition`

```elixir
@spec partition(value(), module(), atom()) :: non_neg_integer() | nil
```

Returns partition stored in the field, or nil. Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in "loaded" form.

  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

# `to_integer`

```elixir
@spec to_integer(value(), Stamp.Config.t()) :: {:ok, non_neg_integer()} | :error
```

Converts the id to integer. Returns `{:ok, integer_id}` or `:error` if the
value can't be decoded.

# `to_integer`

```elixir
@spec to_integer(value(), module(), atom()) :: {:ok, non_neg_integer()} | :error
```

Converts the field value to integer. Returns `{:ok, integer_id}` or `:error` if the
value can't be decoded.

Arguments:
  - `id` - stamp in integer or string form.

  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

# `to_integer!`

```elixir
@spec to_integer!(value(), Stamp.Config.t()) :: non_neg_integer() | :no_return
```

Converts the id to integer. Returns the integer id or raises if the
value can't be decoded.

Arguments:
  - `id` - stamp in integer or string form

  - `config` - `Stamp.Config` structure containing parameters for
    the stamp.

# `to_integer!`

```elixir
@spec to_integer!(value(), module(), atom()) :: non_neg_integer() | :no_return
```

Converts the field value to integer. Returns integer id or raises if the value can't
be decoded.

Arguments:
  - `id` - stamp in integer or string form.

  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

# `unpack`

```elixir
@spec unpack(value(), Stamp.Config.t()) :: t() | :no_return
```

Unpacks parameters stored in the id.
This function is for non-Ecto uses. For Ecto fields use `unpack/3`.
Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in integer or string form (strictly according to config)

  - `config` - `Stamp.Config` structure containing parameters for the stamp.

# `unpack`

```elixir
@spec unpack(value(), module(), atom()) :: t() | :no_return
```

Unpacks parameters stored in the field. Raises `ArgumentError` on errors.

Arguments:
  - `id` - stamp in "loaded" form.

  - `schema` - Ecto schema module.

  - `field` - Ecto schema field atom.

---

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