flpdf 0.4.0

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
//! The pre-1.0 flat, configurable-depth outline API was removed in favor of
//! qpdf-compatible [`OutlineTree`] materialization.
//!
//! ```compile_fail
//! use flpdf::outline::{outline_items, outline_items_with_max_depth};
//! ```

use crate::{Object, ObjectRef};
use std::collections::{BTreeMap, VecDeque};
use std::ops::Index;
use std::sync::OnceLock;

/// Stable index of an item within an [`OutlineTree`].
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct OutlineId(pub(crate) usize);

/// One materialized outline item.
#[derive(Debug, Clone, PartialEq)]
pub struct OutlineItem {
    /// Indirect source identity, or `None` for a direct outline value.
    pub source_ref: Option<ObjectRef>,
    /// Parent item in the arena; top-level items have no parent.
    pub parent: Option<OutlineId>,
    /// Child items in raw `/First` then `/Next` order.
    pub kids: Vec<OutlineId>,
    /// Raw object obtained by resolving this outline cursor exactly once.
    pub object: Object,
    /// Decoded `/Title`, or an empty string when unavailable.
    pub title: String,
    /// Raw `/Count` converted to qpdf's signed 32-bit accessor shape.
    pub count: i32,
    /// qpdf-compatible resolved destination, or [`Object::Null`].
    pub dest: Object,
}

impl OutlineItem {
    /// Mirror qpdf `getDestPage()` without resolving the page operand.
    pub fn dest_page(&self) -> Object {
        match &self.dest {
            Object::Array(items) if !items.is_empty() => items[0].clone(),
            _ => Object::Null,
        }
    }
}

/// Arena-backed materialization of a document outline.
#[derive(Debug)]
pub struct OutlineTree {
    pub(crate) items: Vec<OutlineItem>,
    pub(crate) roots: Vec<OutlineId>,
    by_page: OnceLock<BTreeMap<Option<ObjectRef>, Vec<OutlineId>>>,
}

impl OutlineTree {
    pub(crate) fn new() -> Self {
        Self {
            items: Vec::new(),
            roots: Vec::new(),
            by_page: OnceLock::new(),
        }
    }

    fn normalize_page_key(page: Option<ObjectRef>) -> Option<ObjectRef> {
        page.filter(|reference| *reference != ObjectRef::new(0, 0))
    }

    fn page_key(item: &OutlineItem) -> Option<ObjectRef> {
        match item.dest_page() {
            Object::Reference(reference) => Self::normalize_page_key(Some(reference)),
            _ => None,
        }
    }

    fn by_page(&self) -> &BTreeMap<Option<ObjectRef>, Vec<OutlineId>> {
        self.by_page.get_or_init(|| {
            let mut index = BTreeMap::<Option<ObjectRef>, Vec<OutlineId>>::new();
            let mut queue: VecDeque<OutlineId> = self.roots.iter().copied().collect();
            while let Some(id) = queue.pop_front() {
                index.entry(Self::page_key(&self[id])).or_default().push(id);
                queue.extend(self[id].kids.iter().copied());
            }
            index
        })
    }

    /// Return outlines targeting `page` in qpdf breadth-first order.
    ///
    /// `None` represents qpdf's `QPDFObjGen(0, 0)` bucket and therefore also
    /// contains destinations whose page operand is not an indirect reference.
    pub fn outlines_for_page(
        &self,
        page: Option<ObjectRef>,
    ) -> impl Iterator<Item = (OutlineId, &OutlineItem)> {
        self.by_page()
            .get(&Self::normalize_page_key(page))
            .into_iter()
            .flatten()
            .copied()
            .map(|id| (id, &self[id]))
    }

    /// Top-level items in raw `/First` then `/Next` order.
    pub fn roots(&self) -> &[OutlineId] {
        &self.roots
    }

    /// Return an item when `id` belongs to this tree.
    pub fn get(&self, id: OutlineId) -> Option<&OutlineItem> {
        self.items.get(id.0)
    }

    /// Iterate over every item in pre-order, yielding one-based depth.
    pub fn preorder(&self) -> OutlineTreeIter<'_> {
        OutlineTreeIter {
            tree: self,
            stack: self.roots.iter().rev().map(|&id| (1, id)).collect(),
        }
    }
}

impl Index<OutlineId> for OutlineTree {
    type Output = OutlineItem;

    fn index(&self, id: OutlineId) -> &Self::Output {
        &self.items[id.0]
    }
}

/// Lossless pre-order view over an [`OutlineTree`].
pub struct OutlineTreeIter<'a> {
    tree: &'a OutlineTree,
    stack: Vec<(usize, OutlineId)>,
}

impl<'a> Iterator for OutlineTreeIter<'a> {
    type Item = (usize, OutlineId, &'a OutlineItem);

    fn next(&mut self) -> Option<Self::Item> {
        let (depth, id) = self.stack.pop()?;
        let item = &self.tree[id];
        self.stack
            .extend(item.kids.iter().rev().map(|&kid| (depth + 1, kid)));
        Some((depth, id, item))
    }
}