Comment, ChangeLog, release note for new contribution

3 files changed, 16 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 7276db09..0c129e04 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2022-02-06  Jay Berkenbilt  <ejb@ql.org>
+
+	* From m-holger: add getKeyIfDict(), which calls getKey for
+	dictionaries and returns null if called on null. This is for
+	easier access to optional, lower-level dictionaries.
+
 2022-02-05  Jay Berkenbilt  <ejb@ql.org>
 
 	* Add several new accessors to QPDFObjectHandle: the bool
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index 59e58544..adb3fdd9 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -810,6 +810,9 @@ class QPDFObjectHandle
     // returned.
     QPDF_DLL
     QPDFObjectHandle getKey(std::string const&);
+    // If the object is null, return null. Otherwise, call getKey().
+    // This makes it easier to access lower-level dictionaries, as in
+    // auto font = page.getKeyIfDict("/Resources").getKeyIfDict("/Font");
     QPDF_DLL
     QPDFObjectHandle getKeyIfDict(std::string const&);
     // Return all keys.  Keys with null values are treated as if
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 44974c1d..19e172e8 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -129,6 +129,13 @@ For a detailed list of changes, please see the file
       ``qpdf_oh_is_name_and_equals``. Thanks to M. Holger for the
       contribution.
 
+    - New convenience method in ``QPDFObjectHandle``: ``getKeyIfDict``
+      returns null when called on null and otherwise calls ``getKey``.
+      This makes it easier to access optional, lower-level
+      dictionaries. It is exposed in the C API
+      ``qpdf_oh_get_key_if_dict``. Thanks to M. Holger for the
+      contribution.
+
     - New functions added to ``QUtil``: ``make_shared_cstr`` and
       ``make_unique_cstr`` copy ``std::string`` to
       ``std::shared_ptr<char>`` and ``std::unique_ptr<char[]>``. These