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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 17, 2012, 21:17 UTC
Message-ID: <7vy5k8s622.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1347895267-5054-1-git-send-email-mhagger@alum.mit.edu>

Michael Haggerty <mhagger@alum.mit.edu> writes:

Show 10 quoted lines

> Junio pointed out that the sort order currently used by string_list
> could be considered to be an implementation detail internal to
> string_list.  But the sort order is already visible to the outside
> world (e.g., via iteration or via print_string_list()), so it
> shouldn't be changed willy-nilly.  Therefore, document the current
> sort order as part of the API's contract.
>
> (If, at some future time, somebody wants a string_list that is sorted
> by a different criterion, then the order should be made specifiable
> via a callback function specified by the user.)

As I said in a separate message, we do not give any documented guarantee on the order the strings comes out of print_string_list(), other than "if you are using the unsorted list function to insert or append strings, we won't muck with the order of the items and you will get your strings back in the order you gave us". Until we add a callback that the user can specify at the time of string list initialization, I do not think it is wise to cast it in stone and declare it as "shouldn't be changed willy-nilly", unnecessarily painting us into a corner that we need to expend extra effort to get out of.

Besides, nobody calls print_string_list() in the first place. I have always considered it as a debugging aid.