Skip to main content

Document

Struct Document 

Source
pub struct Document { /* private fields */ }
Expand description

A parsed PDF file.

Opening is cheap: only the header, the cross-reference sections and the trailer are read. Pages, streams and content are parsed on demand by Document::get_object, which caches what it reads.

Implementations§

Source§

impl Document

Source

pub fn extract_text(&self, page: &Page) -> Result<String>

Extract the text of a page’s content streams.

Source

pub fn extract_text_from( &self, content: &[u8], resources: Option<&Dictionary>, ) -> Result<String>

Extract text from a decoded content stream and its resource dictionary.

Source

pub fn spans(&self, page: &Page) -> Result<Vec<TextSpan>>

The page’s lines with their rectangles, in the same order extract_text reports the text (ADR 0008).

Source

pub fn search(&self, needle: &str) -> Result<Vec<PageHits>>

Every occurrence of needle in the document’s pages, case-insensitively.

The search runs over the spans, so a phrase is found inside a line and never across a line break: a reader searching “first line” wants the words, and a reader searching for text that only matches if two lines are glued together wants a different tool. An empty needle matches nothing rather than everything.

Source

pub fn spans_from( &self, content: &[u8], resources: Option<&Dictionary>, ) -> Result<Vec<TextSpan>>

Spans of a decoded content stream and its resource dictionary.

Source§

impl Document

Source

pub fn open(data: impl Into<Vec<u8>>) -> Result<Self>

Open a PDF from its bytes.

Accepts %PDF-1.x and %PDF-2.x files whose cross-reference is a classic table, an xref stream, or a hybrid of both, with any number of /Prev sections.

An encrypted file is opened with the empty password, which covers the common “no password needed, but encrypted” case; use Document::open_with_password otherwise.

Source

pub fn open_with_password( data: impl Into<Vec<u8>>, password: &[u8], ) -> Result<Self>

Open a PDF with a password for its /V 5 (AES-256) security handler.

Source

pub fn open_path(path: impl AsRef<Path>) -> Result<Self>

Open a PDF from a file path.

Source

pub fn open_path_with_password( path: impl AsRef<Path>, password: &[u8], ) -> Result<Self>

Open a PDF from a file path with a password.

Source

pub fn is_encrypted(&self) -> bool

Whether the document was opened with a security handler.

Source

pub fn version(&self) -> &str

The version from the header, e.g. "2.0".

Source

pub fn trailer(&self) -> &Dictionary

The newest trailer dictionary.

Source

pub fn catalog(&self) -> Result<Object>

The document catalog, reached through the trailer’s /Root.

The catalogue is the entry point of the whole object graph (§7.7.2).

Source

pub fn get_object(&self, id: ObjectId) -> Result<Object>

Fetch the object with this id, following the cross-reference.

Only the object number selects the entry, so a stale generation still resolves — that is what real readers do and what incremental updates rely on. Use Document::get_object_by_number to fetch with the generation the cross-reference records.

Results are cached, so fetching the same object twice parses it once.

Source

pub fn get_object_by_number(&self, number: u32) -> Result<Object>

Fetch an object by number, using the generation the cross-reference has.

Source

pub fn contains_object(&self, number: u32) -> bool

Whether the cross-reference knows number as a live object.

Source

pub fn stream(&self, id: ObjectId) -> Result<Stream>

Fetch a stream object by id.

Source

pub fn decoded_limit(&self) -> usize

The decoded-bytes budget: the most any one stream may decode to.

Defaults to filter::DEFAULT_DECODE_LIMIT (256 MiB). A stream that would decode past it fails with crate::Error::Limit instead of allocating: without the cap a 1 MiB file can expand to a gigabyte, which is a denial of service rather than a rendering failure.

Source

pub fn set_decoded_limit(&self, bytes: usize)

Set the decoded-bytes budget, in bytes; usize::MAX lifts it.

Lower it when the caller knows its own ceiling (a browser tab, a server-side preview), or raise it for a document whose images legitimately decode to more than the default.

Source

pub fn object_limit(&self) -> usize

How many objects may be read before one is refused.

Defaults to DEFAULT_OBJECT_LIMIT. The count is of objects held after being read, so a document that lists millions in its cross-reference is still opened — the ceiling is on parsing them, which is the part that costs memory.

Source

pub fn set_object_limit(&self, objects: usize)

Set the object ceiling; usize::MAX lifts it.

Source

pub fn page_limit(&self) -> usize

How many pages a page tree may list.

Defaults to DEFAULT_PAGE_LIMIT. Every pages call walks the tree, so this bounds the work a crafted /Pages can ask for.

Source

pub fn set_page_limit(&self, pages: usize)

Set the page ceiling; usize::MAX lifts it.

A document that legitimately has more pages than the default raises it, and a caller rendering one page at a time can lower it.

Source

pub fn decode_stream(&self, stream: &Stream) -> Result<Vec<u8>>

Decode a stream’s payload through its filter chain.

Indirect /Filter and /DecodeParms entries are resolved through the object table first, which is what the plain Stream::decode cannot do on its own.

Source

pub fn stream_bytes(&self, id: ObjectId) -> Result<Vec<u8>>

Fetch a stream’s payload with decryption applied and its filters left alone.

A caller that brings its own decoder — the renderer’s /DCTDecode path — needs the bytes the file holds, decrypted if the document is encrypted, because Document::decode_stream would refuse an image filter.

Source

pub fn stream_data(&self, id: ObjectId) -> Result<Vec<u8>>

Fetch a stream by id and decode its payload in one step.

Source§

impl Document

Source

pub fn catalog_dict(&self) -> Result<Dictionary>

The catalog dictionary.

Source

pub fn pages(&self) -> Result<Vec<Page>>

Walk the page tree and return every page in document order.

Source

pub fn page_count(&self) -> Result<usize>

Number of pages, counted by walking the tree rather than trusting /Count.

Source

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

The page at index, counting from zero.

Source

pub fn page_user_unit(&self, page: &Page) -> Result<f64>

The page’s effective /UserUnit, defaulting to 1.0 (7.7.3.4).

The attribute is inheritable, so the page dictionary’s /Parent chain is walked; a missing entry, a cycle (bounded at 32 levels) or a non-positive value stops the walk at 1.0.

Source

pub fn page_content(&self, page: &Page) -> Result<Vec<u8>>

The decoded content of a page, with its streams joined by a newline.

This is the input the content-stream interpreter takes.

Source

pub fn has_metadata(&self) -> Result<bool>

Whether the catalog carries an XMP /Metadata stream.

Source

pub fn metadata(&self) -> Result<Option<Vec<u8>>>

The decoded XMP metadata packet, if the document has one.

Source§

impl Document

Source

pub fn new() -> DocumentBuilder

Start a new, empty PDF 2.0 document.

Returns a DocumentBuilder rather than a reader: collect objects and pages with it, then DocumentBuilder::save the file and Document::open it back. The name follows the plan’s Document::new() … save() shape; the builder is the only thing that can be “new”, because a reader always comes from bytes.

Trait Implementations§

Source§

impl Debug for Document

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl LengthResolver for Document

Source§

fn resolve_length(&self, id: ObjectId) -> Result<usize>

The byte length of the object id points at.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.