{"thread":{"id":"24994","subject":"[PATCH v2] string-list: Document STRING_LIST_INIT_* macros.","startedAt":"2010-09-05T23:40:55Z","lastAt":"2010-09-06T00:15:08Z","messageCount":3,"participants":["Thiago Farina","Jonathan Nieder"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"150010","messageId":"1283730055-14477-1-git-send-email-tfransosi@gmail.com","threadId":"24994","inReplyTo":null,"subject":"[PATCH v2] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2010-09-05T23:40:55Z","receivedAt":"2010-09-05T23:40:55Z","isPatch":true,"sender":{"key":"tfransosi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/970071?v=4"},"body":"Clarify the modern ways to initialize a string_list. Text roughly\nbased on the analogous passage from api-strbuf.txt.\n\n(Note: Based on the demo patch of Jonathan Nieder).\n\nSigned-off-by: Thiago Farina <tfransosi@gmail.com>\n---\n Documentation/technical/api-string-list.txt |   24 +++++++++++++++++++++---\n 1 files changed, 21 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt\nindex 3f575bd..1510ee2 100644\n--- a/Documentation/technical/api-string-list.txt\n+++ b/Documentation/technical/api-string-list.txt\n@@ -11,7 +11,14 @@ The caller:\n \n . Allocates and clears a `struct string_list` variable.\n \n-. Initializes the members. You might want to set the flag `strdup_strings`\n+. Initializes the members. A string_list has to by `= STRING_LIST_INT_NODUP` or\n+  `= STRING_LIST_INIT_DUP` before it can be used.\n+  Strings in lists initialized with the _DUP variant will be\n+  automatically strdup()ed on insertion and free()ed on removal.\n+  For example, this is necessary when you add something like\n+  git_path(\"...\"), since that function returns a static buffer\n+  that will change with the next call to git_path().\n+\n   if the strings should be strdup()ed. For example, this is necessary\n   when you add something like git_path(\"...\"), since that function returns\n   a static buffer that will change with the next call to git_path().\n@@ -34,10 +41,9 @@ member (you need this if you add things later) and you should set the\n Example:\n \n ----\n-struct string_list list;\n+struct string_list list = STRING_LIST_DUP;\n int i;\n \n-memset(&list, 0, sizeof(struct string_list));\n string_list_append(&list, \"foo\");\n string_list_append(&list, \"bar\");\n for (i = 0; i < list.nr; i++)\n@@ -52,6 +58,18 @@ However, if you use the list to check if a certain string was added\n already, you should not do that (using unsorted_string_list_has_string()),\n because the complexity would be quadratic again (but with a worse factor).\n \n+Macros\n+------\n+\n+`STRING_LIST_INIT_NODUP`::\n+\n+\tInitialize the members and set the `strdup_strings` member to 0.\n+\n+`STRING_LIST_INIT_DUP`::\n+\n+\tInitialize the members and set the `strdup_strings` member to 1.\n+\n+\n Functions\n ---------\n \n-- \n1.7.2.3.313.gcd15\n"},{"id":"150013","messageId":"20100905235752.GA18060@burratino","threadId":"24994","inReplyTo":"1283730055-14477-1-git-send-email-tfransosi@gmail.com","subject":"Re: [PATCH v2] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-09-05T23:57:52Z","receivedAt":"2010-09-05T23:57:52Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thiago Farina wrote:\n\n> +++ b/Documentation/technical/api-string-list.txt\n> @@ -11,7 +11,14 @@ The caller:\n>  \n>  . Allocates and clears a `struct string_list` variable.\n>  \n> -. Initializes the members. You might want to set the flag `strdup_strings`\n> +. Initializes the members. A string_list has to by `= STRING_LIST_INT_NODUP` or\n> +  `= STRING_LIST_INIT_DUP` before it can be used.\n> +  Strings in lists initialized with the _DUP variant will be\n> +  automatically strdup()ed on insertion and free()ed on removal.\n> +  For example, this is necessary when you add something like\n> +  git_path(\"...\"), since that function returns a static buffer\n> +  that will change with the next call to git_path().\n> +\n>    if the strings should be strdup()ed. For example, this is necessary\n>    when you add something like git_path(\"...\")\n\nHmm, something seems to have go wrong here.  Did you intend to\ninsert that line break and duplicate the text below it?\n\nWe cannot really say \"a string_list has to be initialized with\nSTRING_LIST_INIT_NODUP or STRING_LIST_INIT_DUP before it is\nused\" because not all string_lists are statically allocated.\nSome (many) are allocated on the heap, which is part of why I\nintroduced a string_list_init() function in the rfc series.\n\n> @@ -52,6 +58,18 @@ However, if you use the list to check if a certain string was added\n>  already, you should not do that (using unsorted_string_list_has_string()),\n>  because the complexity would be quadratic again (but with a worse factor).\n>  \n> +Macros\n> +------\n> +\n> +`STRING_LIST_INIT_NODUP`::\n> +\n> +\tInitialize the members and set the `strdup_strings` member to 0.\n\nI think this section is not very useful.  I think what is intended is\nsomething like\n\n`STRING_LIST_INIT_NODUP`::\n\n\tinitializer for a string_list with 0 items and the `strdup_strings`\n\tmember equal to 0\n\nbut string-list.h says that already:\n\n struct string_list\n {\n\tstruct string_list_item *items;\n\tunsigned int nr, alloc;\n\tunsigned int strdup_strings:1;\n };\n\n #define STRING_LIST_INIT_NODUP\t{ NULL, 0, 0, 0 }\n\nIn generally it is not always a good idea to immediately document\nevery identifier in a project like this one: writing good\ndocumentation takes some time, and maintaining it takes even more, so\nwhen the code already explains something, it tends to be more useful\nto document from another angle.\n\nHope that helps,\nJonathan\n"},{"id":"150016","messageId":"AANLkTi=cfOaivQ0OcLw8XU4JXAnW8kPj1SZbOOQPs2ua@mail.gmail.com","threadId":"24994","inReplyTo":"20100905235752.GA18060@burratino","subject":"Re: [PATCH v2] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2010-09-06T00:15:08Z","receivedAt":"2010-09-06T00:15:08Z","isPatch":true,"sender":{"key":"tfransosi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/970071?v=4"},"body":"On Sun, Sep 5, 2010 at 8:57 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Hmm, something seems to have go wrong here.  Did you intend to\n> insert that line break and duplicate the text below it?\n>\nOps, good catch. Fixed that.\n\n>> @@ -52,6 +58,18 @@ However, if you use the list to check if a certain string was added\n>>  already, you should not do that (using unsorted_string_list_has_string()),\n>>  because the complexity would be quadratic again (but with a worse factor).\n>>\n>> +Macros\n>> +------\n>> +\n>> +`STRING_LIST_INIT_NODUP`::\n>> +\n>> +     Initialize the members and set the `strdup_strings` member to 0.\n>\n> I think this section is not very useful.\n\nOK, removed that section.\n"}]}