[Libguestfs] [nbdkit PATCH 1/2] common/utils: document empty_vector compound literal assignment
We usually zero-initialize vectors like
string_vector names = empty_vector;
Allocating and zeroing separately is frequently useful however. Document
the pattern
string_vector names;
names = (string_vector)empty_vector;
where "(string_vector)empty_vector" is a compound literal.
Link: http://mid.mail-archive.com/20230221183810.vjilfbmj3woqivlj@redhat.com
Suggested-by: Eric Blake <eblake(a)redhat.com>
Signed-off-by: Laszlo Ersek <lersek(a)redhat.com>
---
Notes:
I'll pick this patch to libnbd as well, once merged in nbdkit.
context:-U10
common/utils/vector.h | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/common/utils/vector.h b/common/utils/vector.h
index ac28c0b5363a..7337d26893eb 100644
--- a/common/utils/vector.h
+++ b/common/utils/vector.h
@@ -55,28 +55,34 @@
/* Use of this macro defines a new type called ‘name’ containing an
* extensible vector of ‘type’ elements. For example:
*
* DEFINE_VECTOR_TYPE (string_vector, char *);
*
* defines a new type called ‘string_vector’ as a vector of ‘char *’.
* You can create variables of this type:
*
* string_vector names = empty_vector;
*
+ * or
+ *
+ * string_vector names;
+ * names = (string_vector)empty_vector;
+ *
* where ‘names.ptr[]’ will be an array of strings and ‘names.len’
* will be the number of strings. There are no get/set accessors. To
* iterate over the strings you can use the ‘.ptr’ field directly:
*
* for (size_t i = 0; i < names.len; ++i)
* printf ("%s\n", names.ptr[i]);
*
- * Initializing with ‘empty_vector’ sets ‘.ptr = NULL’ and ‘.len = 0’.
+ * Initializing with ‘empty_vector’, or assigning the compound literal
+ * ‘(string_vector)empty_vector’, sets ‘.ptr = NULL’ and ‘.len = 0’.
*
* DEFINE_VECTOR_TYPE also defines utility functions. For the full
* list see the definition below, but useful functions include:
*
* ‘name’_append (eg. ‘string_vector_append’)
* - Append a new element at the end. This operation is cheap.
*
* ‘name’_insert (eg. ‘string_vector_insert’)
* - Insert a new element at the beginning, middle or end. This
* operation is more expensive because existing elements may need