pub struct Document { /* private fields */ }Expand description
A loaded PDF document.
Implementations§
Source§impl Document
impl Document
Sourcepub fn load(data: Vec<u8>) -> Result<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.
Sourcepub fn load_with_password(data: Vec<u8>, password: &str) -> Result<Document>
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.
Sourcepub fn open_with_password(
path: impl AsRef<Path>,
password: &str,
) -> Result<Document>
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.
Sourcepub fn open(path: impl AsRef<Path>) -> Result<Document>
pub fn open(path: impl AsRef<Path>) -> Result<Document>
Reads the file at path and loads it via Document::load.
Sourcepub fn is_encrypted(&self) -> bool
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.
Sourcepub fn is_locked(&self) -> bool
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.
Sourcepub fn get(&self, r: ObjRef) -> Result<Object>
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).
Sourcepub fn resolve(&self, o: &Object) -> Result<Object>
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.
Sourcepub fn stream_data(&self, s: &Stream) -> Result<Vec<u8>>
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.
Sourcepub fn seed(&self) -> DocumentSeed
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.
Sourcepub fn from_seed(seed: DocumentSeed) -> Document
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.
Sourcepub fn fork(&self) -> Document
pub fn fork(&self) -> Document
Document::seed and Document::from_seed in one step, for a
fork used on the calling thread.
Sourcepub fn page_count(&self) -> usize
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.
Sourcepub fn flattened_page_count(&self) -> usize
pub fn flattened_page_count(&self) -> usize
Number of pages the page tree actually holds: the flattened tree’s
length, walking the tree on first use. This is the count
Document::page indexes into; it differs from
Document::page_count only while the tree is unwalked and its
declared /Count is wrong.
Sourcepub fn metadata(&self) -> Metadata
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.
Sourcepub fn oc_state(&self) -> Option<OcState>
pub fn oc_state(&self) -> Option<OcState>
The document’s optional-content visibility as a viewer shows it on
screen: the default configuration (ISO 32000-1 §8.11.4.3) with the
View usage application (§8.11.4.4) applied, 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.
Sourcepub fn oc_state_for(&self, event: Option<OcEvent>) -> Option<OcState>
pub fn oc_state_for(&self, event: Option<OcEvent>) -> Option<OcState>
The document’s optional-content visibility under one usage
application event (ISO 32000-1 §8.11.4.4), or under the default
configuration alone for None; None in the result when the catalog
declares no /OCProperties. See crate::OcState::load_for_with.
Covers ISO 32000-1 §8.11.4.5.
Sourcepub fn optional_content_groups(&self, event: Option<OcEvent>) -> Vec<OcGroup>
pub fn optional_content_groups(&self, event: Option<OcEvent>) -> Vec<OcGroup>
The document’s optional content groups (ISO 32000-1 §8.11.2.1) in
/OCGs order, each with its state under event; empty without
/OCProperties.
Covers ISO 32000-1 §8.11.4.2.
Sourcepub fn structure_tree(&self) -> Option<StructureTree>
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: the root, its
role and class maps and every entry of its parent tree, so a caller
walking the pages loads it once and forks it per worker (its
Clone, see map_pages_forking); the tree ranks a page’s marked
content on request and keeps what each walk read for the next.
Sourcepub fn content_items(&self, page: &Page) -> Vec<PlacedItem>
pub fn content_items(&self, page: &Page) -> Vec<PlacedItem>
A page’s content items in structure-tree order (ISO 32000-1 §14.7.4): the marked-content sequences of its content stream and the annotations the tree holds through object references, ranked together, so each annotation sits where §14.8.2.3.2 puts it in the page’s content order. Empty for a page the tree does not reach, or a document without a tree.
Sourcepub fn named(&self, tree: NameTree, key: &[u8]) -> Option<Object>
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.
Sourcepub fn names(&self, tree: NameTree) -> Vec<(Vec<u8>, Object)>
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.
Sourcepub fn named_destination(&self, name: &[u8]) -> Option<Destination>
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.
Sourcepub fn named_destinations(&self) -> Vec<(Vec<u8>, Destination)>
pub fn named_destinations(&self) -> Vec<(Vec<u8>, Destination)>
Every named destination of the document, sorted by name.
Sourcepub fn destination(&self, value: &Object) -> Option<Destination>
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).
Sourcepub fn outline(&self) -> Vec<OutlineItem>
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.
Sourcepub fn page_labels(&self) -> Option<Vec<PageLabel>>
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.
Sourcepub fn language(&self) -> Option<String>
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.
Sourcepub fn language_tag(&self) -> Option<LanguageTag>
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.
Sourcepub fn extensions(&self) -> Vec<DeveloperExtension>
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.
Sourcepub fn viewer_preferences(&self) -> Option<ViewerPreferences>
pub fn viewer_preferences(&self) -> Option<ViewerPreferences>
The catalog’s viewer preferences (ISO 32000-1 §12.2), None when
the catalog declares none.
Sourcepub fn linearization(&self) -> Option<Linearization>
pub fn linearization(&self) -> Option<Linearization>
The linearization parameter dictionary (ISO 32000-1 Annex F.3) as
written, None when the file’s first object is not one. It may be
stale after an appended update; Document::is_linearized tells.
Sourcepub fn is_linearized(&self) -> bool
pub fn is_linearized(&self) -> bool
Whether the file is linearized and its parameter dictionary still
applies, which Table F.1 ties to /L naming the file’s actual
length.
Covers ISO 32000-1 Annex F.3.
Sourcepub fn output_intents(&self) -> Vec<OutputIntent>
pub fn output_intents(&self) -> Vec<OutputIntent>
The catalog’s output intents (ISO 32000-1 §14.11.5) in array order,
empty without /OutputIntents.
Sourcepub fn piece_info(&self) -> Vec<PagePiece>
pub fn piece_info(&self) -> Vec<PagePiece>
The catalog’s page-piece dictionary (ISO 32000-1 §14.5): one record
per product, empty without /PieceInfo.
Sourcepub fn page_piece_info(&self, page: &Page) -> Vec<PagePiece>
pub fn page_piece_info(&self, page: &Page) -> Vec<PagePiece>
A page’s page-piece dictionary (ISO 32000-1 §14.5): one record per
product, empty without /PieceInfo on the page.
Sourcepub fn thumbnail(&self, page: &Page) -> Option<Thumbnail>
pub fn thumbnail(&self, page: &Page) -> Option<Thumbnail>
A page’s thumbnail image (ISO 32000-1 §12.3.4), None when the
page has no /Thumb stream.
Sourcepub fn articles(&self) -> Vec<ArticleThread>
pub fn articles(&self) -> Vec<ArticleThread>
The catalog’s article threads (ISO 32000-1 §12.4.3) in array order,
empty without /Threads.
Sourcepub fn page_beads(&self, page: &Page) -> Vec<ObjRef>
pub fn page_beads(&self, page: &Page) -> Vec<ObjRef>
The beads on a page in drawing order (ISO 32000-1 §12.4.3), empty
without /B.
Sourcepub fn presentation(&self, page: &Page) -> Option<Presentation>
pub fn presentation(&self, page: &Page) -> Option<Presentation>
A page’s presentation entries (ISO 32000-1 §12.4.4), None when
the page has neither /Dur nor a /Trans dictionary.
Sourcepub fn viewports(&self, page: &Page) -> Vec<Viewport>
pub fn viewports(&self, page: &Page) -> Vec<Viewport>
The viewports of a page’s /VP array (ISO 32000-1 §12.9), empty
without one.
Sourcepub fn separation_info(&self, page: &Page) -> Option<SeparationInfo>
pub fn separation_info(&self, page: &Page) -> Option<SeparationInfo>
A page’s separation dictionary (ISO 32000-1 §14.11.4), None when
the page has no /SeparationInfo naming a colorant.
Sourcepub fn annotations(&self, page: &Page) -> Vec<Annotation>
pub fn annotations(&self, page: &Page) -> Vec<Annotation>
The annotations of a page’s /Annots array (ISO 32000-1 §12.5.2),
in order, with their actions read as data.
Sourcepub fn page_additional_actions(&self, page: &Page) -> Vec<TriggeredAction>
pub fn page_additional_actions(&self, page: &Page) -> Vec<TriggeredAction>
The actions a page’s /AA dictionary fires when it opens and closes
(ISO 32000-1 §12.6.3), empty without one.
Sourcepub fn additional_actions(&self) -> Vec<TriggeredAction>
pub fn additional_actions(&self) -> Vec<TriggeredAction>
The actions the catalog’s /AA dictionary fires around closing,
saving and printing (ISO 32000-1 §12.6.3), empty without one.
Sourcepub fn action(&self, value: &Object) -> Option<Action>
pub fn action(&self, value: &Object) -> Option<Action>
The action an /A or /AA value holds, with its /Next chain
(ISO 32000-1 §12.6.2); None when the value is no action
dictionary.
Sourcepub fn permission_handlers(&self) -> Option<PermissionHandlers>
pub fn permission_handlers(&self) -> Option<PermissionHandlers>
The permission handlers of the catalog’s /Perms dictionary (ISO
32000-1 §12.8.4), None without one.
Sourcepub fn requirements(&self) -> Vec<Requirement>
pub fn requirements(&self) -> Vec<Requirement>
The requirements the catalog’s /Requirements array lists (ISO
32000-1 §12.10.1), empty without one.
Sourcepub fn legal_attestation(&self) -> Option<LegalAttestation>
pub fn legal_attestation(&self) -> Option<LegalAttestation>
The catalog’s legal attestation dictionary (ISO 32000-1 §12.8.5),
None without one.
Sourcepub fn interactive_form(&self) -> Option<InteractiveForm>
pub fn interactive_form(&self) -> Option<InteractiveForm>
The document’s interactive form dictionary (ISO 32000-1 §12.7.2),
None when the catalog has no /AcroForm.
Sourcepub fn form_fields(&self) -> Vec<FormField>
pub fn form_fields(&self) -> Vec<FormField>
Every field of the document’s interactive form (ISO 32000-1 §12.7.3), depth first from the root fields; empty without a form.
Sourcepub fn page_label(&self, index: usize) -> Option<String>
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.
Sourcepub fn embedded_files(&self) -> Vec<EmbeddedFile>
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.
Sourcepub fn embedded_file_data(&self, file: &EmbeddedFile) -> Result<Vec<u8>>
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.
Source§impl Document
impl Document
Sourcepub fn elements(&self, opts: ElementOpts) -> Elements<'_> ⓘ
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§
Source§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.
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.