From f8bbd608c9a0f34e44c4b14f7b913da061e71a70 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 28 Oct 2021 15:11:11 -0500 Subject: Enhanced RDoc for Numeric (#4994) Treats: #eql? #<+> #floor #ceil #round #truncate #step --- numeric.c | 188 +++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 120 insertions(+), 68 deletions(-) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index 715f11c631..da6595085d 100644 --- a/numeric.c +++ b/numeric.c @@ -1419,14 +1419,23 @@ rb_float_pow(VALUE x, VALUE y) /* * call-seq: - * num.eql?(numeric) -> true or false + * eql?(other) -> true or false * - * Returns +true+ if +num+ and +numeric+ are the same type and have equal - * values. Contrast this with Numeric#==, which performs type conversions. + * Returns +true+ if +self+ and +other+ are the same type and have equal values. + * + * Of the Core and Standard Library classes, + * only Integer, Rational, and Complex use this implementation. + * + * Examples: + * + * 1.eql?(1) # => true + * 1.eql?(1.0) # => false + * 1.eql?(Rational(1, 1)) # => false + * 1.eql?(Complex(1, 0)) # => false + * + * \Method +eql?+ is different from +==+ in that +eql?+ requires matching types, + * while +==+ does not. * - * 1 == 1.0 #=> true - * 1.eql?(1.0) #=> false - * 1.0.eql?(1.0) #=> true */ static VALUE @@ -1443,9 +1452,12 @@ num_eql(VALUE x, VALUE y) /* * call-seq: - * number <=> other -> 0 or nil + * self <=> other -> zero or nil + * + * Returns zero if +self+ is the same as +other+, +nil+ otherwise. + * + * No subclass in the Ruby Core or Standard Library uses this implementation. * - * Returns zero if +number+ equals +other+, otherwise returns +nil+. */ static VALUE @@ -2464,12 +2476,12 @@ flo_truncate(int argc, VALUE *argv, VALUE num) /* * call-seq: - * num.floor([ndigits]) -> integer or float + * floor(digits = 0) -> integer or float * - * Returns the largest number less than or equal to +num+ with - * a precision of +ndigits+ decimal digits (default: 0). + * Returns the largest number that is less than or equal to +self+ with + * a precision of +digits+ decimal digits. * - * Numeric implements this by converting its value to a Float and + * \Numeric implements this by converting +self+ to a Float and * invoking Float#floor. */ @@ -2481,12 +2493,12 @@ num_floor(int argc, VALUE *argv, VALUE num) /* * call-seq: - * num.ceil([ndigits]) -> integer or float + * ceil(digits = 0) -> integer or float * - * Returns the smallest number greater than or equal to +num+ with - * a precision of +ndigits+ decimal digits (default: 0). + * Returns the smallest number that is greater than or equal to +self+ with + * a precision of +digits+ decimal digits. * - * Numeric implements this by converting its value to a Float and + * \Numeric implements this by converting +self+ to a Float and * invoking Float#ceil. */ @@ -2498,12 +2510,12 @@ num_ceil(int argc, VALUE *argv, VALUE num) /* * call-seq: - * num.round([ndigits]) -> integer or float + * round(digits = 0) -> integer or float * - * Returns +num+ rounded to the nearest value with - * a precision of +ndigits+ decimal digits (default: 0). + * Returns +self+ rounded to the nearest value with + * a precision of +digits+ decimal digits. * - * Numeric implements this by converting its value to a Float and + * \Numeric implements this by converting +self+ to a Float and * invoking Float#round. */ @@ -2515,12 +2527,12 @@ num_round(int argc, VALUE* argv, VALUE num) /* * call-seq: - * num.truncate([ndigits]) -> integer or float + * truncate(digits = 0) -> integer or float * - * Returns +num+ truncated (toward zero) to - * a precision of +ndigits+ decimal digits (default: 0). + * Returns +self+ truncated (toward zero) to + * a precision of +digits+ decimal digits. * - * Numeric implements this by converting its value to a Float and + * \Numeric implements this by converting +self+ to a Float and * invoking Float#truncate. */ @@ -2748,25 +2760,89 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) /* * call-seq: - * num.step(by: step, to: limit) {|i| block } -> self - * num.step(by: step, to: limit) -> an_enumerator - * num.step(by: step, to: limit) -> an_arithmetic_sequence - * num.step(limit=nil, step=1) {|i| block } -> self - * num.step(limit=nil, step=1) -> an_enumerator - * num.step(limit=nil, step=1) -> an_arithmetic_sequence - * - * Invokes the given block with the sequence of numbers starting at +num+, - * incremented by +step+ (defaulted to +1+) on each call. - * - * The loop finishes when the value to be passed to the block is greater than - * +limit+ (if +step+ is positive) or less than +limit+ (if +step+ is - * negative), where +limit+ is defaulted to infinity. - * - * In the recommended keyword argument style, either or both of - * +step+ and +limit+ (default infinity) can be omitted. In the - * fixed position argument style, zero as a step - * (i.e. num.step(limit, 0)) is not allowed for historical - * compatibility reasons. + * step(to = nil, by = 1) {|n| ... } -> self + * step(to = nil, by = 1) -> enumerator + * step(to = nil, by: 1) {|n| ... } -> self + * step(to = nil, by: 1) -> enumerator + * step(by: 1, to: ) {|n| ... } -> self + * step(by: 1, to: ) -> enumerator + * step(by: , to: nil) {|n| ... } -> self + * step(by: , to: nil) -> enumerator + * + * Generates a sequence of numbers; with a block given, traverses the sequence. + * + * Of the Core and Standard Library classes, + * Integer, Float, and Rational use this implementation. + * + * A quick example: + * + * squares = [] + * 1.step(by: 2, to: 10) {|i| squares.push(i*i) } + * squares # => [1, 9, 25, 49, 81] + * + * The generated sequence: + * + * - Begins with +self+. + * - Continues at intervals of +step+ (which may not be zero). + * - Ends with the last number that is within or equal to +limit+; + * that is, less than or equal to +limit+ if +step+ is positive, + * greater than or equal to +limit+ if +step+ is negative. + * If +limit+ is not given, the sequence is of infinite length. + * + * If a block is given, calls the block with each number in the sequence; + * returns +self+. If no block is given, returns an Enumerator::ArithmeticSequence. + * + * Keyword Arguments + * + * With keyword arguments +by+ and +to+, + * their values (or defaults) determine the step and limit: + * + * # Both keywords given. + * squares = [] + * 4.step(by: 2, to: 10) {|i| squares.push(i*i) } # => 4 + * squares # => [16, 36, 64, 100] + * cubes = [] + * 3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3 + * cubes # => [27.0, 3.375, 0.0, -3.375, -27.0] + * squares = [] + * 1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) } + * squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0] + * + * squares = [] + * Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) } + * squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0] + * + * # Only keyword to given. + * squares = [] + * 4.step(to: 10) {|i| squares.push(i*i) } # => 4 + * squares # => [16, 25, 36, 49, 64, 81, 100] + * # Only by given. + * + * # Only keyword by given + * squares = [] + * 4.step(by:2) {|i| squares.push(i*i); break if i > 10 } + * squares # => [16, 36, 64, 100, 144] + * + * # No block given. + * e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3)) + * e.class # => Enumerator::ArithmeticSequence + * + * Positional Arguments + * + * With optional positional arguments +limit+ and +step+, + * their values (or defaults) determine the step and limit: + * + * squares = [] + * 4.step(10, 2) {|i| squares.push(i*i) } # => 4 + * squares # => [16, 36, 64, 100] + * squares = [] + * 4.step(10) {|i| squares.push(i*i) } + * squares # => [16, 25, 36, 49, 64, 81, 100] + * squares = [] + * 4.step {|i| squares.push(i*i); break if i > 10 } # => nil + * squares # => [16, 25, 36, 49, 64, 81, 100, 121] + * + * Implementation Notes * * If all the arguments are integers, the loop operates using an integer * counter. @@ -2774,32 +2850,8 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) * If any of the arguments are floating point numbers, all are converted * to floats, and the loop is executed * floor(n + n*Float::EPSILON) + 1 times, - * where n = (limit - num)/step. - * - * Otherwise, the loop starts at +num+, uses either the - * less-than (<) or greater-than (>) operator - * to compare the counter against +limit+, - * and increments itself using the + operator. - * - * If no block is given, an Enumerator is returned instead. - * Especially, the enumerator is an Enumerator::ArithmeticSequence - * if both +limit+ and +step+ are kind of Numeric or nil. - * - * For example: - * - * p 1.step.take(4) - * p 10.step(by: -1).take(4) - * 3.step(to: 5) {|i| print i, " " } - * 1.step(10, 2) {|i| print i, " " } - * Math::E.step(to: Math::PI, by: 0.2) {|f| print f, " " } - * - * Will produce: + * where n = (limit - self)/step. * - * [1, 2, 3, 4] - * [10, 9, 8, 7] - * 3 4 5 - * 1 3 5 7 9 - * 2.718281828459045 2.9182818284590453 3.118281828459045 */ static VALUE -- cgit v1.2.3