# `PdfElixide.Document.Font`
[🔗](https://github.com/r8/pdf_elixide/blob/v0.16.0/lib/pdf_elixide/document/font.ex#L1)

A font referenced by a PDF page, with its zero-based page index, the page's
font resource name, and metadata describing the face.

The `:base_font` name has any six-letter subset prefix (`ABCDEF+`) stripped;
`:subset?` records whether one was present. `:subtype` is the PDF font type
(`"Type1"`, `"TrueType"`, `"Type0"`), and `:encoding` is `:identity`,
`:custom`, or `{:standard, name}` for a named base encoding such as
`"WinAnsiEncoding"`.

The raw embedded font program is not carried on the struct; instead `:ref` is a
handle to the font, and `data/1` pulls the bytes on demand:

    {:ok, bytes} = PdfElixide.Document.Font.data(font)   # embedded TTF/OTF bytes

For a non-embedded font (`:embedded?` is `false`, e.g. one of the standard 14)
`data/1` returns `{:ok, nil}`.

`data/1` takes the handle's lock shared and `close/1` takes it exclusively, so
several processes can pull embedded font programs in parallel; see the
[Concurrency](guides/concurrency.md) guide.

# `encoding`

```elixir
@type encoding() :: {:standard, String.t()} | :custom | :identity
```

A font's character encoding: `{:standard, name}` for a named base encoding,
or `:custom` / `:identity`.

# `t`

```elixir
@type t() :: %PdfElixide.Document.Font{
  base_font: String.t(),
  bold?: boolean(),
  embedded?: boolean(),
  encoding: encoding(),
  italic?: boolean(),
  page: non_neg_integer(),
  ref: reference(),
  resource_name: String.t(),
  subset?: boolean(),
  subtype: String.t(),
  weight: integer() | nil
}
```

# `close`

```elixir
@spec close(t()) :: :ok
```

Releases this handle's reference to the font immediately.

The embedded font program behind `:ref` is normally released when the BEAM
garbage-collects the handle; `close/1` releases this handle now. Calling it is
optional and idempotent, and other extracted font handles remain valid. It
takes the handle's lock exclusively, so it waits for an in-flight `data/1` —
*immediately* means as soon as the handle is idle, not preemptively.

Afterwards `data/1` returns `{:error, %PdfElixide.Error{reason: :closed}}`
(and `data!/1` raises it); the metadata fields on the struct keep working. A
font's lifetime is independent of the document it came from — closing either
one leaves the other usable.

# `closed?`

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

Returns whether the font handle has been released with `close/1`.

# `data`

```elixir
@spec data(t()) :: {:ok, binary() | nil} | {:error, PdfElixide.Error.t()}
```

Returns the font's raw embedded font-program bytes — the TrueType / OpenType
file, suitable for re-embedding elsewhere.

Returns `{:ok, nil}` for a non-embedded font (`:embedded?` is `false`).

# `data!`

```elixir
@spec data!(t()) :: binary() | nil
```

Same as `data/1` but returns the bytes directly, raising on error.

---

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