Crate pdfrum_object 

pdfrum-object

The eight object types of ISO 32000-1 §7.3 — null, boolean, integer, real, string, name, array, dictionary — plus streams (a dictionary with bytes) and indirect references (N G R). Construction and typed access only: nothing in this crate reads a byte of a file, which is what lets a page, a font or an annotation be built from synthesized objects in a test with no document behind it.

use pdfrum_object::{Array, Dict, NoResolve, Object, names};

let page = Dict::from_pairs([
    (names::TYPE.clone(), Object::Name(names::PAGE.clone())),
    (names::RECT.clone(), Object::Array(Array::of([0, 0, 612, 792].map(Object::from)))),
]);
assert_eq!(page.rect(names::RECT, &NoResolve).width(), 612.0);

Resolution is one hop, deliberately. A reference whose target is itself a reference reads as absent rather than being chased, because a file can point an object at itself and a resolver that loops is a hang on untrusted input. Accessors come in resolving and non-resolving pairs so a caller says which it wants at every site; NoResolve is the resolver for values that cannot contain references, and it is a type rather than an Option so the choice is visible in the signature.

Numbers have two readings and both are needed. 4294967295 is a valid integer object and a valid real, and a /Length reading it as one while an xref offset reads it as the other is a real file’s real behaviour — so integer and number access are separate methods rather than one lossy conversion.

names is the workspace’s one declaration site for the specification’s dictionary keys. A key spelled there is never spelled again at a use site, so a typo cannot silently produce a lookup that never matches — the failure mode of string keys is a missing feature, not a compile error. Name is a Cow<'static, [u8]>, so a constant costs no allocation, and #xx escapes are resolved on construction so two spellings of one key compare equal.

Part of pdfrum. #![forbid(unsafe_code)].

MIT OR Apache-2.0

Modules

names

The dictionary-key names the specification defines, as constants.

Macros

names

Declare PDF name constants: one table, no desyncing spellings.

Structs

Array

A PDF array: an ordered sequence of objects.

ByteSpan

A window into a shared byte buffer.

Dict

A PDF dictionary: key-value pairs in document order.

Name

A PDF name, holding its decoded bytes without the leading /.

NoResolve

A resolver that knows nothing, for reading dictionaries whose references are irrelevant (or before a store exists).

ObjRef

An indirect object’s identity: the pair a N G obj header carries and a cross-reference entry keys.

PdfString

A PDF string object: raw bytes plus the syntax they were written in.

Stream

A stream object: a dictionary describing bytes, plus the bytes.

Enums

Error

What can go wrong constructing or resolving PDF objects.

Object

A PDF object (ISO 32000-1 §7.3).

Resolved

The result of resolving: a direct object stays borrowed, an indirect one arrives shared from the store.

StringSyntax

How the string was spelled in the file.

Constants

INT_RANGE

The range of integer values a conforming lexer may store in Object::Int.

PDF_DOC_ENCODING

PDFDocEncoding (ISO 32000-1 Annex D.2) as a byte-to-code-point table.

Traits

Resolve

A store that can produce the object behind a reference.

Functions

decode_text

Read a text string’s bytes as text (ISO 32000-1 §7.9.2.2).

encode_string_hex

Spell bytes as a hexadecimal string: <…> with uppercase digit pairs.

encode_string_literal

Spell bytes as a literal string: (…) with \n, \r, \(, \) and \\ escaped and every other byte verbatim.

encode_text

Write text back out as a text string’s bytes (ISO 32000-1 §7.9.2.2).

fmt_int

Spell an integer the way the writers do: through the signed 32-bit view, so a stored 4294967295 writes as -1.

fmt_number

Spell a real the way the content-stream and object writers do.

name_decode

Resolve #xx escapes in a raw name token.

name_encode

Spell a name’s bytes as file syntax (without the leading /).

narrow_to_signed32

The integer view of a stored integer: keep the low 32 bits and read them as signed.

truncate_to_signed32

The integer view of a real: truncate toward zero, saturating at the signed 32-bit bounds, with NaN mapping to 0.

widen_to_f32

The numeric view of a stored integer: widen it to f32.