From 9f58e96b6d0235f5187895103312e3cbf950fb55 Mon Sep 17 00:00:00 2001
From: m-holger <m.holger@qpdf.org>
Date: Thu, 4 Sep 2025 11:42:23 +0100
Subject: [PATCH] Introduce private-API `Name` class and update name handling in `QPDFObjectHandle`.

---
 libqpdf/QPDFObjectHandle.cc              | 34 +++++++++++++++++++++++++++-------
 libqpdf/qpdf/QPDFObjectHandle_private.hh | 41 ++++++++++++++++++++++++++++++++++++++++-
 libqpdf/qpdf/QPDFObject_private.hh       |  2 ++
 3 files changed, 69 insertions(+), 8 deletions(-)

diff --git a/libqpdf/QPDFObjectHandle.cc b/libqpdf/QPDFObjectHandle.cc
index 3dd04da..7cae11e 100644
--- a/libqpdf/QPDFObjectHandle.cc
+++ b/libqpdf/QPDFObjectHandle.cc
@@ -952,7 +952,33 @@ QPDFObjectHandle::getValueAsReal(std::string& value) const
     return true;
 }
 
-// Name accessors
+// Name methods
+
+QPDFObjectHandle
+QPDFObjectHandle::newName(std::string const& name)
+{
+    return {QPDFObject::create<QPDF_Name>(name)};
+}
+
+Name::Name(std::string const& name) :
+    BaseHandle(QPDFObject::create<QPDF_Name>(name))
+{
+}
+
+Name::Name(std::string&& name) :
+    BaseHandle(QPDFObject::create<QPDF_Name>(std::move(name)))
+{
+}
+
+std::string const&
+Name::value() const
+{
+    auto* n = as<QPDF_Name>();
+    if (!n) {
+        throw invalid_error("Name");
+    }
+    return n->name;
+}
 
 std::string
 QPDFObjectHandle::getName() const
@@ -1695,12 +1721,6 @@ QPDFObjectHandle::newReal(double value, int decimal_places, bool trim_trailing_z
 }
 
 QPDFObjectHandle
-QPDFObjectHandle::newName(std::string const& name)
-{
-    return {QPDFObject::create<QPDF_Name>(name)};
-}
-
-QPDFObjectHandle
 QPDFObjectHandle::newString(std::string const& str)
 {
     return {QPDFObject::create<QPDF_String>(str)};
diff --git a/libqpdf/qpdf/QPDFObjectHandle_private.hh b/libqpdf/qpdf/QPDFObjectHandle_private.hh
index c213f1b..cca454d 100644
--- a/libqpdf/qpdf/QPDFObjectHandle_private.hh
+++ b/libqpdf/qpdf/QPDFObjectHandle_private.hh
@@ -324,7 +324,7 @@ namespace qpdf
         {
         }
 
-        // Return the integer value. If the object is not a valid integer, throw a
+        // Return the integer value. If the object is not a valid Integer, throw a
         // std::invalid_argument exception. If the object is out of range for the target type,
         // throw a std::overflow_error or std::underflow_error exception.
         template <std::integral T>
@@ -391,6 +391,45 @@ namespace qpdf
         // escaping. Return {false, false} if the name is not valid utf-8, otherwise return {true,
         // true} if no characters require or {true, false} if escaping is required.
         static std::pair<bool, bool> analyzeJSONEncoding(std::string const& name);
+
+        Name() = default;
+        Name(Name const&) = default;
+        Name(Name&&) = default;
+        Name& operator=(Name const&) = default;
+        Name& operator=(Name&&) = default;
+        ~Name() = default;
+
+        explicit Name(std::string const&);
+        explicit Name(std::string&&);
+
+        Name(QPDFObjectHandle const& oh) :
+            BaseHandle(oh.type_code() == ::ot_name ? oh : QPDFObjectHandle())
+        {
+        }
+
+        Name(QPDFObjectHandle&& oh) :
+            BaseHandle(oh.type_code() == ::ot_name ? std::move(oh) : QPDFObjectHandle())
+        {
+        }
+
+        // Return the name value. If the object is not a valid Name, throw a
+        // std::invalid_argument exception.
+        operator std::string() const&
+        {
+            return value();
+        }
+
+        // Return the integer value. If the object is not a valid integer, throw a
+        // std::invalid_argument exception.
+        std::string const& value() const;
+
+        // Return true if object value is equal to the 'rhs' value. Return false if the object is
+        // not a valid Name.
+        friend bool
+        operator==(Name const& lhs, std::string_view rhs)
+        {
+            return lhs && lhs.value() == rhs;
+        }
     };
 
     class Stream final: public BaseHandle
diff --git a/libqpdf/qpdf/QPDFObject_private.hh b/libqpdf/qpdf/QPDFObject_private.hh
index 9dd4b92..03ccad9 100644
--- a/libqpdf/qpdf/QPDFObject_private.hh
+++ b/libqpdf/qpdf/QPDFObject_private.hh
@@ -28,6 +28,7 @@ namespace qpdf
     class BaseDictionary;
     class Dictionary;
     class Integer;
+    class Name;
     class Stream;
 } // namespace qpdf
 
@@ -138,6 +139,7 @@ class QPDF_Name final
 {
     friend class QPDFObject;
     friend class qpdf::BaseHandle;
+    friend class qpdf::Name;
 
     explicit QPDF_Name(std::string name) :
         name(std::move(name))
--
libgit2 0.21.4