rpdfium_parser/

object.rs

// Derived from PDFium's cpdf_object.h / cpdf_object.cpp
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! PDF object model — ObjectId, StreamData, and the Object enum.

use std::collections::HashMap;

pub use rpdfium_core::error::ObjectId;
use rpdfium_core::{Name, PdfString};

/// Represents the raw (undecoded) data of a PDF stream.
///
/// Stream data is not read or decoded at parse time. Only the byte range
/// within the source data is recorded for later on-demand decoding.
#[derive(Debug, Clone)]
pub enum StreamData {
    /// Undecoded: byte range within source data.
    Raw { offset: u64, length: u64 },
    /// Already decoded/generated data (used by editing operations).
    Decoded { data: Vec<u8> },
}

/// A PDF object value.
///
/// `Object::Reference` holds an unresolved indirect reference — it is **not**
/// recursively resolved at parse time to avoid `OnceLock` deadlocks.
#[derive(Debug, Clone)]
pub enum Object {
    /// The PDF null object.
    Null,
    /// A boolean value.
    Boolean(bool),
    /// An integer number.
    Integer(i64),
    /// A real (floating-point) number.
    Real(f64),
    /// A PDF string (encoding-aware).
    String(PdfString),
    /// A PDF name.
    Name(Name),
    /// An array of objects.
    Array(Vec<Object>),
    /// A dictionary mapping names to objects.
    Dictionary(HashMap<Name, Object>),
    /// A stream object with dictionary metadata and raw data reference.
    Stream {
        dict: HashMap<Name, Object>,
        data: StreamData,
    },
    /// An unresolved indirect reference to another object.
    Reference(ObjectId),
}

impl Object {
    /// Returns the boolean value if this is `Object::Boolean`.
    pub fn as_bool(&self) -> Option<bool> {
        match self {
            Object::Boolean(b) => Some(*b),
            _ => None,
        }
    }

    /// Returns the integer value if this is `Object::Integer`.
    pub fn as_i64(&self) -> Option<i64> {
        match self {
            Object::Integer(n) => Some(*n),
            _ => None,
        }
    }

    /// Returns the floating-point value if this is `Object::Real` or `Object::Integer`.
    pub fn as_f64(&self) -> Option<f64> {
        match self {
            Object::Real(f) => Some(*f),
            Object::Integer(n) => Some(*n as f64),
            _ => None,
        }
    }

    /// Returns a reference to the `PdfString` if this is `Object::String`.
    pub fn as_string(&self) -> Option<&PdfString> {
        match self {
            Object::String(s) => Some(s),
            _ => None,
        }
    }

    /// Returns a reference to the `Name` if this is `Object::Name`.
    pub fn as_name(&self) -> Option<&Name> {
        match self {
            Object::Name(n) => Some(n),
            _ => None,
        }
    }

    /// Returns a reference to the array if this is `Object::Array`.
    pub fn as_array(&self) -> Option<&[Object]> {
        match self {
            Object::Array(a) => Some(a),
            _ => None,
        }
    }

    /// Returns a reference to the dictionary if this is `Object::Dictionary`.
    pub fn as_dict(&self) -> Option<&HashMap<Name, Object>> {
        match self {
            Object::Dictionary(d) => Some(d),
            _ => None,
        }
    }

    /// Returns a reference to the stream dictionary if this is `Object::Stream`.
    pub fn as_stream_dict(&self) -> Option<&HashMap<Name, Object>> {
        match self {
            Object::Stream { dict, .. } => Some(dict),
            _ => None,
        }
    }

    /// Returns the `ObjectId` if this is `Object::Reference`.
    pub fn as_reference(&self) -> Option<ObjectId> {
        match self {
            Object::Reference(id) => Some(*id),
            _ => None,
        }
    }

    /// Returns a mutable reference to the dictionary if this is `Object::Dictionary`.
    pub fn as_dict_mut(&mut self) -> Option<&mut HashMap<Name, Object>> {
        match self {
            Object::Dictionary(d) => Some(d),
            _ => None,
        }
    }

    /// Returns a mutable reference to the array if this is `Object::Array`.
    pub fn as_array_mut(&mut self) -> Option<&mut Vec<Object>> {
        match self {
            Object::Array(a) => Some(a),
            _ => None,
        }
    }

    /// Returns `true` if this is `Object::Null`.
    pub fn is_null(&self) -> bool {
        matches!(self, Object::Null)
    }

    /// Returns `true` if this is `Object::Reference`.
    pub fn is_reference(&self) -> bool {
        matches!(self, Object::Reference(_))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn object_id_display_format() {
        let id = ObjectId::new(42, 0);
        assert_eq!(format!("{}", id), "42 0 R");
    }

    #[test]
    fn object_id_equality() {
        let a = ObjectId::new(1, 0);
        let b = ObjectId::new(1, 0);
        let c = ObjectId::new(1, 1);
        assert_eq!(a, b);
        assert_ne!(a, c);
    }

    #[test]
    fn object_null() {
        let obj = Object::Null;
        assert!(obj.is_null());
        assert_eq!(obj.as_bool(), None);
        assert_eq!(obj.as_i64(), None);
    }

    #[test]
    fn object_boolean() {
        let obj = Object::Boolean(true);
        assert_eq!(obj.as_bool(), Some(true));
        assert_eq!(obj.as_i64(), None);
    }

    #[test]
    fn object_integer() {
        let obj = Object::Integer(42);
        assert_eq!(obj.as_i64(), Some(42));
        assert_eq!(obj.as_f64(), Some(42.0));
        assert_eq!(obj.as_bool(), None);
    }

    #[test]
    #[allow(clippy::approx_constant)]
    fn object_real() {
        let obj = Object::Real(3.14);
        assert_eq!(obj.as_f64(), Some(3.14));
        assert_eq!(obj.as_i64(), None);
    }

    #[test]
    fn object_string() {
        let obj = Object::String(PdfString::from_bytes(b"hello".to_vec()));
        assert!(obj.as_string().is_some());
        assert_eq!(obj.as_string().unwrap().as_bytes(), b"hello");
    }

    #[test]
    fn object_name() {
        let obj = Object::Name(Name::from_bytes(b"Type".to_vec()));
        assert!(obj.as_name().is_some());
    }

    #[test]
    fn object_array() {
        let obj = Object::Array(vec![Object::Integer(1), Object::Integer(2)]);
        assert_eq!(obj.as_array().unwrap().len(), 2);
    }

    #[test]
    fn object_dictionary() {
        let mut dict = HashMap::new();
        dict.insert(
            Name::r#type(),
            Object::Name(Name::from_bytes(b"Catalog".to_vec())),
        );
        let obj = Object::Dictionary(dict);
        assert!(obj.as_dict().is_some());
    }

    #[test]
    fn object_stream() {
        let dict = HashMap::new();
        let data = StreamData::Raw {
            offset: 0,
            length: 100,
        };
        let obj = Object::Stream { dict, data };
        assert!(obj.as_stream_dict().is_some());
    }

    #[test]
    fn object_reference() {
        let id = ObjectId::new(5, 0);
        let obj = Object::Reference(id);
        assert!(obj.is_reference());
        assert_eq!(obj.as_reference(), Some(id));
    }
}