ruby-changes:27366
From: zzak <ko1@a...>
Date: Sat, 23 Feb 2013 12:35:54 +0900 (JST)
Subject: [ruby-changes:27366] zzak:r39418 (trunk): * array.c: Document #<=> return values and formatting
zzak 2013-02-23 12:35:38 +0900 (Sat, 23 Feb 2013) New Revision: 39418 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=39418 Log: * array.c: Document #<=> return values and formatting * bignum.c: ditto * file.c: ditto * object.c: ditto * numeric.c: ditto * rational.c: ditto * string.c: ditto * time.c: ditto Modified files: trunk/ChangeLog trunk/array.c trunk/bignum.c trunk/file.c trunk/numeric.c trunk/object.c trunk/rational.c trunk/string.c trunk/time.c Index: array.c =================================================================== --- array.c (revision 39417) +++ array.c (revision 39418) @@ -3703,6 +3703,8 @@ recursive_cmp(VALUE ary1, VALUE ary2, in https://github.com/ruby/ruby/blob/trunk/array.c#L3703 * Comparison --- Returns an integer (+-1+, +0+, or <code>+1</code>) if this * array is less than, equal to, or greater than +other_ary+. * + * +nil+ is returned if the two values are incomparable. + * * Each object in each array is compared (using the <=> operator). * * Arrays are compared in an "element-wise" manner; the first two elements Index: time.c =================================================================== --- time.c (revision 39417) +++ time.c (revision 39418) @@ -3334,10 +3334,12 @@ time_subsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3334 * call-seq: * time <=> other_time -> -1, 0, +1 or nil * - * Comparison---Compares _time_ with +other_time+. - * The return value is ++1+ if _time_ is greater than - * +other_time+, +0+ if _time_ is equal to +other_time+ and - * +-1+ if _time_ is smaller than +other_time+. + * Comparison---Compares +time+ with +other_time+. + * + * -1, 0, +1 or nil depending on whether +time+ is less than, equal to, or + * greater than +other_time+. + * + * +nil+ is returned if the two values are incomparable. * * t = Time.now #=> 2007-11-19 08:12:12 -0600 * t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600 Index: ChangeLog =================================================================== --- ChangeLog (revision 39417) +++ ChangeLog (revision 39418) @@ -1,3 +1,14 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Sat Feb 23 12:35:00 2013 Zachary Scott <zachary@z...> + + * array.c: Document #<=> return values and formatting + * bignum.c: ditto + * file.c: ditto + * object.c: ditto + * numeric.c: ditto + * rational.c: ditto + * string.c: ditto + * time.c: ditto + Sat Feb 23 10:50:00 2013 Zachary Scott <zachary@z...> * array.c (rb_ary_diff, rb_ary_and, rb_ary_or): Document return order Index: string.c =================================================================== --- string.c (revision 39417) +++ string.c (revision 39418) @@ -2358,20 +2358,22 @@ rb_str_eql(VALUE str1, VALUE str2) https://github.com/ruby/ruby/blob/trunk/string.c#L2358 /* * call-seq: - * str <=> other_str -> -1, 0, +1 or nil + * string <=> other_string -> -1, 0, +1 or nil * - * Comparison---Returns -1 if <i>other_str</i> is greater than, 0 if - * <i>other_str</i> is equal to, and +1 if <i>other_str</i> is less than - * <i>str</i>. If the strings are of different lengths, and the strings are - * equal when compared up to the shortest length, then the longer string is - * considered greater than the shorter one. In older versions of Ruby, setting - * <code>$=</code> allowed case-insensitive comparisons; this is now deprecated - * in favor of using <code>String#casecmp</code>. + * + * Comparison---Returns -1, 0, +1 or nil depending on whether +string+ is less + * than, equal to, or greater than +other_string+. + * + * +nil+ is returned if the two values are incomparable. + * + * If the strings are of different lengths, and the strings are equal when + * compared up to the shortest length, then the longer string is considered + * greater than the shorter one. * * <code><=></code> is the basis for the methods <code><</code>, - * <code><=</code>, <code>></code>, <code>>=</code>, and <code>between?</code>, - * included from module <code>Comparable</code>. The method - * <code>String#==</code> does not use <code>Comparable#==</code>. + * <code><=</code>, <code>></code>, <code>>=</code>, and + * <code>between?</code>, included from module Comparable. The method + * String#== does not use Comparable#==. * * "abcdef" <=> "abcde" #=> 1 * "abcdef" <=> "abcdef" #=> 0 @@ -7946,9 +7948,15 @@ sym_succ(VALUE sym) https://github.com/ruby/ruby/blob/trunk/string.c#L7948 /* * call-seq: * - * str <=> other -> -1, 0, +1 or nil + * symbol <=> other_symbol -> -1, 0, +1 or nil + * + * Compares +symbol+ with +other_symbol+ after calling #to_s on each of the + * symbols. Returns -1, 0, +1 or nil depending on whether +symbol+ is less + * than, equal to, or greater than +other_symbol+. + * + * +nil+ is returned if the two values are incomparable. * - * Compares _sym_ with _other_ in string form. + * See String#<=> for more information. */ static VALUE Index: object.c =================================================================== --- object.c (revision 39417) +++ object.c (revision 39418) @@ -1540,13 +1540,14 @@ rb_mod_gt(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L1540 /* * call-seq: - * mod <=> other_mod -> -1, 0, +1, or nil + * module <=> other_module -> -1, 0, +1, or nil * - * Comparison---Returns -1 if <i>mod</i> includes <i>other_mod</i>, 0 if - * <i>mod</i> is the same as <i>other_mod</i>, and +1 if <i>mod</i> is - * included by <i>other_mod</i>. Returns <code>nil</code> if <i>mod</i> - * has no relationship with <i>other_mod</i> or if <i>other_mod</i> is - * not a module. + * Comparison---Returns -1, 0, +1 or nil depending on whether +module+ + * includes +other_module+, they are the same, or if +module+ is included by + * +other_module+. This is the basis for the tests in Comparable. + * + * Returns +nil+ if +module+ has no relationship with +other_module+, if + * +other_module+ is not a module, or if the two values are incomparable. */ static VALUE Index: numeric.c =================================================================== --- numeric.c (revision 39417) +++ numeric.c (revision 39418) @@ -1038,10 +1038,10 @@ num_eql(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1038 /* * call-seq: - * num <=> other -> 0 or nil + * number <=> other -> 0 or nil * - * Returns zero if <i>num</i> equals <i>other</i>, <code>nil</code> - * otherwise. + * Returns zero if +number+ equals +other+, otherwise +nil+ is returned if the + * two values are incomparable. */ static VALUE @@ -1129,13 +1129,15 @@ rb_dbl_cmp(double a, double b) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1129 /* * call-seq: - * flt <=> real -> -1, 0, +1 or nil + * float <=> real -> -1, 0, +1 or nil + * + * Returns -1, 0, +1 or nil depending on whether +float+ is less than, equal + * to, or greater than +real+. This is the basis for the tests in Comparable. * - * Returns -1, 0, +1 or nil depending on whether <i>flt</i> is less - * than, equal to, or greater than <i>real</i>. This is the basis for - * the tests in <code>Comparable</code>. * The result of <code>NaN <=> NaN</code> is undefined, so the * implementation-dependent value is returned. + * + * +nil+ is returned if the two values are incomparable. */ static VALUE @@ -3042,10 +3044,11 @@ fix_equal(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L3044 * call-seq: * fix <=> numeric -> -1, 0, +1 or nil * - * Comparison---Returns -1, 0, +1 or nil depending on whether - * <i>fix</i> is less than, equal to, or greater than - * <i>numeric</i>. This is the basis for the tests in - * <code>Comparable</code>. + * Comparison---Returns -1, 0, +1 or nil depending on whether +fix+ is less + * than, equal to, or greater than +numeric+. This is the basis for the tests + * in Comparable. + * + * +nil+ is returned if the two values are incomparable. */ static VALUE Index: bignum.c =================================================================== --- bignum.c (revision 39417) +++ bignum.c (revision 39418) @@ -1520,9 +1520,11 @@ rb_integer_float_eq(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/bignum.c#L1520 * call-seq: * big <=> numeric -> -1, 0, +1 or nil * - * Comparison---Returns -1, 0, or +1 depending on whether <i>big</i> is - * less than, equal to, or greater than <i>numeric</i>. This is the - * basis for the tests in <code>Comparable</code>. + * Comparison---Returns -1, 0, or +1 depending on whether +big+ is + * less than, equal to, or greater than +numeric+. This is the + * basis for the tests in Comparable. + * + * +nil+ is returned if the two values are incomparable. * */ Index: rational.c =================================================================== --- rational.c (revision 39417) +++ rational.c (revision 39418) @@ -1024,10 +1024,12 @@ nurat_expt(VALUE self, VALUE other) https://github.com/ruby/ruby/blob/trunk/rational.c#L1024 /* * call-seq: - * rat <=> numeric -> -1, 0, +1 or nil + * rational <=> numeric -> -1, 0, +1 or nil * * Performs comparison and returns -1, 0, or +1. * + * +nil+ is returned if the two values are incomparable. + * * Rational(2, 3) <=> Rational(2, 3) #=> 0 * Rational(5) <=> 5 #=> 0 * Rational(2,3) <=> Rational(1,3) #=> 1 Index: file.c =================================================================== --- file.c (revision 39417) +++ file.c (revision 39418) @@ -326,8 +326,10 @@ static struct timespec stat_mtimespec(st https://github.com/ruby/ruby/blob/trunk/file.c#L326 * call-seq: * stat <=> other_stat -> -1, 0, 1, nil * - * Compares <code>File::Stat</code> objects by comparing their - * respective modification times. + * Compares File::Stat objects by comparing their respective modification + * times. + * + * +nil+ is returned if the two values are incomparable. * * f1 = File.new("f1", "w") * sleep 1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/