From c97ca399d8ea5434b332c30ba1d25ab04d14c109 Mon Sep 17 00:00:00 2001
From: Doug Coleman <erg@jobim.local>
Date: Fri, 3 Apr 2009 19:49:49 -0500
Subject: [PATCH] refactor a bit, document sort-by

---
 basis/sorting/slots/slots-docs.factor | 15 ++++++++++++---
 basis/sorting/slots/slots.factor      |  7 +++----
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/basis/sorting/slots/slots-docs.factor b/basis/sorting/slots/slots-docs.factor
index a3bdbf9ac1..cc89d497e7 100644
--- a/basis/sorting/slots/slots-docs.factor
+++ b/basis/sorting/slots/slots-docs.factor
@@ -14,7 +14,7 @@ HELP: compare-slots
 HELP: sort-by-slots
 { $values
      { "seq" sequence } { "sort-specs" "a sequence of accessors ending with a comparator" }
-     { "seq'" sequence }
+     { "sortedseq" sequence }
 }
 { $description "Sorts a sequence of tuples by the sort-specs in " { $snippet "sort-spec" } ". A sort-spec is a sequence of slot accessors ending in a comparator." }
 { $examples
@@ -39,11 +39,20 @@ HELP: split-by-slots
 }
 { $description "Splits a sequence of tuples into a sequence of slices of tuples that have the same values in all slots in the accessor sequence. This word is only useful for splitting a sorted sequence, but is more efficient than partitioning in such a case." } ;
 
+HELP: sort-by
+{ $values
+    { "seq" sequence } { "sort-seq" "a sequence of comparators" }
+    { "sortedseq" sequence }
+}
+{ $description "Sorts a sequence by comparing elements by comparators, using subsequent comparators when there is a tie." } ;
+
 ARTICLE: "sorting.slots" "Sorting by slots"
 "The " { $vocab-link "sorting.slots" } " vocabulary can sort tuples by slot in ascending or descending order, using subsequent slots as tie-breakers." $nl
 "Comparing two objects by a sequence of slots:"
 { $subsection compare-slots }
-"Sorting a sequence by a sequence of slots:"
-{ $subsection sort-by-slots } ;
+"Sorting a sequence of tuples by a slot/comparator pairs:"
+{ $subsection sort-by-slots }
+"Sorting a sequence by a sequence of comparators:"
+{ $subsection sort-by } ;
 
 ABOUT: "sorting.slots"
diff --git a/basis/sorting/slots/slots.factor b/basis/sorting/slots/slots.factor
index 4b6743af5c..2dccc60821 100644
--- a/basis/sorting/slots/slots.factor
+++ b/basis/sorting/slots/slots.factor
@@ -8,7 +8,7 @@ IN: sorting.slots
 <PRIVATE
 
 : short-circuit-comparator ( word -- quot )
-    '[ _ execute dup +eq+ eq? [ drop f ] when ] ; inline
+    execute dup +eq+ eq? [ drop f ] when ; inline
 
 : slot-comparator ( seq -- quot )
     [
@@ -16,7 +16,7 @@ IN: sorting.slots
         [ '[ [ _ execute ] bi@ ] ] map concat
     ] [
         peek
-        '[ @ _ execute dup +eq+ eq? [ drop f ] when ]
+        '[ @ _ short-circuit-comparator ]
     ] bi ;
 
 PRIVATE>
@@ -29,12 +29,11 @@ MACRO: compare-slots ( sort-specs -- <=> )
     '[ _ compare-slots ] sort ;
 
 MACRO: compare-seq ( seq -- quot )
-    [ short-circuit-comparator ] map '[ _ 2|| +eq+ or ] ;
+    [ '[ _ short-circuit-comparator ] ] map '[ _ 2|| +eq+ or ] ;
 
 : sort-by ( seq sort-seq -- sortedseq )
     '[ _ compare-seq ] sort ;
 
-
 MACRO: split-by-slots ( accessor-seqs -- quot )
     [ [ '[ [ _ execute ] bi@ ] ] map concat [ = ] compose ] map
     '[ [ _ 2&& ] slice monotonic-slice ] ;