opal/util/json: Add opal_json_get_key_by_index function

Retrieves values from a json object according to their index.

Signed-off-by: Luke Robison <[email protected]>

Author: Luke Robison

opal/util/json/opal_json.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024      Amazon.com, Inc. or its affiliates.
+ * Copyright (c) 2024-2025 Amazon.com, Inc. or its affiliates.
  *                         All Rights reserved.
  * $COPYRIGHT$
  *
@@ -186,6 +186,33 @@ int opal_json_get_key(const opal_json_t *json, const char *key, const opal_json_
     return ret;
 }
 
+int opal_json_get_key_by_index(const opal_json_t *json, const size_t index, const char **key, const opal_json_t **out)
+{
+    int ret = OPAL_ERROR;
+
+    CHECK_OBJ_TYPE(json, OPAL_JSON_OBJECT);
+
+    opal_json_internal_t *in = (opal_json_internal_t *) json;
+    opal_json_internal_t *result = NULL;
+
+    json_object_entry entry = {0};
+
+    if (index < 0 || index >= in->value->u.object.length) {
+        opal_show_help("help-json.txt", "Index out of bound", true, index,
+                       in->value->u.array.length);
+        return ret;
+    }
+    entry = in->value->u.object.values[index];
+    *key = entry.name;
+    ret = opal_json_internal_new(entry.value, &result);
+    if (OPAL_SUCCESS == ret) {
+        *out = (opal_json_t *) result;
+    } else if (result) {
+        opal_json_internal_free(result);
+    }
+    return ret;
+}
+
 void opal_json_free(const opal_json_t **json)
 {
     opal_json_internal_free((struct opal_json_internal_t *) *json);

opal/util/json/opal_json.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024      Amazon.com, Inc. or its affiliates.
+ * Copyright (c) 2024-2025 Amazon.com, Inc. or its affiliates.
  *                         All Rights reserved.
  * $COPYRIGHT$
  *
@@ -123,6 +123,22 @@ OPAL_DECLSPEC int opal_json_get_key(const opal_json_t *json, const char *key,
 OPAL_DECLSPEC int opal_json_get_index(const opal_json_t *json, const size_t index,
                                       const opal_json_t **out);
 
+/**
+ * Get the JSON object and key at index from a JSON object
+ *
+ * @param[in]   json    Parent JSON array
+ * @param[in]   index   Index value
+ * @param[out]  key     The name of the key at the given index. This pointer
+ *                      remains valid for the lifetime of the parent JSON
+ *                      object.  The caller should not free it.
+ * @param[out]  out     Output JSON object at the specified index. This object
+ *                      should be freed by caller with opal_json_free.
+ */
+OPAL_DECLSPEC int
+opal_json_get_key_by_index( const opal_json_t *json, const size_t index,
+                            const char **key, const opal_json_t **out);
+
+
 /**
  * Get the number of objects in a container-type value, i.e. object, array.
  *

test/util/opal_json.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024      Amazon.com, Inc. or its affiliates.
+ * Copyright (c) 2024-2025 Amazon.com, Inc. or its affiliates.
  *                         All Rights reserved.
  * $COPYRIGHT$
  *
@@ -129,7 +129,9 @@ static void test_valid_json(void)
     int ret = 0;
     size_t size;
     const opal_json_t *json = NULL, *a = NULL, *b = NULL, *b0 = NULL, *b1 = NULL, *c = NULL,
-                      *d = NULL;
+                      *d = NULL, *dummy = NULL;
+    const char *found_key;
+
     /**
      * Human readable form:
      * {
@@ -208,6 +210,21 @@ static void test_valid_json(void)
             test_json_double_val(d, 3.456);
         }
 
+        ret = opal_json_get_key_by_index(json, 3, &found_key, &d);
+        if (ret) {
+            test_failure("opal_json_get_key_by_index failed when called with a valid index");
+        } else {
+            if ( 0 != strcmp(found_key, "d") ) {
+                test_failure("opal_json_get_key_by_index returned the wrong key value");
+            }
+            test_json_double_val(d, 3.456);
+        }
+
+        ret = opal_json_get_key_by_index(json, 4, &found_key, &dummy);
+        if (ret == OPAL_SUCCESS) {
+            test_failure("opal_json_get_key_by_index returned OPAL_SUCCESS when passed invalid index.");
+        }
+
         /* JSON objects can be released in any order */
         FREE_JSON(a);
         FREE_JSON(b);