[FFmpeg-devel] [PATCH 1/3] avutil/dict: add av_dict_pop

[Marvin Scholz]

This new API allows to remove an entry and obtain ownership of the
key/value that was associated with the removed entry.
---
 doc/APIchanges         |  4 ++++
 libavutil/dict.c       | 27 +++++++++++++++++++++++++++
 libavutil/dict.h       | 20 ++++++++++++++++++++
 libavutil/tests/dict.c | 34 ++++++++++++++++++++++++++++++++++
 libavutil/version.h    |  2 +-
 tests/ref/fate/dict    | 12 ++++++++++++
 6 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/doc/APIchanges b/doc/APIchanges
index 0b609e3d3b..5b807873b7 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -2,6 +2,10 @@ The last version increases of all libraries were on 2023-02-09
 
 API changes, most recent first:
 
+2023-04-29 - xxxxxxxxxx - lavu 58.7.100 - dict.c
+  Add av_dict_pop() to remove an entry from a dict
+  and get ownership of the removed key/value.
+
 2023-04-10 - xxxxxxxxxx - lavu 58.6.100 - frame.h
   av_frame_get_plane_buffer() now accepts const AVFrame*.
 
diff --git a/libavutil/dict.c b/libavutil/dict.c
index f673977a98..ac41771994 100644
--- a/libavutil/dict.c
+++ b/libavutil/dict.c
@@ -173,6 +173,33 @@ int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value,
     return av_dict_set(pm, key, valuestr, flags);
 }
 
+int av_dict_pop(AVDictionary **pm, const char *key,
+                char **out_key, char **out_value, int flags)
+{
+    AVDictionary *m = *pm;
+    AVDictionaryEntry *entry = NULL;
+    entry = (AVDictionaryEntry *)av_dict_get(m, key, NULL, flags);
+    if (!entry)
+        return AVERROR(ENOENT);
+
+    if (out_key)
+        *out_key = entry->key;
+    else
+        av_free(entry->key);
+
+    if (out_value)
+        *out_value = entry->value;
+    else
+        av_free(entry->value);
+
+    *entry = m->elems[--m->count];
+    if (m && !m->count) {
+        av_freep(&m->elems);
+        av_freep(pm);
+    }
+    return 0;
+}
+
 static int parse_key_value_pair(AVDictionary **pm, const char **buf,
                                 const char *key_val_sep, const char *pairs_sep,
                                 int flags)
diff --git a/libavutil/dict.h b/libavutil/dict.h
index 713c9e361a..b2ab55a026 100644
--- a/libavutil/dict.h
+++ b/libavutil/dict.h
@@ -172,6 +172,26 @@ int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags
  */
 int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags);
 
+/**
+ * Remove the entry with the given key from the dictionary.
+ *
+ * Search for an entry matching `key` and remove it, if found. Optionally
+ * the found key and/or value can be returned using the `out_key`/`out_value`
+ * arguments.
+ *
+ * If more than one entry matches, only one entry is removed and returned
+ * on each call. Which entry is returned first in that case is undefined.
+ *
+ * @param pm        Pointer to a pointer to a dictionary struct.
+ * @param key       Entry key to match.
+ * @param out_key   Pointer whose pointee will be set to the matched
+ *                  entry key. Must be freed by the caller. May be NULL.
+ * @param out_value Pointer whose pointee will be set to the matched
+ *                  entry value. Must be freed by the caller. May be NULL.
+ */
+int av_dict_pop(AVDictionary **pm, const char *key,
+                char **out_key, char **out_value, int flags);
+
 /**
  * Parse the key/value pairs list and add the parsed entries to a dictionary.
  *
diff --git a/libavutil/tests/dict.c b/libavutil/tests/dict.c
index bececefb31..0652794b97 100644
--- a/libavutil/tests/dict.c
+++ b/libavutil/tests/dict.c
@@ -158,5 +158,39 @@ int main(void)
     printf("%s\n", e->value);
     av_dict_free(&dict);
 
+    char *key, *val = NULL;
+    int ret;
+    printf("\nTesting av_dict_pop() with existing AVDictionaryEntry.key as key\n");
+    av_dict_set(&dict, "test-key", "test-value", 0);
+    ret = av_dict_pop(&dict, "test-key", &key, &val, 0);
+    printf("%s: %s (Return code: %i)\n",
+        (key) ? key : "(null)",
+        (val) ? val : "(null)", ret);
+    e = av_dict_get(dict, "test-key", NULL, 0);
+    printf("%s\n", (e) ? e->value : "(null)");
+    av_freep(&key);
+    av_freep(&val);
+
+    printf("\nTesting av_dict_pop() with nonexistent key\n");
+    ret = av_dict_pop(&dict, "test-key", &key, &val, 0);
+    printf("%s: %s (Return code: %i)\n",
+        (key) ? key : "(null)",
+        (val) ? val : "(null)", ret);
+    e = av_dict_get(dict, "test-key", NULL, 0);
+    printf("%s\n", (e) ? e->value : "(null)");
+    av_freep(&key);
+    av_freep(&val);
+
+    printf("\nTesting av_dict_pop() with prefix key match\n");
+    av_dict_set(&dict, "prefix-test-key", "test-value", 0);
+    ret = av_dict_pop(&dict, "prefix-test", &key, &val, AV_DICT_IGNORE_SUFFIX);
+    printf("%s: %s (Return code: %i)\n",
+        (key) ? key : "(null)",
+        (val) ? val : "(null)", ret);
+    e = av_dict_get(dict, "prefix-test", NULL, AV_DICT_IGNORE_SUFFIX);
+    printf("%s\n", (e) ? e->value : "(null)");
+    av_freep(&key);
+    av_freep(&val);
+
     return 0;
 }
diff --git a/libavutil/version.h b/libavutil/version.h
index 40f92af055..b8d1ef06a8 100644
--- a/libavutil/version.h
+++ b/libavutil/version.h
@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  58
-#define LIBAVUTIL_VERSION_MINOR   6
+#define LIBAVUTIL_VERSION_MINOR   7
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \
diff --git a/tests/ref/fate/dict b/tests/ref/fate/dict
index 7205e4c845..bdb097cb03 100644
--- a/tests/ref/fate/dict
+++ b/tests/ref/fate/dict
@@ -48,3 +48,15 @@ Testing av_dict_set_int()
 Testing av_dict_set() with existing AVDictionaryEntry.key as key
 new val OK
 new val OK
+
+Testing av_dict_pop() with existing AVDictionaryEntry.key as key
+test-key: test-value (Return code: 0)
+(null)
+
+Testing av_dict_pop() with nonexistent key
+(null): (null) (Return code: -2)
+(null)
+
+Testing av_dict_pop() with prefix key match
+prefix-test-key: test-value (Return code: 0)
+(null)
-- 
2.37.0 (Apple Git-136)