diff --git a/include/qpdf/ObjectHandle.hh b/include/qpdf/ObjectHandle.hh index 8d8f200..2e2295a 100644 --- a/include/qpdf/ObjectHandle.hh +++ b/include/qpdf/ObjectHandle.hh @@ -85,6 +85,7 @@ namespace qpdf bool contains(std::string const& key) const; size_t erase(std::string const& key); + QPDFObjectHandle& find(std::string const& key) const; bool replace(std::string const& key, QPDFObjectHandle value); QPDFObjectHandle const& operator[](std::string const& key) const; diff --git a/libqpdf/QPDF_Dictionary.cc b/libqpdf/QPDF_Dictionary.cc index b080c0b..d4eccd1 100644 --- a/libqpdf/QPDF_Dictionary.cc +++ b/libqpdf/QPDF_Dictionary.cc @@ -2,6 +2,7 @@ #include #include +#include using namespace std::literals; using namespace qpdf; @@ -29,12 +30,49 @@ BaseHandle::operator[](std::string const& key) const return null_obj; } +/// @brief Checks if the specified key exists in the object. +/// +/// This method determines whether the given key is present in the object by verifying if the +/// associated value is non-null. +/// +/// @param key The key to look for in the object. +/// @return True if the key exists and its associated value is non-null. Otherwise, returns false. bool BaseHandle::contains(std::string const& key) const { return !(*this)[key].null(); } +/// @brief Retrieves the value associated with the given key from dictionary. +/// +/// This method attempts to find the value corresponding to the specified key for objects that can +/// be interpreted as dictionaries. +/// +/// - If the object is a dictionary and the specified key exists, it returns a reference +/// to the associated value. +/// - If the object is not a dictionary or the specified key does not exist, it returns +/// a reference to a static uninitialized object handle. +/// +/// @note Modifying the uninitialized object returned when the key is not found is strictly +/// prohibited. +/// +/// @param key The key whose associated value should be retrieved. +/// @return A reference to the associated value if the key is found or a reference to a static +/// uninitialized object if the key is not found. +QPDFObjectHandle& +BaseHandle::find(std::string const& key) const +{ + static const QPDFObjectHandle null_obj; + qpdf_invariant(!null_obj); + if (auto d = as()) { + auto it = d->items.find(key); + if (it != d->items.end()) { + return it->second; + } + } + return const_cast(null_obj); +} + std::set BaseDictionary::getKeys() {