[Xapian-tickets] [Xapian] #311: set_sort_by_value has incorrect sense for 'ascending'

[Xapian]

#311: set_sort_by_value has incorrect sense for 'ascending'
-------------------------+--------------------------------------------------
 Reporter:  tommortimer  |        Owner:  olly     
     Type:  defect       |       Status:  assigned 
 Priority:  normal       |    Milestone:  1.1.0    
Component:  Library API  |      Version:  SVN trunk
 Severity:  minor        |   Resolution:           
 Keywords:               |    Blockedby:           
 Platform:  All          |     Blocking:           
-------------------------+--------------------------------------------------
Changes (by olly):

  * component:  Documentation => Library API


Comment:

 In comment:6 you preferred reversed though!

 I think there's definite "prior art" as to a standard default sort
 direction (ascending) and for describing the opposite as "reverse".  For
 example, the UNIX sort program defaults to ascending with "-r" for reverse
 (the GNU version even has "--reverse" as the long form of "-r"); C++'s
 std::sort defaults to ascending; Perl's sort() function does too; Python's
 sorted function and sort method do (and the sort method has an optional
 "reverse" parameter); PHP's sort() is ascending by default (it offers an
 "rsort" function to sort in reverse order).  Ascending is also the order
 used in dictionaries and book indices.

 In fact, I think the only source of confusion here really is the current
 parameter name and its default.

 > In 2.0, if we add a default argument back, we can add it back with a
 value of false (this only
 > works if there are several release series between 1.1 and 2.0, so that
 it is reasonable to
 > expect all applications to have changed).

 Yes, that's why I said "more distant future".  If 2.0 ends up immediately
 following 1.2, that's probably too soon, though at least the major version
 bump suggests incompatible changes.

 > I don't think adding the default parameter back is not a terribly
 important step, though.

 I'm guessing the "not" isn't intended there.

 But I believe there is natural default here, and I've not been able to
 come up with any existing sorting API which doesn't have a default order,
 other than C's qsort() which is probably just because C doesn't have
 default arguments.  Even there, if you make the comparison function just
 call strcmp(), you get ascending order.

 > "set_sorting_by_value_then_relevance(sort_key, descending=false)" for
 example. I'm not particularly keen on this, but mention it as another idea
 for consideration...

 But then you can't write code which work on both 1.0.x and 1.2.x without
 either using the deprecated form (and getting a warning) or having both
 versions and switching with the preprocessor, which is clumsy and doesn't
 work for the bindings.

 Marking as "API" again, since we're intending to change code rather than
 add warnings to the documentation about the current odd API.

-- 
Ticket URL: <http://trac.xapian.org/ticket/311#comment:11>
Xapian <http://xapian.org/>
Xapian