threads / patch / 24995

v3string-list: Document STRING_LIST_INIT_* macros.

Subject: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.

## tl;dr

3 messages between Sep 6, 2010 and Sep 6, 2010. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Thiago Farina· Sep 6, 2010, 00:13 UTC · lore

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@gmail.com>
---
 Documentation/technical/api-string-list.txt |   16 ++++++++++------
 1 files changed, 10 insertions(+), 6 deletions(-)
Show changes to Documentation/technical/api-string-list.txt +10 −6
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 3f575bd..f689163 100644
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -11,10 +11,15 @@ The caller:
 
 . Allocates and clears 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 might be initialize 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 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_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++)

-- 
1.7.2.3.313.gcd15
Jonathan Nieder· Sep 6, 2010, 00:22 UTC · re: Thiago Farina · lore

Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.

Thiago Farina wrote:
Show 10 quoted lines
> +++ b/Documentation/technical/api-string-list.txt
> @@ -11,10 +11,15 @@ The caller:
>  
>  . Allocates and clears 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 might be initialize by
s/initialize/initalized/, I think.
Show 7 quoted lines
> +  `= 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 we do not have a string_list_init() function, maybe it is worth mentioning how a person can use

 memset(&list, 0, sizeof(struct string_list));
 list.strdup_strings = 1 or 0;
too?

The previous text tried (too subtly, perhaps) to imply that with the "clears" (for memset) and "might want to set the flag `strdup_strings`" phrases.

Show 12 quoted lines
> @@ -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_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++)

Probably worth copying and pasting this code to another file and trying it to make sure it works for the final draft.

Also, I am afraid I will not be able to send detailed reviews on uncomplicated patches like this one in the future. It simply does not scale (though I like for people to learn, at a certain point it becomes faster to do things myself).

So if you can, it is best to find ways to motivate other people to help with your work, by conveying what problems it will solve (in this case: people might be confused about the initialization sequence; as part of patch 3 demonstrated, the invariants regarding strdup_strings are not being described clearly enough) and finding ways to minimize the time other people have to spend to get it done.

Regards, Jonathan

Thiago Farina· Sep 6, 2010, 00:38 UTC · re: Jonathan Nieder · lore

Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.

On Sun, Sep 5, 2010 at 9:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 15 quoted lines
>> @@ -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_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++)
>
> Probably worth copying and pasting this code to another file and
> trying it to make sure it works for the final draft.
I already done in the test-string-list.c patch I sent. :-)

← back to recent threads