[patch] Add apr_array_clear() API

[Daniel Rall <dl...@apache.org>]

The following patch adds a new apr_array_clear() API.  While a trivial
operation, the minimum (safe) implementation required to clear an
apr_array_header_t is somewhat non-obvious without examining the
source code.  Looping over apr_array_pop() is probably a common
fallback for those who still aren't sure after reading
apr_array_header_t's doc string.  To clarify things, we should instead
present an obvious API.


[[[
Add apr_array_clear() API.

* include/apr_tables.h
* tables/apr_tables.c
  (apr_array_clear): Declare and define new API.

* test/testtable.c
  (a1): Static variable for use across array tests.
  (array_clear): New test for apr_array_clear().
  (testtable): Add array_clear() to the test suite.
]]]

Index: tables/apr_tables.c
===================================================================
--- tables/apr_tables.c	(revision 482732)
+++ tables/apr_tables.c	(working copy)
@@ -90,6 +90,11 @@
     return res;
 }
 
+APR_DECLARE(void) apr_array_clear(apr_array_header_t *arr)
+{
+    arr->nelts = 0;
+}
+
 APR_DECLARE(void *) apr_array_pop(apr_array_header_t *arr)
 {
     if (apr_is_empty_array(arr)) {
Index: test/testtable.c
===================================================================
--- test/testtable.c	(revision 482732)
+++ test/testtable.c	(working copy)
@@ -30,8 +30,18 @@
 #include <string.h>
 #endif
 
+static apr_array_header_t *a1 = NULL;
 static apr_table_t *t1 = NULL;
 
+static void array_clear(abts_case *tc, void *data)
+{
+    a1 = apr_array_make(p, 2, sizeof(const char *));
+    APR_ARRAY_PUSH(a1, const char *) = "foo";
+    APR_ARRAY_PUSH(a1, const char *) = "bar";
+    apr_array_clear(a1);
+    ABTS_INT_EQUAL(tc, 0, a1->nelts);
+}
+
 static void table_make(abts_case *tc, void *data)
 {
     t1 = apr_table_make(p, 5);
@@ -174,6 +184,7 @@
 {
     suite = ADD_SUITE(suite)
 
+    abts_run_test(suite, array_clear, NULL);
     abts_run_test(suite, table_make, NULL);
     abts_run_test(suite, table_get, NULL);
     abts_run_test(suite, table_set, NULL);
Index: include/apr_tables.h
===================================================================
--- include/apr_tables.h	(revision 482732)
+++ include/apr_tables.h	(working copy)
@@ -148,6 +148,14 @@
 APR_DECLARE(void *) apr_array_pop(apr_array_header_t *arr);
 
 /**
+ * Remove all elements from an array.
+ * @param arr The array to remove all elements from.
+ * @remark As the underlying storage is allocated from a pool, no
+ * memory is freed by this operation, but is available for reuse.
+ */
+APR_DECLARE(void) apr_array_clear(apr_array_header_t *arr);
+
+/**
  * Concatenate two arrays together
  * @param dst The destination array, and the one to go first in the combined 
  *            array

Re: [patch] Add apr_array_clear() API

[Paul Querna <ch...@force-elite.com>]

Daniel Rall wrote:
> The following patch adds a new apr_array_clear() API.  While a trivial
> operation, the minimum (safe) implementation required to clear an
> apr_array_header_t is somewhat non-obvious without examining the
> source code.  Looping over apr_array_pop() is probably a common
> fallback for those who still aren't sure after reading
> apr_array_header_t's doc string.  To clarify things, we should instead
> present an obvious API.
> 
> 
> [[[
> Add apr_array_clear() API.
> 
> * include/apr_tables.h
> * tables/apr_tables.c
>   (apr_array_clear): Declare and define new API.
> 
> * test/testtable.c
>   (a1): Static variable for use across array tests.
>   (array_clear): New test for apr_array_clear().
>   (testtable): Add array_clear() to the test suite.
> ]]]

Committed in r538391. Thanks, sorry for the delay :-)

-Paul