From 4acac918f49d6117a857e9acce66bec4648dde81 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 17 Nov 2021 12:51:32 -0600 Subject: Enhanced RDoc for Integer (#5134) Treated: #== #<=> #< #<= #> #>= #& #| #^ --- numeric.c | 241 ++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 156 insertions(+), 85 deletions(-) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index fd3adf5fbc..a736e7cecb 100644 --- a/numeric.c +++ b/numeric.c @@ -3934,12 +3934,15 @@ fix_div(VALUE x, VALUE y) * call-seq: * self / numeric -> numeric_result * - * Performs division: + * Performs division; for integer +numeric+, truncates the result to an integer: * * 4 / 3 # => 1 * 4 / -3 # => -2 * -4 / 3 # => -2 * -4 / -3 # => 1 + * + * For other +numeric+, returns non-integer result: + * * 4 / 3.0 # => 1.3333333333333333 * 4 / Rational(3, 1) # => (4/3) * 4 / Complex(3, 0) # => ((4/3)+0i) @@ -4309,19 +4312,6 @@ rb_num_pow(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#== - * Document-method: Integer#=== - * call-seq: - * int == other -> true or false - * - * Returns +true+ if +int+ equals +other+ numerically. - * Contrast this with Integer#eql?, which requires +other+ to be an Integer. - * - * 1 == 2 #=> false - * 1 == 1.0 #=> true - */ - static VALUE fix_equal(VALUE x, VALUE y) { @@ -4338,6 +4328,21 @@ fix_equal(VALUE x, VALUE y) } } +/* + * call-seq: + * self == other -> true or false + * + * Returns +true+ if +self+ is numerically equal to +other+; +false+ otherwise. + * + * 1 == 2 #=> false + * 1 == 1.0 #=> true + * + * Related: Integer#eql? (requires +other+ to be an \Integer). + * + * Integer#=== is an alias for Integer#==. + * + */ + VALUE rb_int_equal(VALUE x, VALUE y) { @@ -4350,19 +4355,6 @@ rb_int_equal(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#<=> - * call-seq: - * int <=> numeric -> -1, 0, +1, or nil - * - * Comparison---Returns -1, 0, or +1 depending on whether +int+ is - * less than, equal to, or greater than +numeric+. - * - * This is the basis for the tests in the Comparable module. - * - * +nil+ is returned if the two values are incomparable. - */ - static VALUE fix_cmp(VALUE x, VALUE y) { @@ -4387,6 +4379,32 @@ fix_cmp(VALUE x, VALUE y) } } +/* + * call-seq: + * self <=> other -> -1, 0, +1, or nil + * + * Returns: + * + * - -1, if +self+ is less than +other+. + * - 0, if +self+ is equal to +other+. + * - 1, if +self+ is greater then +other+. + * - +nil+, if +self+ and +other+ are incomparable. + * + * Examples: + * + * 1 <=> 2 # => -1 + * 1 <=> 1 # => 0 + * 1 <=> 0 # => 1 + * 1 <=> 'foo' # => nil + * + * 1 <=> 1.0 # => 0 + * 1 <=> Rational(1, 1) # => 0 + * 1 <=> Complex(1, 0) # => 0 + * + * This method is the basis for comparisons in module Comparable. + * + */ + VALUE rb_int_cmp(VALUE x, VALUE y) { @@ -4401,14 +4419,6 @@ rb_int_cmp(VALUE x, VALUE y) } } -/* - * Document-method: Integer#> - * call-seq: - * int > real -> true or false - * - * Returns +true+ if the value of +int+ is greater than that of +real+. - */ - static VALUE fix_gt(VALUE x, VALUE y) { @@ -4426,6 +4436,22 @@ fix_gt(VALUE x, VALUE y) } } +/* + * call-seq: + * self > other -> true or false + * + * Returns +true+ if the value of +self+ is greater than that of +other+: + * + * 1 > 0 # => true + * 1 > 1 # => false + * 1 > 2 # => false + * 1 > 0.5 # => true + * 1 > Rational(1, 2) # => true + * + * Raises an exception if the comparison cannot be made. + * + */ + VALUE rb_int_gt(VALUE x, VALUE y) { @@ -4438,15 +4464,6 @@ rb_int_gt(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#>= - * call-seq: - * int >= real -> true or false - * - * Returns +true+ if the value of +int+ is greater than or equal to that of - * +real+. - */ - static VALUE fix_ge(VALUE x, VALUE y) { @@ -4465,6 +4482,23 @@ fix_ge(VALUE x, VALUE y) } } +/* + * call-seq: + * self >= real -> true or false + * + * Returns +true+ if the value of +self+ is greater than or equal to + * that of +other+: + * + * 1 >= 0 # => true + * 1 >= 1 # => true + * 1 >= 2 # => false + * 1 >= 0.5 # => true + * 1 >= Rational(1, 2) # => true + * + * Raises an exception if the comparison cannot be made. + * + */ + VALUE rb_int_ge(VALUE x, VALUE y) { @@ -4477,14 +4511,6 @@ rb_int_ge(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#< - * call-seq: - * int < real -> true or false - * - * Returns +true+ if the value of +int+ is less than that of +real+. - */ - static VALUE fix_lt(VALUE x, VALUE y) { @@ -4502,6 +4528,22 @@ fix_lt(VALUE x, VALUE y) } } +/* + * call-seq: + * self < other -> true or false + * + * Returns +true+ if the value of +self+ is less than that of +other+: + * + * 1 < 0 # => false + * 1 < 1 # => false + * 1 < 2 # => true + * 1 < 0.5 # => false + * 1 < Rational(1, 2) # => false + * + * Raises an exception if the comparison cannot be made. + * + */ + static VALUE int_lt(VALUE x, VALUE y) { @@ -4514,15 +4556,6 @@ int_lt(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#<= - * call-seq: - * int <= real -> true or false - * - * Returns +true+ if the value of +int+ is less than or equal to that of - * +real+. - */ - static VALUE fix_le(VALUE x, VALUE y) { @@ -4541,6 +4574,23 @@ fix_le(VALUE x, VALUE y) } } +/* + * call-seq: + * self <= real -> true or false + * + * Returns +true+ if the value of +self+ is less than or equal to + * that of +other+: + * + * 1 <= 0 # => false + * 1 <= 1 # => true + * 1 <= 2 # => true + * 1 <= 0.5 # => false + * 1 <= Rational(1, 2) # => false + * + * Raises an exception if the comparison cannot be made. + * + */ + static VALUE int_le(VALUE x, VALUE y) { @@ -4600,14 +4650,6 @@ rb_num_coerce_bit(VALUE x, VALUE y, ID func) return ret; } -/* - * Document-method: Integer#& - * call-seq: - * int & other_int -> integer - * - * Bitwise AND. - */ - static VALUE fix_and(VALUE x, VALUE y) { @@ -4623,6 +4665,21 @@ fix_and(VALUE x, VALUE y) return rb_num_coerce_bit(x, y, '&'); } +/* + * call-seq: + * self & other -> integer + * + * Bitwise AND; each bit in the result is 1 if both corresponding bits + * in +self+ and +other+ are 1, 0 otherwise: + * + * "%04b" % (0b0101 & 0b0110) # => "0100" + * + * Raises an exception if +other+ is not an \Integer. + * + * Related: Integer#| (bitwise OR), Integer#^ (bitwise EXCLUSIVE OR). + * + */ + VALUE rb_int_and(VALUE x, VALUE y) { @@ -4635,14 +4692,6 @@ rb_int_and(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#| - * call-seq: - * int | other_int -> integer - * - * Bitwise OR. - */ - static VALUE fix_or(VALUE x, VALUE y) { @@ -4658,6 +4707,21 @@ fix_or(VALUE x, VALUE y) return rb_num_coerce_bit(x, y, '|'); } +/* + * call-seq: + * self | other -> integer + * + * Bitwise OR; each bit in the result is 1 if either corresponding bit + * in +self+ or +other+ is 1, 0 otherwise: + * + * "%04b" % (0b0101 | 0b0110) # => "0111" + * + * Raises an exception if +other+ is not an \Integer. + * + * Related: Integer#& (bitwise AND), Integer#^ (bitwise EXCLUSIVE OR). + * + */ + static VALUE int_or(VALUE x, VALUE y) { @@ -4670,14 +4734,6 @@ int_or(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#^ - * call-seq: - * int ^ other_int -> integer - * - * Bitwise EXCLUSIVE OR. - */ - static VALUE fix_xor(VALUE x, VALUE y) { @@ -4693,6 +4749,21 @@ fix_xor(VALUE x, VALUE y) return rb_num_coerce_bit(x, y, '^'); } +/* + * call-seq: + * self ^ other -> integer + * + * Bitwise EXCLUSIVE OR; each bit in the result is 1 if the corresponding bits + * in +self+ and +other+ are different, 0 otherwise: + * + * "%04b" % (0b0101 ^ 0b0110) # => "0011" + * + * Raises an exception if +other+ is not an \Integer. + * + * Related: Integer#& (bitwise AND), Integer#| (bitwise OR). + * + */ + static VALUE int_xor(VALUE x, VALUE y) { -- cgit v1.2.1