PaperForge.StringEncoding (PaperForge v0.2.0)

Encodes strings for use inside PDF objects.

PaperForge currently supports:

PDF literal strings;
PDF hexadecimal strings;
UTF-16BE strings with a byte-order mark;
automatic selection between literal and UTF-16BE encoding.

Standard Type 1 fonts still depend on their own font encoding for visible page content. This module is especially useful for metadata such as titles, authors, subjects, and keywords.

Summary

Types

encoded_string()

Functions

auto(value)

Chooses the most appropriate PDF representation automatically.

latin1?(value)

Returns whether a string can be encoded as Latin-1.

literal(value)

Encodes a string for a PDF literal string.

to_latin1(value)

Attempts to encode a string as Latin-1.

utf16be(value)

Encodes a string as UTF-16BE with a byte-order mark.

utf16be?(arg1)

Returns whether a binary starts with the UTF-16BE byte-order mark.

utf16be_hex(value)

Encodes a string as a PDF hexadecimal UTF-16BE string.

Types

encoded_string()

@type encoded_string() :: binary() | {:hex_string, binary()}

Functions

auto(value)

@spec auto(binary()) :: encoded_string()

Chooses the most appropriate PDF representation automatically.

Strings that can be represented safely using Latin-1 are returned as ordinary binaries. Other strings are returned as UTF-16BE hexadecimal strings.

Examples

PaperForge.StringEncoding.auto("PaperForge")
#=> "PaperForge"

PaperForge.StringEncoding.auto("PDF con 漢字")
#=> {:hex_string, <<254, 255, ...>>}

latin1?(value)

@spec latin1?(binary()) :: boolean()

Returns whether a string can be encoded as Latin-1.

literal(value)

@spec literal(binary()) :: binary()

Encodes a string for a PDF literal string.

The returned value is still a regular Elixir binary. Escaping of parentheses, backslashes, and control characters is handled later by PaperForge.Serializer.

This function raises when the string contains characters outside the Latin-1 range.

Examples

PaperForge.StringEncoding.literal("PaperForge")
#=> "PaperForge"

PaperForge.StringEncoding.literal("Manuel García")
#=> "Manuel García"

to_latin1(value)

@spec to_latin1(binary()) :: {:ok, binary()} | {:error, binary()}

Attempts to encode a string as Latin-1.

Returns:

{:ok, encoded_binary}

or:

{:error, unsupported_character}

utf16be(value)

@spec utf16be(binary()) :: binary()

Encodes a string as UTF-16BE with a byte-order mark.

The result is suitable for use as a PDF hexadecimal string.

Example

PaperForge.StringEncoding.utf16be("México")
#=> <<254, 255, ...>>

utf16be?(arg1)

@spec utf16be?(binary()) :: boolean()

Returns whether a binary starts with the UTF-16BE byte-order mark.

utf16be_hex(value)

@spec utf16be_hex(binary()) :: {:hex_string, binary()}

Encodes a string as a PDF hexadecimal UTF-16BE string.

Example

PaperForge.StringEncoding.utf16be_hex("México")
#=> {:hex_string, <<254, 255, ...>>}