Clarify the modern ways to initialize a string_list. Text roughly
based on the analogous passage from api-strbuf.txt.
Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
---
Documentation/technical/api-string-list.txt | 18 +++++++++++-------
1 files changed, 11 insertions(+), 7 deletions(-)
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 3f575bd..0f0e579 100644
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -9,12 +9,17 @@ because it is not specific to paths.
The caller:
-. Allocates and clears a `struct string_list` variable.
+. Allocates a `struct string_list` variable
-. Initializes the members. You might want to set the flag `strdup_strings`
- if the strings should be strdup()ed. For example, this is necessary
- when you add something like git_path("..."), since that function returns
- a static buffer that will change with the next call to git_path().
+. Initializes the members. A string_list has to be initialized by
+ `string_list_init()` or by `= STRING_LIST_INIT_DUP` or
+ `= STRING_LIST_INIT_NODUP` before it can be used.
++
+Strings in lists initialized with the _DUP variant will be
+automatically strdup()ed on insertion and free()ed on removal.
+For example, this is necessary when you add something like
+git_path("..."), since that function returns a static buffer
+that will change with the next call to git_path().
+
If you need something advanced, you can manually malloc() the `items`
member (you need this if you add things later) and you should set the
@@ -34,10 +39,9 @@ member (you need this if you add things later) and you should set the
Example:
----
-struct string_list list;
+struct string_list list STRING_LIST_INIT_NODUP;
int i;
-memset(&list, 0, sizeof(struct string_list));
string_list_append(&list, "foo");
string_list_append(&list, "bar");
for (i = 0; i < list.nr; i++)
--
1.7.2.3
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html