rpdfium_edit/

object_ctx.rs

// rpdfium-specific: no upstream equivalent.
// This module resolves a PDFium API naming collision in Rust.

//! Context types for namespaced page-object and annotation-object access.
//!
//! # Background — the naming collision
//!
//! PDFium's C API contains two groups of functions whose names differ only in
//! the prefix that identifies the context (page vs. annotation):
//!
//! | PDFium function         | snake_case alias | Context |
//! |-------------------------|------------------|---------|
//! | `FPDFPage_GetObject`    | `get_object`     | page    |
//! | `FPDFAnnot_GetObject`   | `get_object`     | annot   |
//! | `FPDFPage_RemoveObject` | `remove_object`  | page    |
//! | `FPDFAnnot_RemoveObject`| `remove_object`  | annot   |
//!
//! In C the disambiguation is implicit: the first argument type tells you
//! which group you are calling.  In Rust we cannot define two methods with
//! the same name on a single `EditDocument` struct, so we use *context
//! types* instead.
//!
//! # Solution — context types
//!
//! Each context type is a lightweight wrapper that carries an immutable or
//! mutable borrow of `EditDocument` together with the "which page / which
//! annotation" key.  Once you have a context value you call the same
//! upstream names (`get_object`, `remove_object`, …) on it, and the Rust
//! type system selects the correct implementation.
//!
//! ```text
//! // Page-object side
//! let ctx = doc.page_objects(page_index);
//! let bytes = ctx.get_object(obj_index)?;   // FPDFPage_GetObject
//! let count = ctx.count_objects()?;         // FPDFPage_CountObjects
//!
//! let mut ctx = doc.page_objects_mut(page_index);
//! ctx.remove_object(obj_index)?;            // FPDFPage_RemoveObject
//! ctx.insert_object(new_obj)?;              // FPDFPage_InsertObject
//!
//! // Annotation-object side
//! let ctx = doc.annot_objects(annot_id);
//! let obj = ctx.get_object(0);             // FPDFAnnot_GetObject
//! let n   = ctx.get_object_count();        // FPDFAnnot_GetObjectCount
//!
//! let mut ctx = doc.annot_objects_mut(annot_id);
//! ctx.remove_object(0)?;                   // FPDFAnnot_RemoveObject
//! ctx.append_object(new_obj)?;             // FPDFAnnot_AppendObject
//! ```
//!
//! # ADR-019 alignment
//!
//! All methods named after upstream functions are ADR-019 Tier-2 aliases:
//! they are `#[inline]`, accept no extra arguments, and delegate directly to
//! the corresponding Tier-1 primary on `EditDocument`.  The context type
//! itself supplies the context argument that upstream passes as a first
//! parameter.

use rpdfium_parser::object::ObjectId;

use crate::document::EditDocument;
use crate::error::EditError;
use crate::page_object::PageObject;

// ── Page-object context (immutable) ──────────────────────────────────────────

/// Immutable context for accessing page objects on a single page.
///
/// Obtained via [`EditDocument::page_objects()`].
///
/// This type exists solely to provide correctly-namespaced ADR-019 T2 aliases
/// for `FPDFPage_*` object functions, which otherwise collide with the
/// `FPDFAnnot_*` aliases of the same snake_case name on `EditDocument`.
///
/// # Example
/// ```no_run
/// # use rpdfium_edit::document::EditDocument;
/// # fn example(doc: &EditDocument) {
/// let ctx = doc.page_objects(0);
/// let count = ctx.count_objects().unwrap();
/// let bytes = ctx.get_object(0).unwrap();
/// # }
/// ```
pub struct PageObjectCtx<'doc> {
    /// Borrowed document — all data lives in the document.
    doc: &'doc EditDocument,
    /// Which page these objects belong to.
    page_index: usize,
}

impl<'doc> PageObjectCtx<'doc> {
    // ── constructors (called by EditDocument entry points below) ─────────────

    pub(crate) fn new(doc: &'doc EditDocument, page_index: usize) -> Self {
        Self { doc, page_index }
    }

    // ── T2 aliases (upstream names) ───────────────────────────────────────────

    /// Returns a copy of the raw content bytes for the page object at `index`.
    ///
    /// Each object inserted via [`EditDocument::insert_page_object()`] is
    /// serialised as a `q … Q` (graphic-state save/restore) block.  This
    /// method returns the bytes of the block at position `index`.
    ///
    /// Returns [`EditError::InvalidObjectIndex`] if `index` is out of bounds.
    ///
    /// ADR-019 T2 alias for `FPDFPage_GetObject`.  Namespaced here to avoid
    /// collision with the `FPDFAnnot_GetObject` alias on `EditDocument`.
    ///
    /// See also [`AnnotObjectCtx::get_object()`] for the annotation side.
    #[inline]
    pub fn get_object(&self, index: usize) -> Result<Vec<u8>, EditError> {
        self.doc.page_object_at(self.page_index, index)
    }

    /// Returns the number of page objects on this page.
    ///
    /// ADR-019 T2 alias for `FPDFPage_CountObjects`.
    #[inline]
    pub fn count_objects(&self) -> Result<usize, EditError> {
        self.doc.page_object_count(self.page_index)
    }
}

// ── Page-object context (mutable) ────────────────────────────────────────────

/// Mutable context for accessing page objects on a single page.
///
/// Obtained via [`EditDocument::page_objects_mut()`].
///
/// Provides both read and write access.  Immutable methods delegate through
/// an auto-reborrow so you can mix reads and writes without giving up the
/// context.
///
/// # Example
/// ```no_run
/// # use rpdfium_edit::{document::EditDocument, page_object::PageObject};
/// # fn example(doc: &mut EditDocument, new_obj: PageObject) {
/// let mut ctx = doc.page_objects_mut(0);
/// ctx.insert_object(new_obj).unwrap();
/// ctx.remove_object(0).unwrap();
/// # }
/// ```
pub struct PageObjectCtxMut<'doc> {
    /// Mutably borrowed document.
    doc: &'doc mut EditDocument,
    /// Which page these objects belong to.
    page_index: usize,
}

impl<'doc> PageObjectCtxMut<'doc> {
    pub(crate) fn new(doc: &'doc mut EditDocument, page_index: usize) -> Self {
        Self { doc, page_index }
    }

    // ── read-only aliases (borrow doc immutably through reborrow) ─────────────

    /// Returns a copy of the raw content bytes for the page object at `index`.
    ///
    /// ADR-019 T2 alias for `FPDFPage_GetObject`.
    #[inline]
    pub fn get_object(&self, index: usize) -> Result<Vec<u8>, EditError> {
        self.doc.page_object_at(self.page_index, index)
    }

    /// Returns the number of page objects on this page.
    ///
    /// ADR-019 T2 alias for `FPDFPage_CountObjects`.
    #[inline]
    pub fn count_objects(&self) -> Result<usize, EditError> {
        self.doc.page_object_count(self.page_index)
    }

    // ── write aliases ─────────────────────────────────────────────────────────

    /// Remove the page object at `index` from this page's content stream.
    ///
    /// ADR-019 T2 alias for `FPDFPage_RemoveObject`.  Namespaced here to
    /// avoid collision with the `FPDFAnnot_RemoveObject` alias on
    /// `EditDocument`.
    ///
    /// See also [`AnnotObjectCtxMut::remove_object()`] for the annotation side.
    #[inline]
    pub fn remove_object(&mut self, index: usize) -> Result<(), EditError> {
        self.doc.remove_page_object(self.page_index, index)
    }

    /// Insert a page object into this page's content stream.
    ///
    /// ADR-019 T2 alias for `FPDFPage_InsertObject`.
    #[inline]
    pub fn insert_object(&mut self, object: PageObject) -> Result<(), EditError> {
        self.doc.insert_page_object(self.page_index, object)
    }
}

// ── Annotation-object context (immutable) ────────────────────────────────────

/// Immutable context for accessing AP-stream objects on a single annotation.
///
/// Obtained via [`EditDocument::annot_objects()`].
///
/// This type mirrors [`PageObjectCtx`] on the annotation side, providing the
/// same upstream-named methods for `FPDFAnnot_*`.
///
/// # Example
/// ```no_run
/// # use rpdfium_edit::document::EditDocument;
/// # use rpdfium_parser::object::ObjectId;
/// # fn example(doc: &EditDocument, annot_id: ObjectId) {
/// let ctx = doc.annot_objects(annot_id);
/// let count = ctx.get_object_count();
/// let obj   = ctx.get_object(0);
/// # }
/// ```
pub struct AnnotObjectCtx<'doc> {
    /// Borrowed document — AP objects live in `EditDocument::ap_objects`.
    doc: &'doc EditDocument,
    /// Which annotation's AP-stream object list to access.
    annot_id: ObjectId,
}

impl<'doc> AnnotObjectCtx<'doc> {
    pub(crate) fn new(doc: &'doc EditDocument, annot_id: ObjectId) -> Self {
        Self { doc, annot_id }
    }

    // ── T2 aliases ────────────────────────────────────────────────────────────

    /// Returns a reference to the AP-stream object at `index`.
    ///
    /// Returns `None` if `index` is out of bounds or no objects have been
    /// appended to this annotation.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_GetObject`.  Namespaced here to avoid
    /// collision with the `FPDFPage_GetObject` alias on `EditDocument`.
    ///
    /// See also [`PageObjectCtx::get_object()`] for the page side.
    #[inline]
    pub fn get_object(&self, index: usize) -> Option<&'doc PageObject> {
        self.doc.annotation_object_at(self.annot_id, index)
    }

    /// Returns the number of AP-stream objects for this annotation.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_GetObjectCount`.
    #[inline]
    pub fn get_object_count(&self) -> usize {
        self.doc.annotation_object_count(self.annot_id)
    }
}

// ── Annotation-object context (mutable) ──────────────────────────────────────

/// Mutable context for accessing AP-stream objects on a single annotation.
///
/// Obtained via [`EditDocument::annot_objects_mut()`].
///
/// # Example
/// ```no_run
/// # use rpdfium_edit::{document::EditDocument, page_object::PageObject};
/// # use rpdfium_parser::object::ObjectId;
/// # fn example(doc: &mut EditDocument, annot_id: ObjectId, obj: PageObject) {
/// let mut ctx = doc.annot_objects_mut(annot_id);
/// ctx.append_object(obj).unwrap();
/// ctx.remove_object(0).unwrap();
/// # }
/// ```
pub struct AnnotObjectCtxMut<'doc> {
    /// Mutably borrowed document.
    doc: &'doc mut EditDocument,
    /// Which annotation's AP-stream object list to modify.
    annot_id: ObjectId,
}

impl<'doc> AnnotObjectCtxMut<'doc> {
    pub(crate) fn new(doc: &'doc mut EditDocument, annot_id: ObjectId) -> Self {
        Self { doc, annot_id }
    }

    // ── read-only aliases ─────────────────────────────────────────────────────

    /// Returns a reference to the AP-stream object at `index`.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_GetObject`.
    #[inline]
    pub fn get_object(&self, index: usize) -> Option<&PageObject> {
        self.doc.annotation_object_at(self.annot_id, index)
    }

    /// Returns the number of AP-stream objects for this annotation.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_GetObjectCount`.
    #[inline]
    pub fn get_object_count(&self) -> usize {
        self.doc.annotation_object_count(self.annot_id)
    }

    // ── write aliases ─────────────────────────────────────────────────────────

    /// Remove the AP-stream object at `index` from this annotation.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_RemoveObject`.  Namespaced here to
    /// avoid collision with the `FPDFPage_RemoveObject` alias on
    /// `EditDocument`.
    ///
    /// See also [`PageObjectCtxMut::remove_object()`] for the page side.
    #[inline]
    pub fn remove_object(&mut self, index: usize) -> Result<(), EditError> {
        self.doc.remove_annotation_object(self.annot_id, index)
    }

    /// Append a page object to this annotation's AP-stream object list.
    ///
    /// ADR-019 T2 alias for `FPDFAnnot_AppendObject`.
    #[inline]
    pub fn append_object(&mut self, object: PageObject) -> Result<(), EditError> {
        self.doc.append_annotation_object(self.annot_id, object)
    }

    /// Returns a mutable reference to the AP-stream object at `index`.
    ///
    /// Returns `None` if `index` is out of bounds.
    ///
    /// There is no upstream `FPDFAnnot_GetObjectMut`; mutable access is
    /// Rust-specific.  This is the canonical way to modify an annotation's
    /// AP-stream objects in-place.
    #[inline]
    pub fn get_object_mut(&mut self, index: usize) -> Option<&mut PageObject> {
        self.doc.annotation_object_at_mut(self.annot_id, index)
    }
}

// ── Entry points on EditDocument ─────────────────────────────────────────────

impl EditDocument {
    // ── Page-object side ──────────────────────────────────────────────────────

    /// Return an immutable context for the page objects on page `page_index`.
    ///
    /// This is the preferred entry point for all `FPDFPage_*` object
    /// operations.  The returned [`PageObjectCtx`] carries `page_index` so
    /// you do not have to pass it to every call.
    ///
    /// # Why a context type?
    ///
    /// `FPDFPage_GetObject` and `FPDFAnnot_GetObject` both strip to the same
    /// `get_object` name under ADR-019.  Rust cannot have two methods with
    /// the same name on one struct, so we disambiguate via context types:
    ///
    /// ```text
    /// doc.page_objects(i).get_object(j)   // → FPDFPage_GetObject
    /// doc.annot_objects(id).get_object(j) // → FPDFAnnot_GetObject
    /// ```
    #[inline]
    pub fn page_objects(&self, page_index: usize) -> PageObjectCtx<'_> {
        PageObjectCtx::new(self, page_index)
    }

    /// Return a mutable context for the page objects on page `page_index`.
    ///
    /// See [`page_objects()`](Self::page_objects) for background.
    #[inline]
    pub fn page_objects_mut(&mut self, page_index: usize) -> PageObjectCtxMut<'_> {
        PageObjectCtxMut::new(self, page_index)
    }

    // ── Annotation-object side ────────────────────────────────────────────────

    /// Return an immutable context for the AP-stream objects on annotation
    /// `annot_id`.
    ///
    /// This is the preferred entry point for `FPDFAnnot_*` object operations.
    ///
    /// ```text
    /// doc.annot_objects(id).get_object(j)  // → FPDFAnnot_GetObject
    /// doc.annot_objects(id).get_object_count() // → FPDFAnnot_GetObjectCount
    /// ```
    #[inline]
    pub fn annot_objects(&self, annot_id: ObjectId) -> AnnotObjectCtx<'_> {
        AnnotObjectCtx::new(self, annot_id)
    }

    /// Return a mutable context for the AP-stream objects on annotation
    /// `annot_id`.
    ///
    /// See [`annot_objects()`](Self::annot_objects) for background.
    #[inline]
    pub fn annot_objects_mut(&mut self, annot_id: ObjectId) -> AnnotObjectCtxMut<'_> {
        AnnotObjectCtxMut::new(self, annot_id)
    }
}