From 369b8e8097346924b056ebec4298571ee81a2f70 Mon Sep 17 00:00:00 2001
From: m-holger <m.holger@qpdf.org>
Date: Mon, 10 Nov 2025 11:04:27 +0000
Subject: [PATCH] Refactor: rename `getTopLevelField` to `root_field`, update logic for clarity and consistency.

---
 libqpdf/QPDFFormFieldObjectHelper.cc | 13 +++++++------
 libqpdf/qpdf/FormField.hh            | 17 +++++++++++++----
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/libqpdf/QPDFFormFieldObjectHelper.cc b/libqpdf/QPDFFormFieldObjectHelper.cc
index 0fc6190..ee55157 100644
--- a/libqpdf/QPDFFormFieldObjectHelper.cc
+++ b/libqpdf/QPDFFormFieldObjectHelper.cc
@@ -54,24 +54,25 @@ QPDFFormFieldObjectHelper::getParent()
 QPDFFormFieldObjectHelper
 QPDFFormFieldObjectHelper::getTopLevelField(bool* is_different)
 {
-    return Null::if_null(m->getTopLevelField(is_different).oh());
+    return Null::if_null(m->root_field(is_different).oh());
 }
 
 FormField
-FormField::getTopLevelField(bool* is_different)
+FormField::root_field(bool* is_different)
 {
     if (!obj) {
         return {};
     }
-    auto top_field = oh();
+    auto rf = *this;
+    size_t depth = 0; // Don't bother with loop detection until depth becomes suspicious
     QPDFObjGen::set seen;
-    while (seen.add(top_field) && !top_field.getKeyIfDict("/Parent").null()) {
-        top_field = top_field.getKey("/Parent");
+    while (rf.Parent() && (++depth < 10 || seen.add(rf))) {
+        rf = rf.Parent();
         if (is_different) {
             *is_different = true;
         }
     }
-    return {top_field};
+    return rf;
 }
 
 QPDFObjectHandle
diff --git a/libqpdf/qpdf/FormField.hh b/libqpdf/qpdf/FormField.hh
index 9089468..b763caf 100644
--- a/libqpdf/qpdf/FormField.hh
+++ b/libqpdf/qpdf/FormField.hh
@@ -46,10 +46,19 @@ namespace qpdf::impl
             return {get("/Parent")};
         }
 
-        // Return the top-level field for this field. Typically this will be the field itself or its
-        // parent. If is_different is provided, it is set to true if the top-level field is
-        // different from the field itself; otherwise it is set to false.
-        FormField getTopLevelField(bool* is_different = nullptr);
+        /// @brief Returns the top-level field associated with the current field.
+        ///
+        /// The function traverses the hierarchy of parent fields to identify the highest-level
+        /// field in the tree. Typically, this will be the current field itself unless it has a
+        /// parent field. Optionally, it can indicate whether the top-level field is different from
+        /// the current field.
+        ///
+        /// @param is_different A pointer to a boolean that, if provided, will be set to true if the
+        ///        top-level field differs from the current field; otherwise, it will be set to
+        ///        false.
+        ///
+        /// @return The top-level field in the form field hierarchy.
+        FormField root_field(bool* is_different = nullptr);
 
         // Get a field value, possibly inheriting the value from an ancestor node.
         QPDFObjectHandle getInheritableFieldValue(std::string const& name);
--
libgit2 0.21.4