From d8d54886316878d44a6832271f9cdc84ee26bb3e Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 16 Nov 2021 13:42:05 -0600 Subject: [PATCH] Enhanced RDoc for Integer (#5120) Treated: #+ #- #* #fdiv #/ #div #** #[] #digits #upto #downto --- numeric.c | 273 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 151 insertions(+), 122 deletions(-) diff --git a/numeric.c b/numeric.c index 547e129b18..fd3adf5fbc 100644 --- a/numeric.c +++ b/numeric.c @@ -3705,7 +3705,7 @@ rb_fix_plus(VALUE x, VALUE y) /* * call-seq: - * self + numeric -> numeric + * self + numeric -> numeric_result * * Performs addition: * @@ -3750,7 +3750,7 @@ fix_minus(VALUE x, VALUE y) /* * call-seq: - * int - numeric -> numeric + * int - numeric -> numeric_result * * Performs subtraction: * @@ -3780,15 +3780,6 @@ rb_int_minus(VALUE x, VALUE y) /*tests if N*N would overflow*/ #define FIT_SQRT_LONG(n) (((n)=-SQRT_LONG_MAX)) -/* - * Document-method: Integer#* - * call-seq: - * int * numeric -> numeric_result - * - * Performs multiplication: the class of the resulting object depends on - * the class of +numeric+. - */ - static VALUE fix_mul(VALUE x, VALUE y) { @@ -3813,6 +3804,20 @@ fix_mul(VALUE x, VALUE y) } } +/* + * call-seq: + * self * numeric -> numeric_result + * + * Performs multiplication: + * + * 4 * 2 # => 8 + * 4 * -2 # => -8 + * -4 * 2 # => -8 + * 4 * 2.0 # => 8.0 + * 4 * Rational(1, 3) # => (4/3) + * 4 * Complex(2, 0) # => (8+0i) + */ + VALUE rb_int_mul(VALUE x, VALUE y) { @@ -3864,15 +3869,19 @@ rb_int_fdiv_double(VALUE x, VALUE y) } /* - * Document-method: Integer#fdiv * call-seq: - * int.fdiv(numeric) -> float + * fdiv(numeric) -> float * - * Returns the floating point result of dividing +int+ by +numeric+. + * Returns the Float result of dividing +self+ by +numeric+: + * + * 4.fdiv(2) # => 2.0 + * 4.fdiv(-2) # => -2.0 + * -4.fdiv(2) # => -2.0 + * 4.fdiv(2.0) # => 2.0 + * 4.fdiv(Rational(3, 4)) # => 5.333333333333333 + * + * Raises an exception if +numeric+ cannot be converted to a Float. * - * 654321.fdiv(13731) #=> 47.652829364212366 - * 654321.fdiv(13731.24) #=> 47.65199646936475 - * -654321.fdiv(13731) #=> -47.652829364212366 */ VALUE @@ -3884,15 +3893,6 @@ rb_int_fdiv(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#/ - * call-seq: - * int / numeric -> numeric_result - * - * Performs division: the class of the resulting object depends on - * the class of +numeric+. - */ - static VALUE fix_divide(VALUE x, VALUE y, ID op) { @@ -3930,6 +3930,22 @@ fix_div(VALUE x, VALUE y) return fix_divide(x, y, '/'); } +/* + * call-seq: + * self / numeric -> numeric_result + * + * Performs division: + * + * 4 / 3 # => 1 + * 4 / -3 # => -2 + * -4 / 3 # => -2 + * -4 / -3 # => 1 + * 4 / 3.0 # => 1.3333333333333333 + * 4 / Rational(3, 1) # => (4/3) + * 4 / Complex(3, 0) # => ((4/3)+0i) + * + */ + VALUE rb_int_div(VALUE x, VALUE y) { @@ -3942,21 +3958,30 @@ rb_int_div(VALUE x, VALUE y) return Qnil; } -/* - * Document-method: Integer#div - * call-seq: - * int.div(numeric) -> integer - * - * Performs integer division: returns the integer result of dividing +int+ - * by +numeric+. - */ - static VALUE fix_idiv(VALUE x, VALUE y) { return fix_divide(x, y, id_div); } +/* + * call-seq: + * div(numeric) -> integer + * + * Performs integer division; returns the integer result of dividing +self+ + * by +numeric+: + * + * 4.div(3) # => 1 + * 4.div(-3) # => -2 + * -4.div(3) # => -2 + * -4.div(-3) # => 1 + * 4.div(3.0) # => 1 + * 4.div(Rational(3, 1)) # => 1 + * + * Raises an exception if +numeric+ does not have method +div+. + * + */ + VALUE rb_int_idiv(VALUE x, VALUE y) { @@ -4132,22 +4157,19 @@ rb_int_divmod(VALUE x, VALUE y) } /* - * Document-method: Integer#** * call-seq: - * int ** numeric -> numeric_result + * self ** numeric -> numeric_result * - * Raises +int+ to the power of +numeric+, which may be negative or - * fractional. - * The result may be an Integer, a Float, a Rational, or a complex number. + * Raises +self+ to the power of +numeric+: * - * 2 ** 3 #=> 8 - * 2 ** -1 #=> (1/2) - * 2 ** 0.5 #=> 1.4142135623730951 - * (-1) ** 0.5 #=> (0.0+1.0i) + * 2 ** 3 # => 8 + * 2 ** -3 # => (1/8) + * -2 ** 3 # => -8 + * -2 ** -3 # => (-1/8) + * 2 ** 3.3 # => 9.849155306759329 + * 2 ** Rational(3, 1) # => (8/1) + * 2 ** Complex(3, 0) # => (8+0i) * - * 123456789 ** 2 #=> 15241578750190521 - * 123456789 ** 1.2 #=> 5126464716.0993185 - * 123456789 ** -2 #=> (1/15241578750190521) */ static VALUE @@ -4887,41 +4909,42 @@ int_aref2(VALUE num, VALUE beg, VALUE len) } /* - * Document-method: Integer#[] * call-seq: - * int[n] -> 0, 1 - * int[n, m] -> num - * int[range] -> num + * self[offset] -> 0 or 1 + * self[offset, size] -> integer + * self[range] -> integer * - * Bit Reference---Returns the nth bit in the - * binary representation of +int+, where int[0] - * is the least significant bit. + * Returns a slice of bits from +self+. * - * a = 0b11001100101010 - * 30.downto(0) {|n| print a[n] } - * #=> 0000000000000000011001100101010 + * With argument +offset+, returns the bit at the given offset, + * where offset 0 refers to the least significant bit: * - * a = 9**15 - * 50.downto(0) {|n| print a[n] } - * #=> 000101110110100000111000011110010100111100010111001 + * n = 0b10 # => 2 + * n[0] # => 0 + * n[1] # => 1 + * n[2] # => 0 + * n[3] # => 0 * * In principle, n[i] is equivalent to (n >> i) & 1. - * Thus, any negative index always returns zero: + * Thus, negative index always returns zero: * - * p 255[-1] #=> 0 + * 255[-1] # => 0 * - * Range operations n[i, len] and n[i..j] - * are naturally extended. + * With arguments +offset+ and +size+, returns +size+ bits from +self+, + * beginning at +offset+ and including bits of greater significance: * - * * n[i, len] equals to (n >> i) & ((1 << len) - 1). - * * n[i..j] equals to (n >> i) & ((1 << (j - i + 1)) - 1). - * * n[i...j] equals to (n >> i) & ((1 << (j - i)) - 1). - * * n[i..] equals to (n >> i). - * * n[..j] is zero if n & ((1 << (j + 1)) - 1) is zero. Otherwise, raises an ArgumentError. - * * n[...j] is zero if n & ((1 << j) - 1) is zero. Otherwise, raises an ArgumentError. + * n = 0b111000 # => 56 + * "%010b" % n[0, 10] # => "0000111000" + * "%010b" % n[4, 10] # => "0000000011" * - * Note that range operation may exhaust memory. - * For example, -1[0, 1000000000000] will raise NoMemoryError. + * With argument +range+, returns range.size bits from +self+, + * beginning at range.begin and including bits of greater significance: + * + * n = 0b111000 # => 56 + * "%010b" % n[0..9] # => "0000111000" + * "%010b" % n[4..9] # => "0000000011" + * + * Raises an exception if the slice cannot be constructed. */ static VALUE @@ -5024,26 +5047,6 @@ rb_int_bit_length(VALUE num) return Qnil; } -/* - * Document-method: Integer#digits - * call-seq: - * int.digits -> array - * int.digits(base) -> array - * - * Returns the digits of +int+'s place-value representation - * with radix +base+ (default: 10). - * The digits are returned as an array with the least significant digit - * as the first array element. - * - * +base+ must be greater than or equal to 2. - * - * 12345.digits #=> [5, 4, 3, 2, 1] - * 12345.digits(7) #=> [4, 6, 6, 0, 5] - * 12345.digits(100) #=> [45, 23, 1] - * - * -12345.digits(7) #=> Math::DomainError - */ - static VALUE rb_fix_digits(VALUE fix, long base) { @@ -5120,6 +5123,22 @@ rb_int_digits_bigbase(VALUE num, VALUE base) return digits; } +/* + * call-seq: + * digits(base = 10) -> array_of_integers + * + * Returns an array of integers representing the +base+-radix + * digits of +self+; + * the first element of the array represents the least significant digit: + * + * 12345.digits # => [5, 4, 3, 2, 1] + * 12345.digits(7) # => [4, 6, 6, 0, 5] + * 12345.digits(100) # => [45, 23, 1] + * + * Raises an exception if +self+ is negative or +base+ is less than 2. + * + */ + static VALUE rb_int_digits(int argc, VALUE *argv, VALUE num) { @@ -5154,26 +5173,32 @@ rb_int_digits(int argc, VALUE *argv, VALUE num) return Qnil; } -/* - * Document-method: Integer#upto - * call-seq: - * int.upto(limit) {|i| block } -> self - * int.upto(limit) -> an_enumerator - * - * Iterates the given block, passing in integer values from +int+ up to and - * including +limit+. - * - * If no block is given, an Enumerator is returned instead. - * - * 5.upto(10) {|i| print i, " " } #=> 5 6 7 8 9 10 - */ - static VALUE int_upto_size(VALUE from, VALUE args, VALUE eobj) { return ruby_num_interval_step_size(from, RARRAY_AREF(args, 0), INT2FIX(1), FALSE); } +/* + * call-seq: + * upto(limit) {|i| ... } -> self + * upto(limit) -> enumerator + * + * Calls the given block with each integer value from +self+ up to +limit+; + * returns +self+: + * + * a = [] + * 5.upto(10) {|i| a << i } # => 5 + * a # => [5, 6, 7, 8, 9, 10] + * a = [] + * -5.upto(0) {|i| a << i } # => -5 + * a # => [-5, -4, -3, -2, -1, 0] + * 5.upto(4) {|i| fail 'Cannot happen' } # => 5 + * + * With no block given, returns an Enumerator. + * + */ + static VALUE int_upto(VALUE from, VALUE to) { @@ -5198,28 +5223,32 @@ int_upto(VALUE from, VALUE to) return from; } -/* - * Document-method: Integer#downto - * call-seq: - * int.downto(limit) {|i| block } -> self - * int.downto(limit) -> an_enumerator - * - * Iterates the given block, passing in decreasing values from +int+ down to - * and including +limit+. - * - * If no block is given, an Enumerator is returned instead. - * - * 5.downto(1) { |n| print n, ".. " } - * puts "Liftoff!" - * #=> "5.. 4.. 3.. 2.. 1.. Liftoff!" - */ - static VALUE int_downto_size(VALUE from, VALUE args, VALUE eobj) { return ruby_num_interval_step_size(from, RARRAY_AREF(args, 0), INT2FIX(-1), FALSE); } +/* + * call-seq: + * downto(limit) {|i| ... } -> self + * downto(limit) -> enumerator + * + * Calls the given block with each integer value from +self+ down to +limit+; + * returns +self+: + * + * a = [] + * 10.downto(5) {|i| a << i } # => 10 + * a # => [10, 9, 8, 7, 6, 5] + * a = [] + * 0.downto(-5) {|i| a << i } # => 0 + * a # => [0, -1, -2, -3, -4, -5] + * 4.downto(5) {|i| fail 'Cannot happen' } # => 4 + * + * With no block given, returns an Enumerator. + * + */ + static VALUE int_downto(VALUE from, VALUE to) {