# `Sashite.Epin.Identifier`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L1)

Represents a parsed EPIN (Extended Piece Identifier Notation) identifier.

An Identifier combines a PIN component with a derivation status:
- PIN: encodes abbr, side, state, and terminal status
- Derived: indicates whether the piece uses native or derived style

## Examples

    iex> pin = Sashite.Pin.parse!("K^")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> Sashite.Epin.Identifier.to_string(epin)
    "K^"

    iex> pin = Sashite.Pin.parse!("K^")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> Sashite.Epin.Identifier.to_string(epin)
    "K^'"

@see https://sashite.dev/specs/epin/1.0.0/

# `t`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L29)

```elixir
@type t() :: %Sashite.Epin.Identifier{
  derived: boolean(),
  pin: Sashite.Pin.Identifier.t()
}
```

# `derive`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L238)

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

Returns a new Identifier marked as derived.

Returns the same struct if already derived.

## Examples

    iex> pin = Sashite.Pin.parse!("K^")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> result = Sashite.Epin.Identifier.derive(epin)
    iex> Sashite.Epin.Identifier.to_string(result)
    "K^'"

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> result = Sashite.Epin.Identifier.derive(epin)
    iex> result == epin
    true

# `derived?`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L100)

```elixir
@spec derived?(t()) :: boolean()
```

Returns `true` if the identifier has derived style status.

## Examples

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> Sashite.Epin.Identifier.derived?(epin)
    true

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> Sashite.Epin.Identifier.derived?(epin)
    false

# `native`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L264)

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

Returns a new Identifier marked as native.

Returns the same struct if already native.

## Examples

    iex> pin = Sashite.Pin.parse!("K^")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> result = Sashite.Epin.Identifier.native(epin)
    iex> Sashite.Epin.Identifier.to_string(result)
    "K^"

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> result = Sashite.Epin.Identifier.native(epin)
    iex> result == epin
    true

# `native?`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L118)

```elixir
@spec native?(t()) :: boolean()
```

Returns `true` if the identifier has native style status.

## Examples

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> Sashite.Epin.Identifier.native?(epin)
    true

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> Sashite.Epin.Identifier.native?(epin)
    false

# `new`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L64)

```elixir
@spec new(
  Sashite.Pin.Identifier.t(),
  keyword()
) :: t()
```

Creates a new Identifier from a PIN component.

## Parameters

- `pin` - A `Sashite.Pin.Identifier` struct
- `opts` - Keyword list with optional `:derived` key (default: `false`)

## Examples

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> epin.derived
    false

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> epin.derived
    true

## Raises

- `ArgumentError` if `pin` is not a valid `Sashite.Pin.Identifier`
- `ArgumentError` if `derived` is not a boolean

# `same_derived?`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L294)

```elixir
@spec same_derived?(t(), t()) :: boolean()
```

Checks if two Identifiers have the same derived status.

## Examples

    iex> pin1 = Sashite.Pin.parse!("K")
    iex> pin2 = Sashite.Pin.parse!("Q")
    iex> epin1 = Sashite.Epin.Identifier.new(pin1, derived: true)
    iex> epin2 = Sashite.Epin.Identifier.new(pin2, derived: true)
    iex> Sashite.Epin.Identifier.same_derived?(epin1, epin2)
    true

    iex> pin1 = Sashite.Pin.parse!("K")
    iex> pin2 = Sashite.Pin.parse!("K")
    iex> epin1 = Sashite.Epin.Identifier.new(pin1, derived: true)
    iex> epin2 = Sashite.Epin.Identifier.new(pin2, derived: false)
    iex> Sashite.Epin.Identifier.same_derived?(epin1, epin2)
    false

# `to_string`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L165)

```elixir
@spec to_string(t()) :: String.t()
```

Returns the EPIN string representation.

Each valid combination has its own function clause, generated at compile
time. The BEAM dispatches directly to the correct clause and returns a
pre-computed binary literal — zero concatenation, zero allocation.

## Examples

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin)
    iex> Sashite.Epin.Identifier.to_string(epin)
    "K"

    iex> pin = Sashite.Pin.parse!("K")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> Sashite.Epin.Identifier.to_string(epin)
    "K'"

    iex> pin = Sashite.Pin.parse!("+K^")
    iex> epin = Sashite.Epin.Identifier.new(pin, derived: true)
    iex> Sashite.Epin.Identifier.to_string(epin)
    "+K^'"

# `with_pin`
[🔗](https://github.com/sashite/epin.ex/blob/main/lib/sashite/epin/identifier.ex#L206)

```elixir
@spec with_pin(t(), Sashite.Pin.Identifier.t()) :: t()
```

Returns a new Identifier with a different PIN component.

## Examples

    iex> pin1 = Sashite.Pin.parse!("K")
    iex> pin2 = Sashite.Pin.parse!("+Q^")
    iex> epin = Sashite.Epin.Identifier.new(pin1, derived: true)
    iex> result = Sashite.Epin.Identifier.with_pin(epin, pin2)
    iex> Sashite.Epin.Identifier.to_string(result)
    "+Q^'"

---

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