{"thread":{"id":"24995","subject":"[Patch v3] string-list: Document STRING_LIST_INIT_* macros.","startedAt":"2010-09-06T00:13:11Z","lastAt":"2010-09-06T00:38:01Z","messageCount":3,"participants":["Thiago Farina","Jonathan Nieder"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"150015","messageId":"1283731991-15080-1-git-send-email-tfransosi@gmail.com","threadId":"24995","inReplyTo":null,"subject":"[Patch v3] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2010-09-06T00:13:11Z","receivedAt":"2010-09-06T00:13:11Z","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 |   16 ++++++++++------\n 1 files changed, 10 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt\nindex 3f575bd..f689163 100644\n--- a/Documentation/technical/api-string-list.txt\n+++ b/Documentation/technical/api-string-list.txt\n@@ -11,10 +11,15 @@ 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-  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+. Initializes the members. A string_list might be initialize by\n+  `= STRING_LIST_INT_NODUP` or `= STRING_LIST_INIT_DUP` before it can be used.\n+\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 +\n If you need something advanced, you can manually malloc() the `items`\n member (you need this if you add things later) and you should set the\n@@ -34,10 +39,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-- \n1.7.2.3.313.gcd15\n"},{"id":"150019","messageId":"20100906002249.GB18060@burratino","threadId":"24995","inReplyTo":"1283731991-15080-1-git-send-email-tfransosi@gmail.com","subject":"Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-09-06T00:22:49Z","receivedAt":"2010-09-06T00:22:49Z","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,10 +11,15 @@ 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> -  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> +. Initializes the members. A string_list might be initialize by\n\ns/initialize/initalized/, I think.\n\n> +  `= STRING_LIST_INT_NODUP` or `= STRING_LIST_INIT_DUP` before it can be used.\n> +\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\nIf we do not have a string_list_init() function, maybe it is worth\nmentioning how a person can use\n\n memset(&list, 0, sizeof(struct string_list));\n list.strdup_strings = 1 or 0;\n\ntoo?\n\nThe previous text tried (too subtly, perhaps) to imply that with the\n\"clears\" (for memset) and \"might want to set the flag `strdup_strings`\"\nphrases.\n\n> @@ -34,10 +39,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\nProbably worth copying and pasting this code to another file and\ntrying it to make sure it works for the final draft.\n\nAlso, I am afraid I will not be able to send detailed reviews on\nuncomplicated patches like this one in the future.  It simply does not\nscale (though I like for people to learn, at a certain point it\nbecomes faster to do things myself).\n\nSo if you can, it is best to find ways to motivate other people to\nhelp with your work, by conveying what problems it will solve (in this\ncase: people might be confused about the initialization sequence; as\npart of patch 3 demonstrated, the invariants regarding strdup_strings\nare not being described clearly enough) and finding ways to minimize\nthe time other people have to spend to get it done.\n\nRegards,\nJonathan\n"},{"id":"150021","messageId":"AANLkTikivCxU8Si-p1u4H6GtQfrdQdrHcBpr0Smkf5Rq@mail.gmail.com","threadId":"24995","inReplyTo":"20100906002249.GB18060@burratino","subject":"Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2010-09-06T00:38:01Z","receivedAt":"2010-09-06T00:38:01Z","isPatch":true,"sender":{"key":"tfransosi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/970071?v=4"},"body":"On Sun, Sep 5, 2010 at 9:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n>> @@ -34,10 +39,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>\n> Probably worth copying and pasting this code to another file and\n> trying it to make sure it works for the final draft.\n\nI already done in the test-string-list.c patch I sent. :-)\n"}]}