Break out llinventorylistener.cpp's InvResultSet as LL::ResultSet.

We may well want to leverage that API for additional queries that could
potentially return large datasets.

3 files changed, 156 insertions, 0 deletions

diff --git a/indra/llcommon/CMakeLists.txt b/indra/llcommon/CMakeLists.txt
index 8577d94be1..8c346ea6ce 100644
--- a/indra/llcommon/CMakeLists.txt
+++ b/indra/llcommon/CMakeLists.txt
@@ -112,6 +112,7 @@ set(llcommon_SOURCE_FILES
     lockstatic.cpp
     lua_function.cpp
     lualistener.cpp
+    resultset.cpp
     threadpool.cpp
     throttle.cpp
     u64.cpp
@@ -261,6 +262,7 @@ set(llcommon_HEADER_FILES
     lockstatic.h
     lua_function.h
     lualistener.h
+    resultset.h
     stdtypes.h
     stringize.h
     tempset.h
diff --git a/indra/llcommon/resultset.cpp b/indra/llcommon/resultset.cpp
new file mode 100644
index 0000000000..ee8cc68c6c
--- /dev/null
+++ b/indra/llcommon/resultset.cpp
@@ -0,0 +1,93 @@
+/**
+ * @file   resultset.cpp
+ * @author Nat Goodspeed
+ * @date   2024-09-03
+ * @brief  Implementation for resultset.
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+// Precompiled header
+#include "linden_common.h"
+// associated header
+#include "resultset.h"
+// STL headers
+// std headers
+// external library headers
+// other Linden headers
+#include "llerror.h"
+#include "llsdutil.h"
+
+namespace LL
+{
+
+LLSD ResultSet::getKeyLength() const
+{
+    return llsd::array(getKey(), getLength());
+}
+
+std::pair<LLSD, int> ResultSet::getSliceStart(int index, int count) const
+{
+    // only call getLength() once
+    auto length = getLength();
+    // Adjust bounds [start, end) to overlap the actual result set from
+    // [0, getLength()). Permit negative index; e.g. with a result set
+    // containing 5 entries, getSlice(-2, 5) will adjust start to 0 and
+    // end to 3.
+    int start = llclamp(index, 0, length);
+    int end = llclamp(index + count, 0, length);
+    LLSD result{ LLSD::emptyArray() };
+    // beware of count <= 0, or an [index, count) range that doesn't even
+    // overlap [0, length) at all
+    if (end > start)
+    {
+        // right away expand the result array to the size we'll need
+        result[end - 1] = LLSD();
+        for (int i = start; i < end; ++i)
+        {
+            result[i] = getSingle(i);
+        }
+    }
+    return { result, start };
+}
+
+LLSD ResultSet::getSlice(int index, int count) const
+{
+    return getSliceStart(index, count).first;
+}
+
+/*==========================================================================*|
+LLSD ResultSet::getSingle(int index) const
+{
+    if (0 <= index && index < getLength())
+    {
+        return getSingle_(index);
+    }
+    else
+    {
+        return {};
+    }
+}
+|*==========================================================================*/
+
+ResultSet::ResultSet(const std::string& name):
+    mName(name)
+{
+    LL_DEBUGS("Lua") << *this << LL_ENDL;
+}
+
+ResultSet::~ResultSet()
+{
+    // We want to be able to observe that the consuming script eventually
+    // destroys each of these ResultSets.
+    LL_DEBUGS("Lua") << "~" << *this << LL_ENDL;
+}
+
+} // namespace LL
+
+std::ostream& operator<<(std::ostream& out, const LL::ResultSet& self)
+{
+    return out << "ResultSet(" << self.mName << ", " << self.getKey() << ")";
+}
diff --git a/indra/llcommon/resultset.h b/indra/llcommon/resultset.h
new file mode 100644
index 0000000000..9b9ecbb21e
--- /dev/null
+++ b/indra/llcommon/resultset.h
@@ -0,0 +1,61 @@
+/**
+ * @file   resultset.h
+ * @author Nat Goodspeed
+ * @date   2024-09-03
+ * @brief  ResultSet is an abstract base class to allow scripted access to
+ *         potentially large collections representable as LLSD arrays.
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+#if ! defined(LL_RESULTSET_H)
+#define LL_RESULTSET_H
+
+#include "llinttracker.h"
+#include "llsd.h"
+#include <iosfwd>                   // std::ostream
+#include <utility>                  // std::pair
+
+namespace LL
+{
+
+// This abstract base class defines an interface by which a large collection
+// of items representable as an LLSD array can be retrieved in slices. It isa
+// LLIntTracker so we can pass its unique int key to a consuming script via
+// LLSD.
+struct ResultSet: public LLIntTracker<ResultSet>
+{
+    // Get the length of the result set. Indexes are 0-relative.
+    virtual int getLength() const = 0;
+    // Get conventional LLSD { key, length } pair.
+    LLSD getKeyLength() const;
+    // Retrieve LLSD corresponding to a single entry from the result set,
+    // once we're sure the index is valid.
+    virtual LLSD getSingle(int index) const = 0;
+    // Retrieve LLSD corresponding to a "slice" of the result set: a
+    // contiguous sub-array starting at index. The returned LLSD array might
+    // be shorter than count entries if count > MAX_ITEM_LIMIT, or if the
+    // specified slice contains the end of the result set.
+    LLSD getSlice(int index, int count) const;
+    // Like getSlice(), but also return adjusted start position.
+    std::pair<LLSD, int> getSliceStart(int index, int count) const;
+/*==========================================================================*|
+    // Retrieve LLSD corresponding to a single entry from the result set,
+    // with index validation.
+    LLSD getSingle(int index) const;
+|*==========================================================================*/
+
+    /*---------------- the rest is solely for debug logging ----------------*/
+    std::string mName;
+
+    ResultSet(const std::string& name);
+    virtual ~ResultSet();
+};
+
+} // namespace LL
+
+std::ostream& operator<<(std::ostream& out, const LL::ResultSet& self);
+
+#endif /* ! defined(LL_RESULTSET_H) */