Cleanup erg's cleanup

core/kernel/kernel-docs.factor

@@ -1,5 +1,5 @@
 USING: generic help.markup help.syntax math memory
-namespaces sequences kernel.private layouts sorting classes
+namespaces sequences kernel.private layouts classes
 kernel.private vectors combinators quotations strings words
 assocs arrays math.order ;
 IN: kernel
@@ -241,7 +241,7 @@ ARTICLE: "conditionals" "Conditionals and logic"
 "See " { $link "combinators" } " for forms which abstract away common patterns involving multiple nested branches."
 { $see-also "booleans" "bitwise-arithmetic" both? either? } ;
 
-ARTICLE: "equality" "Equality and comparison testing"
+ARTICLE: "equality" "Equality"
 "There are two distinct notions of ``sameness'' when it comes to objects. You can test if two references point to the same object (" { $emphasis "identity comparison" } "), or you can test if two objects are equal in a domain-specific sense, usually by being instances of the same class, and having equal slot values (" { $emphasis "value comparison" } "). Both notions of equality are equality relations in the mathematical sense."
 $nl
 "Identity comparison:"
@@ -250,16 +250,8 @@ $nl
 { $subsection = }
 "Custom value comparison methods:"
 { $subsection equal? }
+"Utility class:"
 { $subsection identity-tuple }
-"Some types of objects also have an intrinsic order allowing sorting using " { $link natural-sort } ":"
-{ $subsection <=> }
-{ $subsection compare }
-{ $subsection invert-comparison }
-"Utilities for comparing objects:"
-{ $subsection after? }
-{ $subsection before? }
-{ $subsection after=? }
-{ $subsection before=? }
 "An object can be cloned; the clone has distinct identity but equal value:"
 { $subsection clone } ;
 
@@ -394,8 +386,6 @@ HELP: identity-tuple
     { $unchecked-example "T{ foo } dup clone = ." "f" }
 } ;
 
-{ <=> compare natural-sort sort-keys sort-values } related-words
-
 HELP: clone
 { $values { "obj" object } { "cloned" "a new object" } }
 { $contract "Outputs a new object equal to the given object. This is not guaranteed to actually copy the object; it does nothing with immutable objects, and does not copy words either. However, sequences and tuples can be cloned to obtain a shallow copy of the original." } ;

core/math/order/order-docs.factor

@@ -1,9 +1,9 @@
-USING: help.markup help.syntax kernel math sequences quotations
+USING: help.markup help.syntax kernel math quotations
-math.private ;
+math.private words ;
 IN: math.order
 
 HELP: <=>
-{ $values { "obj1" object } { "obj2" object } { "n" real } }
+{ $values { "obj1" object } { "obj2" object } { "symbol" symbol } }
 { $contract
     "Compares two objects using an intrinsic total order, for example, the natural order for real numbers and lexicographic order for strings."
     $nl
@@ -13,7 +13,6 @@ HELP: <=>
         { { $link +eq+ } " - indicating that " { $snippet "obj1" } " is equal to " { $snippet "obj2" } }
         { { $link +gt+ } " - indicating that " { $snippet "obj1" } " follows " { $snippet "obj2" } }
     }
-    "The default implementation treats the two objects as sequences, and recursively compares their elements. So no extra work is required to compare sequences lexicographically."
 } ;
 
 HELP: +lt+
@@ -77,3 +76,19 @@ HELP: [-]
 { $values { "x" real } { "y" real } { "z" real } }
 { $description "Subtracts " { $snippet "y" } " from " { $snippet "x" } ". If the result is less than zero, outputs zero." } ;
 
+ARTICLE: "math.order" "Ordered objects"
+"Some classes have an intrinsic order amongst instances:"
+{ $subsection <=> }
+{ $subsection compare }
+{ $subsection invert-comparison }
+"The above words return one of the following symbols:"
+{ $subsection +lt+ }
+{ $subsection +eq+ }
+{ $subsection +gt+ }
+"Utilities for comparing objects:"
+{ $subsection after? }
+{ $subsection before? }
+{ $subsection after=? }
+{ $subsection before=? } ;
+
+ABOUT: "math.order"

core/math/order/order.factor

@@ -7,11 +7,13 @@ SYMBOL: +lt+
 SYMBOL: +eq+
 SYMBOL: +gt+
 
-GENERIC: <=> ( obj1 obj2 -- n )
+GENERIC: <=> ( obj1 obj2 -- symbol )
 
-: (<=>) - dup 0 < [ drop +lt+ ] [ zero? +eq+ +gt+ ? ] if ;
+: (<=>) ( a b -- symbol )
+    2dup < [ 2drop +lt+ ] [ number= +eq+ +gt+ ? ] if ; inline
 
 : invert-comparison ( symbol -- new-symbol )
+    #! Can't use case, index or nth here
     dup +lt+ eq? [ drop +gt+ ] [ +eq+ eq? +eq+ +lt+ ? ] if ;
 
 M: real <=> (<=>) ;

core/sorting/sorting-docs.factor

@@ -62,3 +62,5 @@ HELP: binsearch*
 { $description "Variant of " { $link binsearch } " which outputs the found element rather than its index in the sequence."
 $nl
 "Outputs " { $link f } " if the sequence is empty. If the sequence has at least one element, this word always outputs a sequence element." } ;
+
+{ <=> compare natural-sort sort-keys sort-values } related-words

extra/help/handbook/handbook.factor

@@ -104,6 +104,7 @@ $nl
 ARTICLE: "objects" "Objects"
 "An " { $emphasis "object" } " is any datum which may be identified. All values are objects in Factor. Each object carries type information, and types are checked at runtime; Factor is dynamically typed."
 { $subsection "equality" }
+{ $subsection "math.order" }
 { $subsection "classes" }
 { $subsection "tuples" }
 { $subsection "generic" }