PdfElixide.Document.Font (pdf_elixide v0.10.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}.

A font handle may be passed to other processes, and data/1 takes it shared, so several processes can pull embedded font programs from one document at once, in parallel — the bytes are already held behind the handle, with no shared cache underneath. Only close/1 is exclusive. Same model as the Concurrency guide describes for a document.

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 on the same font. 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.