Clarify the modern ways to initialize a string_list. Text roughly
based on the analogous passage from api-strbuf.txt.
(Note: Based on the demo patch of Jonathan Nieder).
Signed-off-by: Thiago Farina <tfransosi@xxxxxxxxx>
---
Documentation/technical/api-string-list.txt | 24 +++++++++++++++++++++---
1 files changed, 21 insertions(+), 3 deletions(-)
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 3f575bd..1510ee2 100644
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -11,7 +11,14 @@ The caller:
. Allocates and clears a `struct string_list` variable.
-. Initializes the members. You might want to set the flag `strdup_strings`
+. Initializes the members. A string_list has to by `= STRING_LIST_INT_NODUP` or
+ `= STRING_LIST_INIT_DUP` 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 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().
@@ -34,10 +41,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_DUP;
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++)
@@ -52,6 +58,18 @@ However, if you use the list to check if a certain string was added
already, you should not do that (using unsorted_string_list_has_string()),
because the complexity would be quadratic again (but with a worse factor).
+Macros
+------
+
+`STRING_LIST_INIT_NODUP`::
+
+ Initialize the members and set the `strdup_strings` member to 0.
+
+`STRING_LIST_INIT_DUP`::
+
+ Initialize the members and set the `strdup_strings` member to 1.
+
+
Functions
---------
--
1.7.2.3.313.gcd15
--
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