compar.c

   1 /**********************************************************************
   2
   3   compar.c -
   4
   5   $Author$
   6   created at: Thu Aug 26 14:39:48 JST 1993
   7
   8   Copyright (C) 1993-2007 Yukihiro Matsumoto
   9
  10 **********************************************************************/
  11
  12 #include "id.h"
  13 #include "internal.h"
  14 #include "internal/compar.h"
  15 #include "internal/error.h"
  16 #include "internal/vm.h"
  17 #include "ruby/ruby.h"
  18
  19 VALUE rb_mComparable;
  20
  21 static VALUE
  22 rb_cmp(VALUE x, VALUE y)
  23 {
  24     return rb_funcallv(x, idCmp, 1, &y);
  25 }
  26
  27 void
  28 rb_cmperr(VALUE x, VALUE y)
  29 {
  30     VALUE classname;
  31
  32     if (SPECIAL_CONST_P(y) || BUILTIN_TYPE(y) == T_FLOAT) {
  33         classname = rb_inspect(y);
  34     }
  35     else {
  36         classname = rb_obj_class(y);
  37     }
  38     rb_raise(rb_eArgError, "comparison of %"PRIsVALUE" with %"PRIsVALUE" failed",
  39              rb_obj_class(x), classname);
  40 }
  41
  42 static VALUE
  43 invcmp_recursive(VALUE x, VALUE y, int recursive)
  44 {
  45     if (recursive) return Qnil;
  46     return rb_cmp(y, x);
  47 }
  48
  49 VALUE
  50 rb_invcmp(VALUE x, VALUE y)
  51 {
  52     VALUE invcmp = rb_exec_recursive(invcmp_recursive, x, y);
  53     if (invcmp == Qundef || NIL_P(invcmp)) {
  54         return Qnil;
  55     }
  56     else {
  57         int result = -rb_cmpint(invcmp, x, y);
  58         return INT2FIX(result);
  59     }
  60 }
  61
  62 static VALUE
  63 cmp_eq_recursive(VALUE arg1, VALUE arg2, int recursive)
  64 {
  65     if (recursive) return Qnil;
  66     return rb_cmp(arg1, arg2);
  67 }
  68
  69 /*
  70  *  call-seq:
  71  *     obj == other    -> true or false
  72  *
  73  *  Compares two objects based on the receiver's <code><=></code>
  74  *  method, returning true if it returns 0. Also returns true if
  75  *  _obj_ and _other_ are the same object.
  76  */
  77
  78 static VALUE
  79 cmp_equal(VALUE x, VALUE y)
  80 {
  81     VALUE c;
  82     if (x == y) return Qtrue;
  83
  84     c = rb_exec_recursive_paired_outer(cmp_eq_recursive, x, y, y);
  85
  86     if (NIL_P(c)) return Qfalse;
  87     return RBOOL(rb_cmpint(c, x, y) == 0);
  88 }
  89
  90 static int
  91 cmpint(VALUE x, VALUE y)
  92 {
  93     return rb_cmpint(rb_cmp(x, y), x, y);
  94 }
  95
  96 /*
  97  *  call-seq:
  98  *     obj > other    -> true or false
  99  *
 100  *  Compares two objects based on the receiver's <code><=></code>
 101  *  method, returning true if it returns a value greater than 0.
 102  */
 103
 104 static VALUE
 105 cmp_gt(VALUE x, VALUE y)
 106 {
 107     return RBOOL(cmpint(x, y) > 0);
 108 }
 109
 110 /*
 111  *  call-seq:
 112  *     obj >= other    -> true or false
 113  *
 114  *  Compares two objects based on the receiver's <code><=></code>
 115  *  method, returning true if it returns a value greater than or equal to 0.
 116  */
 117
 118 static VALUE
 119 cmp_ge(VALUE x, VALUE y)
 120 {
 121     return RBOOL(cmpint(x, y) >= 0);
 122 }
 123
 124 /*
 125  *  call-seq:
 126  *     obj < other    -> true or false
 127  *
 128  *  Compares two objects based on the receiver's <code><=></code>
 129  *  method, returning true if it returns a value less than 0.
 130  */
 131
 132 static VALUE
 133 cmp_lt(VALUE x, VALUE y)
 134 {
 135     return RBOOL(cmpint(x, y) < 0);
 136 }
 137
 138 /*
 139  *  call-seq:
 140  *     obj <= other    -> true or false
 141  *
 142  *  Compares two objects based on the receiver's <code><=></code>
 143  *  method, returning true if it returns a value less than or equal to 0.
 144  */
 145
 146 static VALUE
 147 cmp_le(VALUE x, VALUE y)
 148 {
 149     return RBOOL(cmpint(x, y) <= 0);
 150 }
 151
 152 /*
 153  *  call-seq:
 154  *     obj.between?(min, max)    -> true or false
 155  *
 156  *  Returns <code>false</code> if _obj_ <code><=></code> _min_ is less
 157  *  than zero or if _obj_ <code><=></code> _max_ is greater than zero,
 158  *  <code>true</code> otherwise.
 159  *
 160  *     3.between?(1, 5)               #=> true
 161  *     6.between?(1, 5)               #=> false
 162  *     'cat'.between?('ant', 'dog')   #=> true
 163  *     'gnu'.between?('ant', 'dog')   #=> false
 164  *
 165  */
 166
 167 static VALUE
 168 cmp_between(VALUE x, VALUE min, VALUE max)
 169 {
 170     if (cmpint(x, min) < 0) return Qfalse;
 171     if (cmpint(x, max) > 0) return Qfalse;
 172     return Qtrue;
 173 }
 174
 175 /*
 176  *  call-seq:
 177  *     obj.clamp(min, max) ->  obj
 178  *     obj.clamp(range)    ->  obj
 179  *
 180  * In <code>(min, max)</code> form, returns _min_ if _obj_
 181  * <code><=></code> _min_ is less than zero, _max_ if _obj_
 182  * <code><=></code> _max_ is greater than zero, and _obj_
 183  * otherwise.
 184  *
 185  *     12.clamp(0, 100)         #=> 12
 186  *     523.clamp(0, 100)        #=> 100
 187  *     -3.123.clamp(0, 100)     #=> 0
 188  *
 189  *     'd'.clamp('a', 'f')      #=> 'd'
 190  *     'z'.clamp('a', 'f')      #=> 'f'
 191  *
 192  * In <code>(range)</code> form, returns _range.begin_ if _obj_
 193  * <code><=></code> _range.begin_ is less than zero, _range.end_
 194  * if _obj_ <code><=></code> _range.end_ is greater than zero, and
 195  * _obj_ otherwise.
 196  *
 197  *     12.clamp(0..100)         #=> 12
 198  *     523.clamp(0..100)        #=> 100
 199  *     -3.123.clamp(0..100)     #=> 0
 200  *
 201  *     'd'.clamp('a'..'f')      #=> 'd'
 202  *     'z'.clamp('a'..'f')      #=> 'f'
 203  *
 204  * If _range.begin_ is +nil+, it is considered smaller than _obj_,
 205  * and if _range.end_ is +nil+, it is considered greater than
 206  * _obj_.
 207  *
 208  *     -20.clamp(0..)           #=> 0
 209  *     523.clamp(..100)         #=> 100
 210  *
 211  * When _range.end_ is excluded and not +nil+, an exception is
 212  * raised.
 213  *
 214  *     100.clamp(0...100)       # ArgumentError
 215  */
 216
 217 static VALUE
 218 cmp_clamp(int argc, VALUE *argv, VALUE x)
 219 {
 220     VALUE min, max;
 221     int c, excl = 0;
 222
 223     if (rb_scan_args(argc, argv, "11", &min, &max) == 1) {
 224         VALUE range = min;
 225         if (!rb_range_values(range, &min, &max, &excl)) {
 226             rb_raise(rb_eTypeError, "wrong argument type %s (expected Range)",
 227                      rb_builtin_class_name(range));
 228         }
 229         if (!NIL_P(max)) {
 230             if (excl) rb_raise(rb_eArgError, "cannot clamp with an exclusive range");
 231         }
 232     }
 233     if (!NIL_P(min) && !NIL_P(max) && cmpint(min, max) > 0) {
 234         rb_raise(rb_eArgError, "min argument must be smaller than max argument");
 235     }
 236
 237     if (!NIL_P(min)) {
 238         c = cmpint(x, min);
 239         if (c == 0) return x;
 240         if (c < 0) return min;
 241     }
 242     if (!NIL_P(max)) {
 243         c = cmpint(x, max);
 244         if (c > 0) return max;
 245     }
 246     return x;
 247 }
 248
 249 /*
 250  *  The Comparable mixin is used by classes whose objects may be
 251  *  ordered. The class must define the <code><=></code> operator,
 252  *  which compares the receiver against another object, returning a
 253  *  value less than 0, returning 0, or returning a value greater than 0,
 254  *  depending on whether the receiver is less than, equal to,
 255  *  or greater than the other object. If the other object is not
 256  *  comparable then the <code><=></code> operator should return +nil+.
 257  *  Comparable uses <code><=></code> to implement the conventional
 258  *  comparison operators (<code><</code>, <code><=</code>,
 259  *  <code>==</code>, <code>>=</code>, and <code>></code>) and the
 260  *  method <code>between?</code>.
 261  *
 262  *     class SizeMatters
 263  *       include Comparable
 264  *       attr :str
 265  *       def <=>(other)
 266  *         str.size <=> other.str.size
 267  *       end
 268  *       def initialize(str)
 269  *         @str = str
 270  *       end
 271  *       def inspect
 272  *         @str
 273  *       end
 274  *     end
 275  *
 276  *     s1 = SizeMatters.new("Z")
 277  *     s2 = SizeMatters.new("YY")
 278  *     s3 = SizeMatters.new("XXX")
 279  *     s4 = SizeMatters.new("WWWW")
 280  *     s5 = SizeMatters.new("VVVVV")
 281  *
 282  *     s1 < s2                       #=> true
 283  *     s4.between?(s1, s3)           #=> false
 284  *     s4.between?(s3, s5)           #=> true
 285  *     [ s3, s2, s5, s4, s1 ].sort   #=> [Z, YY, XXX, WWWW, VVVVV]
 286  *
 287  *  == What's Here
 288  *
 289  *  \Module \Comparable provides these methods, all of which use method <tt><=></tt>:
 290  *
 291  *  - {<}[#method-i-3C]:: Returns whether +self+ is less than the given object.
 292  *  - {<=}[#method-i-3C-3D]:: Returns whether +self+ is less than or equal to
 293  *                            the given object.
 294  *  - {==}[#method-i-3D-3D]:: Returns whether +self+ is equal to the given object.
 295  *  - {>}[#method-i-3E]:: Returns whether +self+ is greater than or equal to
 296  *                        the given object.
 297  *  - {>=}[#method-i-3E-3D]:: Returns whether +self+ is greater than the given object.
 298  *  - #between? Returns +true+ if +self+ is between two given objects.
 299  *  - #clamp:: For given objects +min+ and +max+, or range <tt>(min..max)</tt>, returns:
 300  *    - +min+ if <tt>(self <=> min) < 0</tt>.
 301  *    - +max+ if <tt>(self <=> max) > 0</tt>.
 302  *    - +self+ otherwise.
 303  */
 304
 305 void
 306 Init_Comparable(void)
 307 {
 308     rb_mComparable = rb_define_module("Comparable");
 309     rb_define_method(rb_mComparable, "==", cmp_equal, 1);
 310     rb_define_method(rb_mComparable, ">", cmp_gt, 1);
 311     rb_define_method(rb_mComparable, ">=", cmp_ge, 1);
 312     rb_define_method(rb_mComparable, "<", cmp_lt, 1);
 313     rb_define_method(rb_mComparable, "<=", cmp_le, 1);
 314     rb_define_method(rb_mComparable, "between?", cmp_between, 2);
 315     rb_define_method(rb_mComparable, "clamp", cmp_clamp, -1);
 316 }