# [Patch v3] string-list: Document STRING_LIST_INIT_* macros. 3 messages from 2010-09-06 to 2010-09-06. Participants: Thiago Farina, Jonathan Nieder. Thread: https://gitlist.dev/t/24995 ## Thiago Farina, 2010-09-06 00:13 Subject: [Patch v3] string-list: Document STRING_LIST_INIT_* macros. Message-ID: <1283731991-15080-1-git-send-email-tfransosi@gmail.com> URL: https://gitlist.dev/e/1283731991-15080-1-git-send-email-tfransosi%40gmail.com ``` 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 --- Documentation/technical/api-string-list.txt | 16 ++++++++++------ 1 files changed, 10 insertions(+), 6 deletions(-) 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, 2010-09-06 00:22 Subject: Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros. Message-ID: <20100906002249.GB18060@burratino> URL: https://gitlist.dev/e/20100906002249.GB18060%40burratino In-Reply-To: <1283731991-15080-1-git-send-email-tfransosi@gmail.com> ``` Thiago Farina wrote: > +++ 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. > + `= 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. > @@ -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, 2010-09-06 00:38 Subject: Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros. Message-ID: URL: https://gitlist.dev/e/AANLkTikivCxU8Si-p1u4H6GtQfrdQdrHcBpr0Smkf5Rq%40mail.gmail.com In-Reply-To: <20100906002249.GB18060@burratino> ``` On Sun, Sep 5, 2010 at 9:22 PM, Jonathan Nieder wrote: >> @@ -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. :-) ```