Sashite.Epin.Identifier (Sashite.Epin v1.2.0)

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/

Summary

Functions

derive(identifier)

Returns a new Identifier marked as derived.

derived?(identifier)

Returns true if the identifier has derived style status.

native(identifier)

Returns a new Identifier marked as native.

native?(identifier)

Returns true if the identifier has native style status.

new(pin, opts \\ [])

Creates a new Identifier from a PIN component.

same_derived?(identifier1, identifier2)

Checks if two Identifiers have the same derived status.

to_string(identifier)

Returns the EPIN string representation.

with_pin(identifier, new_pin)

Returns a new Identifier with a different PIN component.

Types

t()

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

Functions

derive(identifier)

@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?(identifier)

@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(identifier)

@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?(identifier)

@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(pin, opts \\ [])

@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?(identifier1, identifier2)

@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(identifier)

@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(identifier, new_pin)

@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^'"