Struct PdfiumDocument

pub struct PdfiumDocument { /* private fields */ }

Rust interface to FPDF_DOCUMENT

Implementations

impl PdfiumDocument

pub fn new() -> PdfiumResult<Self>

Creates a new empty PdfiumDocument

Examples found in repository

examples/import_pages.rs (line 43)

pub fn example_import_pages() -> PdfiumResult<()> {
    // Create a new, empty PDF document that will serve as our destination
    // This document starts with 0 pages and we'll add pages to it
    let document = PdfiumDocument::new()?;

    // Load the source PDF document from which we'll extract pages
    // The second parameter (None) means we're not providing a password
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import specific pages from the source document into our destination document
    // Parameters breakdown:
    // - &src_doc: Reference to the source document to import from
    // - "12,14,30-34": String specifying which pages to import
    //   * Page 12 (individual page)
    //   * Page 14 (individual page)
    //   * Pages 30-34 (range of 5 pages: 30, 31, 32, 33, 34)
    //   * Total: 7 pages will be imported
    // - 0: Index position where imported pages should be inserted
    //   * 0 means insert at the beginning of the destination document
    //   * If the destination had existing pages, imported pages would be inserted before them
    document.pages().import(&src_doc, "12,14,30-34", 0)?;

    // Save the destination document with imported pages to a new file
    // The second parameter (None) indicates we're not specifying a version
    document.save_to_path("pride-1.pdf", None)?;

    // Verification step: reload the saved document to confirm the operation
    let document = PdfiumDocument::new_from_path("pride-1.pdf", None)?;

    // Get the total number of pages in the saved document
    let page_count = document.page_count();

    // Assert that we have exactly 7 pages as expected
    // This confirms that all specified pages were imported correctly:
    // 1 page (12) + 1 page (14) + 5 pages (30-34) = 7 pages total
    assert_eq!(page_count, 7);

    Ok(())
}

/// Demonstrates importing PDF pages using index-based page specification.
///
/// This function shows an alternative approach to page importing using
/// explicit page indices rather than string specifications. This method
/// provides more programmatic control and is useful when:
/// - You have a dynamically generated list of page numbers
/// - You need to import non-contiguous pages with complex patterns
/// - You're working with 0-based indexing in your application logic
///
/// Key differences from string-based approach:
/// - Uses 0-based indexing (first page is index 0)
/// - Requires explicit specification of each page index
/// - More verbose but offers precise control
/// - Better for programmatic generation of page lists
pub fn example_import_pages_by_index() -> PdfiumResult<()> {
    // Create a new, empty PDF document to serve as our destination
    let document = PdfiumDocument::new()?;

    // Load the same source PDF document as in the previous example
    // We're extracting the same pages but using a different method
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import pages using explicit 0-based indices
    // Parameters breakdown:
    // - &src_doc: Reference to the source document
    // - Some(&[11, 13, 29, 30, 31, 32, 33]): Vector of 0-based page indices
    //   * Index 11 = Page 12 in human numbering (11 + 1 = 12)
    //   * Index 13 = Page 14 in human numbering (13 + 1 = 14)
    //   * Indices 29-33 = Pages 30-34 in human numbering
    //   * Note: This matches exactly the same pages as "12,14,30-34" from the previous example
    //   * The Some() wrapper indicates we're providing a specific list of indices
    //   * Using None instead would import all pages from the source document
    // - 0: Insertion position (beginning of destination document)
    document
        .pages()
        .import_by_index(&src_doc, Some(&[11, 13, 29, 30, 31, 32, 33]), 0)?;

    // Save the document with a different filename to distinguish from the first example
    // Even though the content should be identical, using different names helps with testing
    document.save_to_path("pride-2.pdf", None)?;

    // Verification: reload the saved document to ensure it was created correctly
    let document = PdfiumDocument::new_from_path("pride-2.pdf", None)?;

    // Count the pages in the saved document
    let page_count = document.page_count();

    // Verify that we have the same 7 pages as the string-based method
    // This confirms both methods produce identical results:
    // - 1 page at index 11 (page 12)
    // - 1 page at index 13 (page 14)
    // - 5 pages at indices 29-33 (pages 30-34)
    // Total: 7 pages
    assert_eq!(page_count, 7);

    Ok(())
}

pub fn new_from_path<P: AsRef<Path>>( path: P, password: Option<&str>, ) -> PdfiumResult<Self>

Load a PdfiumDocument from a Path

Examples found in repository

examples/import_pages.rs (line 47)

pub fn example_import_pages() -> PdfiumResult<()> {
    // Create a new, empty PDF document that will serve as our destination
    // This document starts with 0 pages and we'll add pages to it
    let document = PdfiumDocument::new()?;

    // Load the source PDF document from which we'll extract pages
    // The second parameter (None) means we're not providing a password
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import specific pages from the source document into our destination document
    // Parameters breakdown:
    // - &src_doc: Reference to the source document to import from
    // - "12,14,30-34": String specifying which pages to import
    //   * Page 12 (individual page)
    //   * Page 14 (individual page)
    //   * Pages 30-34 (range of 5 pages: 30, 31, 32, 33, 34)
    //   * Total: 7 pages will be imported
    // - 0: Index position where imported pages should be inserted
    //   * 0 means insert at the beginning of the destination document
    //   * If the destination had existing pages, imported pages would be inserted before them
    document.pages().import(&src_doc, "12,14,30-34", 0)?;

    // Save the destination document with imported pages to a new file
    // The second parameter (None) indicates we're not specifying a version
    document.save_to_path("pride-1.pdf", None)?;

    // Verification step: reload the saved document to confirm the operation
    let document = PdfiumDocument::new_from_path("pride-1.pdf", None)?;

    // Get the total number of pages in the saved document
    let page_count = document.page_count();

    // Assert that we have exactly 7 pages as expected
    // This confirms that all specified pages were imported correctly:
    // 1 page (12) + 1 page (14) + 5 pages (30-34) = 7 pages total
    assert_eq!(page_count, 7);

    Ok(())
}

/// Demonstrates importing PDF pages using index-based page specification.
///
/// This function shows an alternative approach to page importing using
/// explicit page indices rather than string specifications. This method
/// provides more programmatic control and is useful when:
/// - You have a dynamically generated list of page numbers
/// - You need to import non-contiguous pages with complex patterns
/// - You're working with 0-based indexing in your application logic
///
/// Key differences from string-based approach:
/// - Uses 0-based indexing (first page is index 0)
/// - Requires explicit specification of each page index
/// - More verbose but offers precise control
/// - Better for programmatic generation of page lists
pub fn example_import_pages_by_index() -> PdfiumResult<()> {
    // Create a new, empty PDF document to serve as our destination
    let document = PdfiumDocument::new()?;

    // Load the same source PDF document as in the previous example
    // We're extracting the same pages but using a different method
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import pages using explicit 0-based indices
    // Parameters breakdown:
    // - &src_doc: Reference to the source document
    // - Some(&[11, 13, 29, 30, 31, 32, 33]): Vector of 0-based page indices
    //   * Index 11 = Page 12 in human numbering (11 + 1 = 12)
    //   * Index 13 = Page 14 in human numbering (13 + 1 = 14)
    //   * Indices 29-33 = Pages 30-34 in human numbering
    //   * Note: This matches exactly the same pages as "12,14,30-34" from the previous example
    //   * The Some() wrapper indicates we're providing a specific list of indices
    //   * Using None instead would import all pages from the source document
    // - 0: Insertion position (beginning of destination document)
    document
        .pages()
        .import_by_index(&src_doc, Some(&[11, 13, 29, 30, 31, 32, 33]), 0)?;

    // Save the document with a different filename to distinguish from the first example
    // Even though the content should be identical, using different names helps with testing
    document.save_to_path("pride-2.pdf", None)?;

    // Verification: reload the saved document to ensure it was created correctly
    let document = PdfiumDocument::new_from_path("pride-2.pdf", None)?;

    // Count the pages in the saved document
    let page_count = document.page_count();

    // Verify that we have the same 7 pages as the string-based method
    // This confirms both methods produce identical results:
    // - 1 page at index 11 (page 12)
    // - 1 page at index 13 (page 14)
    // - 5 pages at indices 29-33 (pages 30-34)
    // Total: 7 pages
    assert_eq!(page_count, 7);

    Ok(())
}

examples/text_extract_search.rs (line 26)

pub fn example_extract_text() -> PdfiumResult<()> {
    // Load the PDF document from the specified file path
    // The second parameter (None) indicates no password is required
    let document = PdfiumDocument::new_from_path("resources/chapter1.pdf", None)?;

    // Iterate through all pages in the document
    // enumerate() provides both the index and the page object
    for (index, page) in document.pages().enumerate() {
        // Extract the full text content from the current page
        // The ?. operators handle potential errors at each step:
        // - page? ensures the page loaded successfully
        // - .text()? extracts text objects from the page
        // - .full() gets the complete text content as a string
        let text = page?.text()?.full();

        // Print formatted output for each page
        println!("Page {}", index + 1); // Pages are 1-indexed for user display
        println!("------");
        println!("{text}");
        println!() // Empty line for separation between pages
    }

    // Expected output:
    //
    // Page 1
    // ------
    //
    // Page 2
    // ------
    // Ruskin
    // House.
    // 156. Charing
    // Cross Road.
    // London
    // George Allen.
    //
    // Page 3
    // ------
    //
    // Page 4
    // ------
    // I
    // Chapter I.
    // T is a truth universally acknowledged, that a single man in possession of a good
    // fortune must be in want of a wife.
    // However little known the feelings or views of such a man may be on his first
    // entering a neighbourhood, this truth is so well fixed in the minds of the surrounding
    // families, that he is considered as the rightful property of some one or other of their
    // daughters.
    // “My dear Mr. Bennet,” said his lady to him one day, “have you heard that
    // Netherfield Park is let at last?”
    // ...

    Ok(())
}

/// Demonstrates text search functionality within a PDF document
pub fn example_search() -> PdfiumResult<()> {
    // Load the PDF document to search within
    let document = PdfiumDocument::new_from_path("resources/groningen.pdf", None)?;

    // Get the first page (index 0) for searching
    let page = document.page(0)?;

    // Extract text objects from the page for searching
    let text = page.text()?;

    // Search for "amsterdam" with case-insensitive matching
    // PdfiumSearchFlags::empty() means no special search flags (case-insensitive by default)
    // The last parameter (0) is the starting position for the search
    let search = text.find("amsterdam", PdfiumSearchFlags::empty(), 0);
    println!("Found amsterdam {} times", search.count());

    // Search for "groningen" with case-insensitive matching
    let search = text.find("groningen", PdfiumSearchFlags::empty(), 0);
    println!(
        "Found groningen {} times (case insensitive)",
        search.count()
    );

    // Search for "Groningen" with case-sensitive matching
    // MATCH_CASE flag enforces exact case matching
    let search = text.find("Groningen", PdfiumSearchFlags::MATCH_CASE, 0);
    println!("Found Groningen {} times (case sensitive)", search.count());

    // Perform another case-insensitive search to iterate through results
    let search = text.find("groningen", PdfiumSearchFlags::empty(), 0);

    // Iterate through each search result to extract detailed information
    for result in search {
        // Extract the text fragment at the found position
        // result.index() gives the character position where the match starts
        // result.count() gives the length of the matched text
        let fragment = text.extract(result.index(), result.count());
        println!(
            "Found groningen (case insensitive) at {}, fragment = '{fragment}'",
            result.index()
        );
    }

    // Expected output:
    //
    // Found amsterdam 0 times
    // Found groningen 5 times (case insensitive)
    // Found Groningen 5 times (case sensitive)
    // Found groningen (case insensitive) at 14, fragment = 'Groningen'
    // Found groningen (case insensitive) at 232, fragment = 'Groningen'
    // Found groningen (case insensitive) at 475, fragment = 'Groningen'
    // Found groningen (case insensitive) at 920, fragment = 'Groningen'
    // Found groningen (case insensitive) at 1050, fragment = 'Groningen'

    Ok(())
}

examples/export_pages.rs (line 39)

pub fn example_export_pages_to_images() -> PdfiumResult<()> {
    // Load the PDF document from the specified file path
    // Parameters:
    // - "resources/groningen.pdf": Path to the PDF file (relative to current working directory)
    // - None: No password required for this PDF (use Some("password") if needed)
    let document = PdfiumDocument::new_from_path("resources/groningen.pdf", None)?;

    // Iterate through all pages in the document
    // document.pages() returns an iterator over all pages
    // enumerate() adds an index counter starting from 0
    // This gives us both the page object and its 0-based index
    for (index, page) in document.pages().enumerate() {
        // Render the current page as a bitmap image
        // This is where the PDF content gets converted to a raster image
        //
        // In the configuration we only specify the height in pixels. The width will be calculated
        // automatically to maintain aspect ratio.
        let config = PdfiumRenderConfig::new().with_height(1080);
        let bitmap = page?.render(&config)?;

        // Verify that the bitmap was rendered at the requested height
        // This assertion ensures the rendering process worked as expected
        // If this fails, it indicates a bug in the rendering logic
        assert_eq!(bitmap.height(), 1080);

        // Generate a unique filename for this page
        // Format: "groningen-page-{page_number}.jpg"
        // - index + 1 converts from 0-based index to 1-based page numbers
        //   * Page 0 becomes "groningen-page-1.jpg"
        //   * Page 1 becomes "groningen-page-2.jpg", etc.
        // - The .jpg extension indicates JPEG format will be used
        let filename = format!("groningen-page-{}.jpg", index + 1);

        // Save the rendered bitmap to disk as a JPEG image
        // Parameters:
        // - &filename: Reference to the generated filename string
        // - image::ImageFormat::Jpeg: Specifies JPEG compression format
        //   * Alternative format: Png (lossless)
        //   * JPEG provides good compression but is lossy (some quality loss)
        //
        // The save operation handles:
        // - Converting from BGRA format to JPEG-compatible format
        // - Applying JPEG compression
        // - Writing the file to disk
        bitmap.save(&filename, image::ImageFormat::Jpeg)?;

        // Note: No explicit cleanup needed - Rust's ownership system automatically
        // deallocates the bitmap memory when it goes out of scope at the end of this iteration
    }

    // Return success - all pages have been successfully exported
    Ok(())
}

pub fn new_from_reader<R: Read + Seek + 'static>( reader: R, password: Option<&str>, ) -> PdfiumResult<Self>

Load a PdfiumDocument using a reader implementing Read and Seek

pub fn save_to_path<P: AsRef<Path>>( &self, path: P, version: Option<i32>, ) -> PdfiumResult<()>

Saves this PdfiumDocument to a file at the specified path.

This is a convenience method that creates a new file at the given path and writes the PDF document to it. The file will be created if it doesn’t exist, or truncated if it does exist.

Arguments

• path - A path-like type (String, &str, Path, PathBuf, etc.) that specifies where to save the PDF file. Uses AsRef<Path> for maximum flexibility.
• version - Optional PDF version to save as. If None, saves as a copy of the original document preserving its version. If Some(version), converts the document to the specified PDF version (e.g., 14 for PDF 1.4).

Returns

• PdfiumResult<()> - Ok(()) on success, or an error if file creation fails or the PDF save operation encounters an issue.

Examples

// Save to current directory preserving original PDF version
document.save_to_path("document.pdf", None)?;

// Save as PDF 1.4 to a specific path
document.save_to_path("document_v14.pdf", Some(14))?;

Errors

This function can fail if:

• The file cannot be created (permissions, invalid path, disk full, etc.)
• The underlying PDF save operation fails (corrupt document, unsupported features, etc.)

Examples found in repository

examples/import_pages.rs (line 64)

pub fn example_import_pages() -> PdfiumResult<()> {
    // Create a new, empty PDF document that will serve as our destination
    // This document starts with 0 pages and we'll add pages to it
    let document = PdfiumDocument::new()?;

    // Load the source PDF document from which we'll extract pages
    // The second parameter (None) means we're not providing a password
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import specific pages from the source document into our destination document
    // Parameters breakdown:
    // - &src_doc: Reference to the source document to import from
    // - "12,14,30-34": String specifying which pages to import
    //   * Page 12 (individual page)
    //   * Page 14 (individual page)
    //   * Pages 30-34 (range of 5 pages: 30, 31, 32, 33, 34)
    //   * Total: 7 pages will be imported
    // - 0: Index position where imported pages should be inserted
    //   * 0 means insert at the beginning of the destination document
    //   * If the destination had existing pages, imported pages would be inserted before them
    document.pages().import(&src_doc, "12,14,30-34", 0)?;

    // Save the destination document with imported pages to a new file
    // The second parameter (None) indicates we're not specifying a version
    document.save_to_path("pride-1.pdf", None)?;

    // Verification step: reload the saved document to confirm the operation
    let document = PdfiumDocument::new_from_path("pride-1.pdf", None)?;

    // Get the total number of pages in the saved document
    let page_count = document.page_count();

    // Assert that we have exactly 7 pages as expected
    // This confirms that all specified pages were imported correctly:
    // 1 page (12) + 1 page (14) + 5 pages (30-34) = 7 pages total
    assert_eq!(page_count, 7);

    Ok(())
}

/// Demonstrates importing PDF pages using index-based page specification.
///
/// This function shows an alternative approach to page importing using
/// explicit page indices rather than string specifications. This method
/// provides more programmatic control and is useful when:
/// - You have a dynamically generated list of page numbers
/// - You need to import non-contiguous pages with complex patterns
/// - You're working with 0-based indexing in your application logic
///
/// Key differences from string-based approach:
/// - Uses 0-based indexing (first page is index 0)
/// - Requires explicit specification of each page index
/// - More verbose but offers precise control
/// - Better for programmatic generation of page lists
pub fn example_import_pages_by_index() -> PdfiumResult<()> {
    // Create a new, empty PDF document to serve as our destination
    let document = PdfiumDocument::new()?;

    // Load the same source PDF document as in the previous example
    // We're extracting the same pages but using a different method
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import pages using explicit 0-based indices
    // Parameters breakdown:
    // - &src_doc: Reference to the source document
    // - Some(&[11, 13, 29, 30, 31, 32, 33]): Vector of 0-based page indices
    //   * Index 11 = Page 12 in human numbering (11 + 1 = 12)
    //   * Index 13 = Page 14 in human numbering (13 + 1 = 14)
    //   * Indices 29-33 = Pages 30-34 in human numbering
    //   * Note: This matches exactly the same pages as "12,14,30-34" from the previous example
    //   * The Some() wrapper indicates we're providing a specific list of indices
    //   * Using None instead would import all pages from the source document
    // - 0: Insertion position (beginning of destination document)
    document
        .pages()
        .import_by_index(&src_doc, Some(&[11, 13, 29, 30, 31, 32, 33]), 0)?;

    // Save the document with a different filename to distinguish from the first example
    // Even though the content should be identical, using different names helps with testing
    document.save_to_path("pride-2.pdf", None)?;

    // Verification: reload the saved document to ensure it was created correctly
    let document = PdfiumDocument::new_from_path("pride-2.pdf", None)?;

    // Count the pages in the saved document
    let page_count = document.page_count();

    // Verify that we have the same 7 pages as the string-based method
    // This confirms both methods produce identical results:
    // - 1 page at index 11 (page 12)
    // - 1 page at index 13 (page 14)
    // - 5 pages at indices 29-33 (pages 30-34)
    // Total: 7 pages
    assert_eq!(page_count, 7);

    Ok(())
}

pub fn save_to_bytes(&self, version: Option<i32>) -> PdfiumResult<Vec<u8>>

Saves this PdfiumDocument to a byte vector in memory.

This method is useful when you need the PDF data as bytes rather than writing directly to a file. Common use cases include:

• Serving PDF content over HTTP without creating temporary files
• Storing PDF data in a database as a BLOB
• Further processing the PDF bytes (compression, encryption, etc.)
• Testing scenarios where you want to verify PDF content

Arguments

• version - Optional PDF version to save as. If None, preserves the original document’s PDF version. If Some(version), converts to the specified version (e.g., 17 for PDF 1.7).

Returns

• PdfiumResult<Vec<u8>> - On success, returns a Vec<u8> containing the complete PDF file data. On failure, returns a PdfiumResult error.

Memory Considerations

The entire PDF is loaded into memory, so this method may use significant RAM for large documents. Consider save_to_writer() with a streaming writer for very large PDFs.

Examples

// Get PDF bytes preserving original version
let pdf_bytes = document.save_to_bytes(None)?;

// Convert to PDF 1.5 and get bytes
let pdf_v15_bytes = document.save_to_bytes(Some(15))?;

// Use the bytes (e.g., send over HTTP)
response.set_body(pdf_bytes);

pub fn save_to_writer<W: Write + 'static>( &self, writer: W, version: Option<i32>, ) -> PdfiumResult<Box<W>>

Writes this PdfiumDocument to the given writer.

This is the core implementation method that all other save methods delegate to. It accepts any type that implements the Write trait, providing maximum flexibility for different output destinations (files, network streams, in-memory buffers, etc.).

The method wraps the provided writer in a PdfiumWriter, which handles the low-level details of interfacing with the Pdfium C library, such as:

• Implements the callback interface expected by Pdfium’s C API
• Handles buffering and error propagation
• Manages the lifetime and ownership of the underlying writer

Arguments

• writer - Any type implementing Write + ’static. The ’static lifetime bound ensures the writer can be stored and moved around safely without lifetime issues. Common types include File, TcpStream, Cursor<Vec<u8>>, etc.
• version - Optional PDF version specification:
  • None: Save as copy preserving original document version and structure
  • Some(version): Convert document to specified PDF version (10-20 typical range)

Returns

• PdfiumResult<Box<W>> - On success, returns the original writer wrapped in a Box. This allows you to continue using the writer after the save operation completes (e.g., to write additional data).

PDF Version Notes

PDF versions are typically specified as integers:

• 10 = PDF 1.0, 11 = PDF 1.1, …, 17 = PDF 1.7, 20 = PDF 2.0
• Converting to an older version may lose features not supported in that version
• Converting to a newer version may enable additional features but reduce compatibility

Examples

// Save to a file
let file = File::create("document.pdf")?;
let file = document.save_to_writer(file, None)?;

// Save to a network stream
let stream = TcpStream::connect("server:8080")?;
let stream = document.save_to_writer(stream, Some(17))?;

// Save to memory buffer
let buffer = Cursor::new(Vec::new());
let buffer = document.save_to_writer(buffer, None)?;

Implementation Details

The method uses the Pdfium library’s C API functions:

• FPDF_SaveWithVersion() - When a specific version is requested
• FPDF_SaveAsCopy() - When preserving the original version

Both functions use a callback-based approach where Pdfium calls back into our PdfiumWriter to actually write the data chunks as they’re generated.

pub fn page_count(&self) -> i32

Returns the number of pages in this PdfiumDocument.

Examples found in repository

examples/import_pages.rs (line 70)

pub fn example_import_pages() -> PdfiumResult<()> {
    // Create a new, empty PDF document that will serve as our destination
    // This document starts with 0 pages and we'll add pages to it
    let document = PdfiumDocument::new()?;

    // Load the source PDF document from which we'll extract pages
    // The second parameter (None) means we're not providing a password
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import specific pages from the source document into our destination document
    // Parameters breakdown:
    // - &src_doc: Reference to the source document to import from
    // - "12,14,30-34": String specifying which pages to import
    //   * Page 12 (individual page)
    //   * Page 14 (individual page)
    //   * Pages 30-34 (range of 5 pages: 30, 31, 32, 33, 34)
    //   * Total: 7 pages will be imported
    // - 0: Index position where imported pages should be inserted
    //   * 0 means insert at the beginning of the destination document
    //   * If the destination had existing pages, imported pages would be inserted before them
    document.pages().import(&src_doc, "12,14,30-34", 0)?;

    // Save the destination document with imported pages to a new file
    // The second parameter (None) indicates we're not specifying a version
    document.save_to_path("pride-1.pdf", None)?;

    // Verification step: reload the saved document to confirm the operation
    let document = PdfiumDocument::new_from_path("pride-1.pdf", None)?;

    // Get the total number of pages in the saved document
    let page_count = document.page_count();

    // Assert that we have exactly 7 pages as expected
    // This confirms that all specified pages were imported correctly:
    // 1 page (12) + 1 page (14) + 5 pages (30-34) = 7 pages total
    assert_eq!(page_count, 7);

    Ok(())
}

/// Demonstrates importing PDF pages using index-based page specification.
///
/// This function shows an alternative approach to page importing using
/// explicit page indices rather than string specifications. This method
/// provides more programmatic control and is useful when:
/// - You have a dynamically generated list of page numbers
/// - You need to import non-contiguous pages with complex patterns
/// - You're working with 0-based indexing in your application logic
///
/// Key differences from string-based approach:
/// - Uses 0-based indexing (first page is index 0)
/// - Requires explicit specification of each page index
/// - More verbose but offers precise control
/// - Better for programmatic generation of page lists
pub fn example_import_pages_by_index() -> PdfiumResult<()> {
    // Create a new, empty PDF document to serve as our destination
    let document = PdfiumDocument::new()?;

    // Load the same source PDF document as in the previous example
    // We're extracting the same pages but using a different method
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import pages using explicit 0-based indices
    // Parameters breakdown:
    // - &src_doc: Reference to the source document
    // - Some(&[11, 13, 29, 30, 31, 32, 33]): Vector of 0-based page indices
    //   * Index 11 = Page 12 in human numbering (11 + 1 = 12)
    //   * Index 13 = Page 14 in human numbering (13 + 1 = 14)
    //   * Indices 29-33 = Pages 30-34 in human numbering
    //   * Note: This matches exactly the same pages as "12,14,30-34" from the previous example
    //   * The Some() wrapper indicates we're providing a specific list of indices
    //   * Using None instead would import all pages from the source document
    // - 0: Insertion position (beginning of destination document)
    document
        .pages()
        .import_by_index(&src_doc, Some(&[11, 13, 29, 30, 31, 32, 33]), 0)?;

    // Save the document with a different filename to distinguish from the first example
    // Even though the content should be identical, using different names helps with testing
    document.save_to_path("pride-2.pdf", None)?;

    // Verification: reload the saved document to ensure it was created correctly
    let document = PdfiumDocument::new_from_path("pride-2.pdf", None)?;

    // Count the pages in the saved document
    let page_count = document.page_count();

    // Verify that we have the same 7 pages as the string-based method
    // This confirms both methods produce identical results:
    // - 1 page at index 11 (page 12)
    // - 1 page at index 13 (page 14)
    // - 5 pages at indices 29-33 (pages 30-34)
    // Total: 7 pages
    assert_eq!(page_count, 7);

    Ok(())
}

pub fn page(&self, index: i32) -> PdfiumResult<PdfiumPage>

Returns the PdfiumPage indicated by index from this PdfiumDocument.

Examples found in repository

examples/text_extract_search.rs (line 85)

pub fn example_search() -> PdfiumResult<()> {
    // Load the PDF document to search within
    let document = PdfiumDocument::new_from_path("resources/groningen.pdf", None)?;

    // Get the first page (index 0) for searching
    let page = document.page(0)?;

    // Extract text objects from the page for searching
    let text = page.text()?;

    // Search for "amsterdam" with case-insensitive matching
    // PdfiumSearchFlags::empty() means no special search flags (case-insensitive by default)
    // The last parameter (0) is the starting position for the search
    let search = text.find("amsterdam", PdfiumSearchFlags::empty(), 0);
    println!("Found amsterdam {} times", search.count());

    // Search for "groningen" with case-insensitive matching
    let search = text.find("groningen", PdfiumSearchFlags::empty(), 0);
    println!(
        "Found groningen {} times (case insensitive)",
        search.count()
    );

    // Search for "Groningen" with case-sensitive matching
    // MATCH_CASE flag enforces exact case matching
    let search = text.find("Groningen", PdfiumSearchFlags::MATCH_CASE, 0);
    println!("Found Groningen {} times (case sensitive)", search.count());

    // Perform another case-insensitive search to iterate through results
    let search = text.find("groningen", PdfiumSearchFlags::empty(), 0);

    // Iterate through each search result to extract detailed information
    for result in search {
        // Extract the text fragment at the found position
        // result.index() gives the character position where the match starts
        // result.count() gives the length of the matched text
        let fragment = text.extract(result.index(), result.count());
        println!(
            "Found groningen (case insensitive) at {}, fragment = '{fragment}'",
            result.index()
        );
    }

    // Expected output:
    //
    // Found amsterdam 0 times
    // Found groningen 5 times (case insensitive)
    // Found Groningen 5 times (case sensitive)
    // Found groningen (case insensitive) at 14, fragment = 'Groningen'
    // Found groningen (case insensitive) at 232, fragment = 'Groningen'
    // Found groningen (case insensitive) at 475, fragment = 'Groningen'
    // Found groningen (case insensitive) at 920, fragment = 'Groningen'
    // Found groningen (case insensitive) at 1050, fragment = 'Groningen'

    Ok(())
}

pub fn pages(&self) -> PdfiumPages<'_>

Return an Iterator for the pages in this PdfiumDocument.

Examples found in repository

examples/import_pages.rs (line 60)

pub fn example_import_pages() -> PdfiumResult<()> {
    // Create a new, empty PDF document that will serve as our destination
    // This document starts with 0 pages and we'll add pages to it
    let document = PdfiumDocument::new()?;

    // Load the source PDF document from which we'll extract pages
    // The second parameter (None) means we're not providing a password
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import specific pages from the source document into our destination document
    // Parameters breakdown:
    // - &src_doc: Reference to the source document to import from
    // - "12,14,30-34": String specifying which pages to import
    //   * Page 12 (individual page)
    //   * Page 14 (individual page)
    //   * Pages 30-34 (range of 5 pages: 30, 31, 32, 33, 34)
    //   * Total: 7 pages will be imported
    // - 0: Index position where imported pages should be inserted
    //   * 0 means insert at the beginning of the destination document
    //   * If the destination had existing pages, imported pages would be inserted before them
    document.pages().import(&src_doc, "12,14,30-34", 0)?;

    // Save the destination document with imported pages to a new file
    // The second parameter (None) indicates we're not specifying a version
    document.save_to_path("pride-1.pdf", None)?;

    // Verification step: reload the saved document to confirm the operation
    let document = PdfiumDocument::new_from_path("pride-1.pdf", None)?;

    // Get the total number of pages in the saved document
    let page_count = document.page_count();

    // Assert that we have exactly 7 pages as expected
    // This confirms that all specified pages were imported correctly:
    // 1 page (12) + 1 page (14) + 5 pages (30-34) = 7 pages total
    assert_eq!(page_count, 7);

    Ok(())
}

/// Demonstrates importing PDF pages using index-based page specification.
///
/// This function shows an alternative approach to page importing using
/// explicit page indices rather than string specifications. This method
/// provides more programmatic control and is useful when:
/// - You have a dynamically generated list of page numbers
/// - You need to import non-contiguous pages with complex patterns
/// - You're working with 0-based indexing in your application logic
///
/// Key differences from string-based approach:
/// - Uses 0-based indexing (first page is index 0)
/// - Requires explicit specification of each page index
/// - More verbose but offers precise control
/// - Better for programmatic generation of page lists
pub fn example_import_pages_by_index() -> PdfiumResult<()> {
    // Create a new, empty PDF document to serve as our destination
    let document = PdfiumDocument::new()?;

    // Load the same source PDF document as in the previous example
    // We're extracting the same pages but using a different method
    let src_doc = PdfiumDocument::new_from_path("resources/pg1342-images-3.pdf", None)?;

    // Import pages using explicit 0-based indices
    // Parameters breakdown:
    // - &src_doc: Reference to the source document
    // - Some(&[11, 13, 29, 30, 31, 32, 33]): Vector of 0-based page indices
    //   * Index 11 = Page 12 in human numbering (11 + 1 = 12)
    //   * Index 13 = Page 14 in human numbering (13 + 1 = 14)
    //   * Indices 29-33 = Pages 30-34 in human numbering
    //   * Note: This matches exactly the same pages as "12,14,30-34" from the previous example
    //   * The Some() wrapper indicates we're providing a specific list of indices
    //   * Using None instead would import all pages from the source document
    // - 0: Insertion position (beginning of destination document)
    document
        .pages()
        .import_by_index(&src_doc, Some(&[11, 13, 29, 30, 31, 32, 33]), 0)?;

    // Save the document with a different filename to distinguish from the first example
    // Even though the content should be identical, using different names helps with testing
    document.save_to_path("pride-2.pdf", None)?;

    // Verification: reload the saved document to ensure it was created correctly
    let document = PdfiumDocument::new_from_path("pride-2.pdf", None)?;

    // Count the pages in the saved document
    let page_count = document.page_count();

    // Verify that we have the same 7 pages as the string-based method
    // This confirms both methods produce identical results:
    // - 1 page at index 11 (page 12)
    // - 1 page at index 13 (page 14)
    // - 5 pages at indices 29-33 (pages 30-34)
    // Total: 7 pages
    assert_eq!(page_count, 7);

    Ok(())
}

examples/text_extract_search.rs (line 30)

pub fn example_extract_text() -> PdfiumResult<()> {
    // Load the PDF document from the specified file path
    // The second parameter (None) indicates no password is required
    let document = PdfiumDocument::new_from_path("resources/chapter1.pdf", None)?;

    // Iterate through all pages in the document
    // enumerate() provides both the index and the page object
    for (index, page) in document.pages().enumerate() {
        // Extract the full text content from the current page
        // The ?. operators handle potential errors at each step:
        // - page? ensures the page loaded successfully
        // - .text()? extracts text objects from the page
        // - .full() gets the complete text content as a string
        let text = page?.text()?.full();

        // Print formatted output for each page
        println!("Page {}", index + 1); // Pages are 1-indexed for user display
        println!("------");
        println!("{text}");
        println!() // Empty line for separation between pages
    }

    // Expected output:
    //
    // Page 1
    // ------
    //
    // Page 2
    // ------
    // Ruskin
    // House.
    // 156. Charing
    // Cross Road.
    // London
    // George Allen.
    //
    // Page 3
    // ------
    //
    // Page 4
    // ------
    // I
    // Chapter I.
    // T is a truth universally acknowledged, that a single man in possession of a good
    // fortune must be in want of a wife.
    // However little known the feelings or views of such a man may be on his first
    // entering a neighbourhood, this truth is so well fixed in the minds of the surrounding
    // families, that he is considered as the rightful property of some one or other of their
    // daughters.
    // “My dear Mr. Bennet,” said his lady to him one day, “have you heard that
    // Netherfield Park is let at last?”
    // ...

    Ok(())
}

examples/export_pages.rs (line 45)

pub fn example_export_pages_to_images() -> PdfiumResult<()> {
    // Load the PDF document from the specified file path
    // Parameters:
    // - "resources/groningen.pdf": Path to the PDF file (relative to current working directory)
    // - None: No password required for this PDF (use Some("password") if needed)
    let document = PdfiumDocument::new_from_path("resources/groningen.pdf", None)?;

    // Iterate through all pages in the document
    // document.pages() returns an iterator over all pages
    // enumerate() adds an index counter starting from 0
    // This gives us both the page object and its 0-based index
    for (index, page) in document.pages().enumerate() {
        // Render the current page as a bitmap image
        // This is where the PDF content gets converted to a raster image
        //
        // In the configuration we only specify the height in pixels. The width will be calculated
        // automatically to maintain aspect ratio.
        let config = PdfiumRenderConfig::new().with_height(1080);
        let bitmap = page?.render(&config)?;

        // Verify that the bitmap was rendered at the requested height
        // This assertion ensures the rendering process worked as expected
        // If this fails, it indicates a bug in the rendering logic
        assert_eq!(bitmap.height(), 1080);

        // Generate a unique filename for this page
        // Format: "groningen-page-{page_number}.jpg"
        // - index + 1 converts from 0-based index to 1-based page numbers
        //   * Page 0 becomes "groningen-page-1.jpg"
        //   * Page 1 becomes "groningen-page-2.jpg", etc.
        // - The .jpg extension indicates JPEG format will be used
        let filename = format!("groningen-page-{}.jpg", index + 1);

        // Save the rendered bitmap to disk as a JPEG image
        // Parameters:
        // - &filename: Reference to the generated filename string
        // - image::ImageFormat::Jpeg: Specifies JPEG compression format
        //   * Alternative format: Png (lossless)
        //   * JPEG provides good compression but is lossy (some quality loss)
        //
        // The save operation handles:
        // - Converting from BGRA format to JPEG-compatible format
        // - Applying JPEG compression
        // - Writing the file to disk
        bitmap.save(&filename, image::ImageFormat::Jpeg)?;

        // Note: No explicit cleanup needed - Rust's ownership system automatically
        // deallocates the bitmap memory when it goes out of scope at the end of this iteration
    }

    // Return success - all pages have been successfully exported
    Ok(())
}

Trait Implementations

impl Clone for PdfiumDocument

fn clone(&self) -> PdfiumDocument

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PdfiumDocument

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

Formats the value using the given formatter.

impl From<&PdfiumDocument> for FPDF_DOCUMENT

fn from(value: &PdfiumDocument) -> Self

Converts to this type from the input type.