Re: [PATCH] string_list API: document what "sorted" means.

[Michael Haggerty <mhagger@alum.mit.edu>]

On 09/18/2012 10:19 AM, Junio C Hamano wrote:
> Michael Haggerty <mhagger@alum.mit.edu> writes:
> 
>> 1. Document that string_list sorts entries according to their strcmp()
>> order, as proposed in this patch.  Then fetch can rely on this ordering.
>>  If somebody wants a different ordering in the future, it is easy to
>> make the sort order a parameter.
>>
>> 2. Leave string_list's "default" sort order unspecified, but already
>> implement a way to let string_list users specify a particular sort
>> order.  Change the fetch machinery to specify a strcmp()-based ordering
>> explicitly.  This approach has the advantage of letting the default sort
>> order of string_list to be changed, though I don't really see how this
>> would be helpful.
>>
>> 3. Change fetch back to doing its own sorting again, rather than relying
>> on sort_string_list().  This isn't a lot of work (inline the one line of
>> sort_string_list(), then either make string-list.c:cmp_items() public or
>> duplicate that function too).
> 
> I haven't looked at non-users of string-list API, but my gut feeling
> has been that lack of 2. made the API less useful for current
> non-users, possible callers that could benefit from something like
> string-list that lets them specify their own sort order.
> 
> Also, I actually am more worried about us wanting to change the
> order in which ref-list is sorted, rather than somebody randomly
> deciding to change the default (and only) order string-list is
> sorted on.  When that happens, we would have even less useful
> string-list left behind, with a documented invariant that is not
> helping anybody if we choose to do 1 now.

If another sort order is needed, then we will either have to audit
existing string_list users to make sure that they don't rely on strcmp()
ordering, or we will have to implement strcmp() ordering *plus* the new
ordering.  In that case the simplest approach would be to convert all
existing users to explicit strcmp() ordering and only use the new
ordering in places where there is a specific need for it.  This process
would be no more difficult if we document strcmp() ordering now.
When/if we reach that bridge, we can easily change the documentation from

    A "sorted" list is one whose entries are sorted by string value in
    `strcmp()` order.

to

    A "sorted" list is one whose entries are sorted according to the
    configured `compare()` function.  The default `compare()` function
    orders entries in the `strcmp()` order of their string values.

It's not that I'm unwilling to implement 2; it's just that I still don't
see any advantage to doing so before there is a demonstrated need for it.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/