Allow different values than only -1, 0 and 1 to be returned by <=>

spec/std/array_spec.cr

@@ -1180,7 +1180,7 @@ describe "Array" do
     b = [4, 5, 6]
     c = [1, 2]
 
-    (a <=> b).should be < 1
+    (a <=> b).should be < 0
     (a <=> c).should be > 0
     (b <=> c).should be > 0
     (b <=> a).should be > 0

src/array.cr

@@ -167,11 +167,13 @@ class Array(T)
     false
   end
 
-  # Combined comparison operator. Returns *0* if `self` equals *other*, *1* if
-  # `self` is greater than *other* and *-1* if `self` is smaller than *other*.
+  # Combined comparison operator.
+  #
+  # Returns `-1`, `0` or `1` depending on whether `self` is less than *other*, equals *other*
+  # or is greater than *other*.
   #
   # It compares the elements of both arrays in the same position using the
-  # `<=>` operator.  As soon as one of such comparisons returns a non-zero
+  # `<=>` operator. As soon as one of such comparisons returns a non-zero
   # value, that result is the return value of the comparison.
   #
   # If all elements are equal, the comparison is based on the size of the arrays.

src/char.cr

@@ -103,10 +103,16 @@ struct Char
     (ord - other).chr
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
+  #
+  # Returns the difference of the codepoint values of `self` and *other*.
+  # The result is either negative, `0` or positive based on whether `other`'s codepoint is
+  # less, equal, or greater than `self`'s codepoint.
   #
   # ```
   # 'a' <=> 'c' # => -2
+  # 'z' <=> 'z' # => 0
+  # 'c' <=> 'a' # => 2
   # ```
   def <=>(other : Char)
     self - other

src/comparable.cr

@@ -1,22 +1,22 @@
 # The `Comparable` mixin is used by classes whose objects may be ordered.
 #
 # Including types must provide an `<=>` method, which compares the receiver against
-# another object, returning `-1`, `0`, or `+1` depending on whether the receiver is less than,
-# equal to, or greater than the other object.
+# another object, returning a negative number, `0`, or a positive number depending
+# on whether the receiver is less than, equal to, or greater than the other object.
 #
 # `Comparable` uses `<=>` to implement the conventional comparison operators (`<`, `<=`, `==`, `>=`, and `>`).
 module Comparable(T)
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `-1`.
+  # Compares this object to *other* based on the receiver's `<=>` method, returning `true` if it returns a negative number.
   def <(other : T)
     (self <=> other) < 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `-1` or `0`.
+  # Compares this object to *other* based on the receiver's `<=>` method, returning `true` if it returns a negative number or `0`.
   def <=(other : T)
     (self <=> other) <= 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `0`.
+  # Compares this object to *other* based on the receiver's `<=>` method, returning `true` if it returns `0`.
   # Also returns `true` if this and *other* are the same object.
   def ==(other : T)
     if self.is_a?(Reference)
@@ -30,25 +30,31 @@ module Comparable(T)
     (self <=> other) == 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `1`.
+  # Compares this object to *other* based on the receiver's `<=>` method, returning `true` if it returns a positive number.
   def >(other : T)
     (self <=> other) > 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `1` or `0`.
+  # Compares this object to *other* based on the receiver's `<=>` method, returning `true` if it returns a positive number or `0`.
   def >=(other : T)
     (self <=> other) >= 0
   end
 
-  # Comparison operator. Returns `0` if the two objects are equal,
-  # a negative number if this object is considered less than *other*,
-  # or a positive number otherwise.
+  # The comparison operator.
+  #
+  # Returns `-1`, `0` or `1` depending on whether `self` is less than *other*, equals *other*
+  # or is greater than *other*.
   #
   # Subclasses define this method to provide class-specific ordering.
   #
+  # The comparison operator is usually used to sort values:
+  #
   # ```
-  # # Sort in a descending way
-  # [4, 7, 2].sort { |x, y| y <=> x } # => [7, 4, 2]
+  # # Sort in a descending way:
+  # [3, 1, 2].sort { |x, y| y <=> x } # => [3, 2, 1]
+  #
+  # # Sort in an ascending way:
+  # [3, 1, 2].sort { |x, y| x <=> y } # => [1, 2, 3]
   # ```
   abstract def <=>(other : T)
 end

src/compiler/crystal/macros.cr

@@ -6,7 +6,9 @@
 # `Macros` module are top-level methods that you can invoke, like `puts` and `run`.
 module Crystal::Macros
   # Compares two [semantic versions](http://semver.org/).
-  # Returns `-1` if `v1 < v2`, `0` if `v1 == v2` and `1` if `v1 > v2`.
+  #
+  # Returns `-1`, `0` or `1` depending on whether *v1* is lower than *v2*,
+  # equal to *v2* or greater than *v2*.
   #
   # ```
   # {{ compare_versions("1.10.0", "1.2.0") }} # => 1

src/number.cr

@@ -161,9 +161,10 @@ struct Number
     {(self / number).floor, self % number}
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
   #
-  # See also: `Object#<=>`.
+  # Returns `-1`, `0` or `1` depending on whether `self` is less than *other*, equals *other*
+  # or is greater than *other*.
   def <=>(other)
     self > other ? 1 : (self < other ? -1 : 0)
   end

src/partial_comparable.cr

@@ -1,30 +1,30 @@
 # The `PartialComparable` mixin is used by classes whose objects may be partially ordered.
 #
 # Including types must provide an `<=>` method, which compares the receiver against
-# another object, returning `-1`, `0`, `+1` or `nil` depending on whether
+# another object, returning a negative number, `0`, a positive number or `nil` depending on whether
 # the receiver is less than, equal to, greater than the other object,
 # or no order can be established.
 #
 # `PartialComparable` uses `<=>` to implement the conventional
 # comparison operators (`<`, `<=`, `==`, `>=`, and `>`).
 module PartialComparable(T)
-  # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `-1`.
+  # Compares this object to *other* based on the receiver's `<=>` method,
+  # returning `true` if it returns a negative number.
   def <(other : T)
     compare_with(other) do |cmp|
       cmp < 0
     end
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `-1` or `0`.
+  # Compares this object to *other* based on the receiver's `<=>` method,
+  # returning `true` if it returns a negative number or `0`.
   def <=(other : T)
     compare_with(other) do |cmp|
       cmp <= 0
     end
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method,
+  # Compares this object to *other* based on the receiver's `<=>` method,
   # returning `true` if it returns `0`.
   # Also returns `true` if this and *other* are the same object.
   def ==(other : T)
@@ -37,16 +37,16 @@ module PartialComparable(T)
     end
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `1`.
+  # Compares this object to *other* based on the receiver's `<=>` method,
+  # returning `true` if it returns a positive number.
   def >(other : T)
     compare_with(other) do |cmp|
       cmp > 0
     end
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `1` or `0`.
+  # Compares this object to *other* based on the receiver's `<=>` method,
+  # returning `true` if it returns a positive number or `0`.
   def >=(other : T)
     compare_with(other) do |cmp|
       cmp >= 0
@@ -62,5 +62,16 @@ module PartialComparable(T)
     end
   end
 
+  # The comparison operator.
+  #
+  # Returns a negative number, `0`, a positive number or `nil` depending on whether the object is considered to be less than *other*,
+  # equal to *other*, greater than *other* or if no order can be established.
+  #
+  # Subclasses define this method to provide class-specific ordering.
+  #
+  # ```
+  # # Sort in a descending way
+  # [4, 7, 2].sort { |x, y| y <=> x } # => [7, 4, 2]
+  # ```
   abstract def <=>(other : T)
 end

src/pointer.cr

@@ -98,10 +98,8 @@ struct Pointer(T)
     self + (-other.to_i64!)
   end
 
-  # Returns -1, 0 or 1 if this pointer's address is less, equal or greater than *other*'s address,
+  # Returns `-1`, `0` or `1` depending on whether this pointer's address is less, equal or greater than *other*'s address,
   # respectively.
-  #
-  # See also: `Object#<=>`.
   def <=>(other : self)
     address <=> other.address
   end

src/semantic_version.cr

@@ -78,7 +78,10 @@ struct SemanticVersion
     end
   end
 
-  # The comparison operator
+  # The comparison operator.
+  #
+  # Returns `-1`, `0` or `1` depending on whether `self`'s version is lower than *other*'s,
+  # equal to *other*'s version or greater than *other*'s version.
   #
   # ```
   # require "semantic_version"
@@ -145,7 +148,10 @@ struct SemanticVersion
       identifiers.join('.', io)
     end
 
-    # The comparison operator
+    # The comparison operator.
+    #
+    # Returns `-1`, `0` or `1` depending on whether `self`'s pre-release is lower than *other*'s,
+    # equal to *other*'s pre-release or greater than *other*'s pre-release.
     #
     # ```
     # require "semantic_version"

src/string.cr

@@ -2361,7 +2361,9 @@ class String
     to_unsafe.memcmp(other.to_unsafe, bytesize) == 0
   end
 
-  # Compares this string with *other*, returning `-1`, `0` or `+1` depending on whether
+  # The comparison operator.
+  #
+  # Compares this string with *other*, returning `-1`, `0` or `1` depending on whether
   # this string is less, equal or greater than *other*.
   #
   # Comparison is done byte-per-byte: if a byte is less then the other corresponding
@@ -2385,7 +2387,7 @@ class String
     cmp == 0 ? (bytesize <=> other.bytesize) : cmp.sign
   end
 
-  # Compares this string with *other*, returning `-1`, `0` or `+1` depending on whether
+  # Compares this string with *other*, returning `-1`, `0` or `1` depending on whether
   # this string is less, equal or greater than *other*, optionally in a *case_insensitive*
   # manner.
   #

src/symbol.cr

@@ -20,8 +20,8 @@ struct Symbol
     hasher.symbol(self)
   end
 
-  # Compares symbol with other based on `String#<=>` method. Returns `-1`, `0`
-  # or `+1` depending on whether symbol is less than, equal to,
+  # Compares symbol with other based on `String#<=>` method.
+  # Returns `-1`, `0` or `1` depending on whether symbol is less than, equal to,
   # or greater than *other*.
   #
   # See `String#<=>` for more information.

src/tuple.cr

@@ -269,13 +269,13 @@ struct Tuple
     true
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
   #
-  # Each object in each tuple is compared (using the `<=>` operator).
+  # Each object in each tuple is compared using the `<=>` operator.
   #
   # Tuples are compared in an "element-wise" manner; the first element of this tuple is
   # compared with the first one of *other* using the `<=>` operator, then each of the second elements,
-  # etc. As soon as the result of any such comparison is non zero
+  # etc. As soon as the result of any such comparison is non-zero
   # (i.e. the two corresponding elements are not equal), that result is returned for the whole tuple comparison.
   #
   # If all the elements are equal, then the result is based on a comparison of the tuple sizes.
@@ -284,11 +284,9 @@ struct Tuple
   #
   # ```
   # {"a", "a", "c"} <=> {"a", "b", "c"} # => -1
-  # {1, 2, 3, 4, 5, 6} <=> {1, 2}       # => +1
+  # {1, 2, 3, 4, 5, 6} <=> {1, 2}       # => 1
   # {1, 2} <=> {1, 2.0}                 # => 0
   # ```
-  #
-  # See also: `Object#<=>`.
   def <=>(other : self)
     {% for i in 0...T.size %}
       cmp = self[{{i}}] <=> other[{{i}}]