Struct Document 

pub struct Document { /* private fields */ }

A loaded PDF document.

Implementations

impl Document

pub fn load(data: Vec<u8>) -> Result<Document>

Loads a document from bytes: locates the %PDF-x.y header (scanning the first 1 KiB, defaulting to 1.4), loads the xref, and sets up decryption for files using the Standard security handler (RC4 or AES) under the empty user password (password-protected files yield Error::Encrypted).

The page tree is not walked here: it is flattened lazily on the first page access, so opening a document (or reading page_count) does not parse every page dictionary.

pub fn load_with_password(data: Vec<u8>, password: &str) -> Result<Document>

Document::load with the password that opens the file, accepted as either the user or the owner password. The empty string is the transparent empty-user-password case Document::load always handles; a password the file does not accept yields Error::Encrypted. Non-ASCII passwords are tried UTF-8 encoded and, for the legacy RC4/AES-128 revisions, Latin-1 encoded as well, covering both encodings real files use.

pub fn open_with_password( path: impl AsRef<Path>, password: &str, ) -> Result<Document>

Reads the file at path and loads it via Document::load_with_password.

pub fn open(path: impl AsRef<Path>) -> Result<Document>

Reads the file at path and loads it via Document::load.

pub fn version(&self) -> (u8, u8)

The PDF version from the header, e.g. (1, 7).

pub fn bytes(&self) -> &[u8]

Raw bytes of the loaded file.

pub fn xref(&self) -> &Xref

The merged cross-reference table and trailer.

pub fn is_encrypted(&self) -> bool

True when the trailer carries a non-null /Encrypt entry: the file declares encryption, whether or not this handle decrypted it.

pub fn is_locked(&self) -> bool

True when the file is encrypted and not opened with a working password: Document::is_encrypted but no Decryptor was configured, so object strings and stream data would decode as ciphertext rather than the document’s actual content.

pub fn get(&self, r: ObjRef) -> Result<Object>

Fetches an indirect object by reference (xref lookup, object-stream indirection, cached). A generation mismatch between the request and the file is tolerated (lenient).

pub fn resolve(&self, o: &Object) -> Result<Object>

Chases reference chains with a depth guard of MAX_RESOLVE_DEPTH (beyond that: Error::CircularReference, naming the last reference followed); a reference to a missing or unreadable object resolves to Null (lenient).

The loop is crate::source::resolve_sync_with, shared with the provided crate::source::ObjectSource::resolve, so the two cannot drift apart. It reaches Document::get through this type’s ObjectSource implementation, which forwards to it unchanged.

pub fn stream_data(&self, s: &Stream) -> Result<Vec<u8>>

Decodes a stream’s data through its filter chain, resolving indirect filter parameters against this document.

pub fn seed(&self) -> DocumentSeed

The document’s shareable core: everything immutable, nothing cached. Forces the page tree first, so no document built from the seed re-walks it.

pub fn from_seed(seed: DocumentSeed) -> Document

A handle to the same document for another thread: share a DocumentSeed across the thread boundary — the seed is Send and Sync; the document, whose caches are single-threaded by design, is neither — and materialize one of these per thread.

The immutable core is shared — the file bytes, the merged cross-reference table, the decryption key material, and the flattened page tree — while the interior caches start fresh, private to this document. That is the whole design: per-page work is independent and lock-free precisely because nothing mutable is shared, so N documents on N threads contend on nothing.

map_pages is the ready-made consumer.

pub fn fork(&self) -> Document

Document::seed and Document::from_seed in one step, for a fork used on the calling thread.

pub fn page_count(&self) -> usize

Number of pages.

Reports the page tree’s declared /Count — the same value mature engines return — without walking the tree, so it is cheap on an otherwise-untouched document. If /Count is absent or implausible the tree is flattened and its true (lenient, cycle- and depth-guarded) length is returned instead. Once the tree has been flattened for any reason, that flattened length is authoritative.

pub fn page(&self, index: usize) -> Result<Page>

The page at 0-based index.

pub fn metadata(&self) -> Metadata

Document metadata from the trailer /Info dictionary (lenient: absent or malformed entries are simply None).

Covers ISO 32000-1 §14.3.3, §7.9.4 and §8.11.4.3.

pub fn oc_state(&self) -> Option<OcState>

The document’s optional-content visibility under its default configuration (ISO 32000-1 §8.11.4.3), or None when the catalog declares no /OCProperties — no optional content, everything visible. Computed per call from a handful of object reads.

Covers ISO 32000-1 §8.11.4.2.

pub fn structure_tree(&self) -> Option<StructureTree>

The document’s structure tree (ISO 32000-1 §14.7), or None when the catalog names no /StructTreeRoot. Loaded per call from a handful of object reads; the tree ranks a page’s marked content on request.

pub fn named(&self, tree: NameTree, key: &[u8]) -> Option<Object>

The object that key names in the catalog’s tree (ISO 32000-1 §7.7.4), resolved: a destination for NameTree::Dests, a file specification for NameTree::EmbeddedFiles. None when the document has no such tree or the tree has no such name.

pub fn names(&self, tree: NameTree) -> Vec<(Vec<u8>, Object)>

Every name in the catalog’s tree with the object it names, unresolved, in tree order; empty when the document has no such tree.

pub fn named_destination(&self, name: &[u8]) -> Option<Destination>

The destination name designates (ISO 32000-1 §12.3.2.3), from the /Names /Dests tree or the catalog’s /Dests dictionary.

pub fn named_destinations(&self) -> Vec<(Vec<u8>, Destination)>

Every named destination of the document, sorted by name.

pub fn destination(&self, value: &Object) -> Option<Destination>

The destination a /Dest or /D value denotes: an explicit array, a name or string looked up among the named destinations, or a dictionary whose /D holds one of those (ISO 32000-1 §12.3.2).

pub fn outline(&self) -> Vec<OutlineItem>

The document outline (ISO 32000-1 §12.3.3): the top-level items with their descendants, in display order; empty when there is none.

pub fn page_labels(&self) -> Option<Vec<PageLabel>>

The document’s page labelling ranges (ISO 32000-1 §12.4.2), sorted by first page; None when the catalog has no /PageLabels.

pub fn language(&self) -> Option<String>

The language the catalog declares for the document’s text (/Lang, ISO 32000-1 §14.9.2), or None when it declares none.

pub fn language_tag(&self) -> Option<LanguageTag>

The document’s language as a parsed identifier (ISO 32000-1 §14.9.2.2), None when the catalog declares none or the tag is not well formed.

pub fn extensions(&self) -> Vec<DeveloperExtension>

The developer extensions the catalog declares (ISO 32000-1 §7.12), sorted by prefix; empty when the catalog declares none.

pub fn viewer_preferences(&self) -> Option<ViewerPreferences>

The catalog’s viewer preferences (ISO 32000-1 §12.2), None when the catalog declares none.

pub fn page_label(&self, index: usize) -> Option<String>

The label the page at index shows, or None when the document has no page labels or no such page.

pub fn embedded_files(&self) -> Vec<EmbeddedFile>

The document-level embedded files (ISO 32000-1 §7.11.4): every entry of the catalog’s /EmbeddedFiles name tree, in tree order.

pub fn embedded_file_data(&self, file: &EmbeddedFile) -> Result<Vec<u8>>

The decoded bytes of one embedded file.

Errors

MissingKey("EF") when the file specification embeds no stream, and the stream’s own decoding errors.

impl Document

pub fn elements(&self, opts: ElementOpts) -> Elements<'_>

Lazy iteration over the document’s elements. Physical elements come in file order (header, objects by offset with object-stream members after their container, xref sections newest→oldest, trailer, startxref, eof); logical elements follow in document order. Nothing is parsed or decoded before it is yielded; an element that fails to parse yields Err for that item and iteration continues.

Physical objects sort by (file offset, member index, object number): in-file objects use their own offset with member index 0; object-stream members use their container’s offset with member index 1 + index so they directly follow their container in stream-index order; members whose container is missing or free sort last (offset u64::MAX) and surface as Err items; ties on offset and member index break by ascending object number.

Trait Implementations

impl ObjectSource for Document

Forwards to the inherent methods, so reading a document through the trait is bit-identical to reading it directly. resolve is forwarded too, even though the provided implementation is now the same shared chase (crate::source::resolve_sync_with) that the inherent method delegates to: routing it through the inherent method keeps the two entry points a single call, so they cannot drift should Document::resolve ever grow document-specific behaviour.

fn get(&self, r: ObjRef) -> Result<Object>

Fetches an indirect object by reference.

fn stream_data(&self, s: &Stream) -> Result<Vec<u8>>

Decodes a stream’s data through its filter chain, resolving indirect filter parameters against this source.

fn resolve(&self, o: &Object) -> Result<Object>

Chases reference chains, depth-capped at MAX_RESOLVE_DEPTH.

impl Resolve for Document

fn resolve_ref(&self, r: ObjRef) -> Option<Object>

Returns the referenced object, or None if it cannot be resolved.