PdfElixide.Document.Font (pdf_elixide v0.12.0)

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 guide.

Summary

Types

encoding()

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

t()

Functions

close(font)

Releases this handle's reference to the font immediately.

closed?(font)

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

data(font)

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

data!(font)

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

Types

encoding()

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

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

t()

@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
}

Functions

close(font)

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

Releases this handle's reference to the font immediately.

The embedded font program behind :ref is normally freed when the BEAM garbage-collects the handle; close/1 releases it now. Calling it is optional and idempotent. Because a font can be shared between pages, the underlying bytes are freed once no other extracted handle still references the same font. 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?(font)

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

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

data(font)

@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!(font)

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

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