Struct SaveOptions 

#[non_exhaustive]
pub struct SaveOptions { /* private fields */ }

Options for saving a PDF document.

Default behaviour (per RFC 0001 §1.2): linearize = false, overwrite = false. save / save_with therefore refuse to clobber existing files unless you opt in via with_overwrite(true).

Determinism

For an unencrypted document, save, save_with, to_bytes, and write_to produce byte-identical output for byte-identical input (issue #1308). This is enforced by integration tests in tests/determinism.rs and is part of the 1.0 contract.

Specifically guaranteed:

• Object ordering is sorted by (id, generation) — BTreeMap in lopdf.
• Dictionary key order is preserved on round-trip — IndexMap in lopdf.
• Stream content is copied as-is.
• The cross-reference table is derived deterministically.

NOT deterministic (by design):

• Encrypted output — AES IVs and content keys are randomly generated per save (security requirement, ISO 32000-2 §7.6). Two saves of the same encrypted document produce different bytes.
• Caller-introduced timestamps — anything you write via metadata_mut() using the system clock (e.g. set_creation_date(SystemTime::now())).

Customer CI pipelines that compare PDF checksums depend on this guarantee — break it only with a new RFC.

Implementations

impl SaveOptions

pub fn new() -> Self

New default options.

pub fn with_linearize(self, v: bool) -> Self

Linearize the output for fast web view.

1.0 behaviour

In 1.0 this flag is accepted but currently a no-op. A true linearizer lands in 1.1. Use it to make your code forward-compatible without waiting for the feature.

pub fn with_overwrite(self, v: bool) -> Self

Permit overwriting an existing file at the target path.

Default is false per RFC 0001 §1.2: save / save_with refuse to clobber an existing file unless you opt in here. This protects against accidental overwrites of either the source file or unrelated files.

pub fn with_incremental(self, v: bool) -> Self

Enable incremental save.

When set to true, only changes made to the PDF will be appended to the original file. This preserves signatures and avoids rewriting the entire file. Returns an error if the document is encrypted or was not loaded from bytes.

Trait Implementations

impl Clone for SaveOptions

fn clone(&self) -> SaveOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SaveOptions

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

Formats the value using the given formatter.

impl Default for SaveOptions

fn default() -> SaveOptions

Returns the “default value” for a type.