# `Once.Prefixed`
[🔗](https://github.com/juulSme/Once/blob/v1.3.1/lib/once/prefixed.ex#L1)

> #### DEPRECATED! Use `Once` directly {: .warning}
>
> This module exists for backward compatibility. New code should use `Once` directly with the `:prefix` option instead. All functionality is identical.

A wrapper for `Once` that adds a prefix to IDs. This module is soft-deprecated in favor of using `Once` with the `:prefix` option.

For complete documentation on prefixed IDs, including prefix persistence, format conversion, and examples, see the [Prefixed IDs section](`m:Once#module-prefixed-ids`) in the `Once` module documentation.

## Usage

**Recommended approach** - use `Once` directly:

    schema "users" do
      field :id, Once, prefix: "usr_", autogenerate: true
      field :external_id, Once, prefix: "usr_"
    end

Legacy approach (for backward compatibility only):

    schema "users" do
      field :id, Prefixed, prefix: "usr_", autogenerate: true
      field :external_id, Prefixed, prefix: "usr_"
    end

# `to_format`

> This function is deprecated. Use Once.to_format/3 with option :prefix instead.

```elixir
@spec to_format(binary(), binary(), Once.format(), [Once.to_format_opt()]) ::
  {:ok, binary()} | :error
```

Transform a prefixed ID between different formats while preserving the prefix.

This works like `Once.to_format/3` but handles the prefix automatically. The prefix must match the second argument.

Note that this function does not return integers when converting to `:signed` or `:unsigned`, but only numeric strings like "prfx_123".

## Options

- `:parse_int` parse numeric strings like `"123"`. Will give unexpected results with all-int hex/url64 inputs.
- `:prefix` format prefixed IDs (e.g. `"usr_Ad6RZCrAAAM"`) as another prefixed format (e.g. `"usr_01de91642ac00004"`)

## Examples

    iex> id = "prfx_18446744073709551615"
    iex> {:ok, "prfx___________8" = id}                    = Prefixed.to_format(id, "prfx_", :url64, parse_int: true)
    iex> {:ok, <<"prfx_", 18446744073709551615::64>> = id} = Prefixed.to_format(id, "prfx_", :raw)
    iex> {:ok, "prfx_-1" = id}                             = Prefixed.to_format(id, "prfx_", :signed)
    iex> {:ok, "prfx_ffffffffffffffff" = id}               = Prefixed.to_format(id, "prfx_", :hex, parse_int: true)
    iex> {:ok, "prfx_vvvvvvvvvvvvu" = id}                  = Prefixed.to_format(id, "prfx_", :hex32)
    iex> {:ok, "prfx_18446744073709551615"}                = Prefixed.to_format(id, "prfx_", :unsigned)

    iex> Prefixed.to_format("wrong_AAAAAAAAAAA", "usr_", :unsigned)
    :error
    iex> Prefixed.to_format("AAAAAAAAAAA", "usr_", :unsigned)
    :error

# `to_format!`

> This function is deprecated. Use Once.to_format!/3 with option :prefix instead.

```elixir
@spec to_format!(binary(), binary(), Once.format(), [Once.to_format_opt()]) ::
  binary()
```

Same as `to_format/4` but raises on error.

## Examples

    iex> "usr_AAAAAAAAAAA"
    ...> |> Prefixed.to_format!("usr_", :unsigned)
    ...> |> Prefixed.to_format!("usr_", :hex, parse_int: true)
    ...> |> Prefixed.to_format!("usr_", :signed)
    ...> |> Prefixed.to_format!("usr_", :raw, parse_int: true)
    ...> |> Prefixed.to_format!("usr_", :hex32)
    ...> |> Prefixed.to_format!("usr_", :url64)
    "usr_AAAAAAAAAAA"

    iex> Prefixed.to_format!("usr_AAAAAAAAAAA", "wrong_", :signed)
    ** (ArgumentError) value could not be parsed: "usr_AAAAAAAAAAA"

    iex> Prefixed.to_format!("AAAAAAAAAAA", "usr_", :signed)
    ** (ArgumentError) value could not be parsed: "AAAAAAAAAAA"

---

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