ruby-changes:69924
From: Burdette <ko1@a...>
Date: Thu, 25 Nov 2021 06:15:27 +0900 (JST)
Subject: [ruby-changes:69924] 9faa599196 (master): Enhanced RDoc for Float#floor (#5167)
https://git.ruby-lang.org/ruby.git/commit/?id=9faa599196 From 9faa59919674ab33a326e479e97864a7bd8067d3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 24 Nov 2021 15:15:12 -0600 Subject: Enhanced RDoc for Float#floor (#5167) * Enhanced RDoc for Float#floor * Enhanced RDoc for Float * Enhanced RDoc for Float --- numeric.c | 284 ++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 146 insertions(+), 138 deletions(-) diff --git a/numeric.c b/numeric.c index 64d8536413d..b589acd192a 100644 --- a/numeric.c +++ b/numeric.c @@ -2091,45 +2091,6 @@ rb_float_floor(VALUE num, int ndigits) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2091 } } -/* - * call-seq: - * float.floor([ndigits]) -> integer or float - * - * Returns the largest number less than or equal to +float+ with - * a precision of +ndigits+ decimal digits (default: 0). - * - * When the precision is negative, the returned value is an integer - * with at least <code>ndigits.abs</code> trailing zeros. - * - * Returns a floating point number when +ndigits+ is positive, - * otherwise returns an integer. - * - * 1.2.floor #=> 1 - * 2.0.floor #=> 2 - * (-1.2).floor #=> -2 - * (-2.0).floor #=> -2 - * - * 1.234567.floor(2) #=> 1.23 - * 1.234567.floor(3) #=> 1.234 - * 1.234567.floor(4) #=> 1.2345 - * 1.234567.floor(5) #=> 1.23456 - * - * 34567.89.floor(-5) #=> 0 - * 34567.89.floor(-4) #=> 30000 - * 34567.89.floor(-3) #=> 34000 - * 34567.89.floor(-2) #=> 34500 - * 34567.89.floor(-1) #=> 34560 - * 34567.89.floor(0) #=> 34567 - * 34567.89.floor(1) #=> 34567.8 - * 34567.89.floor(2) #=> 34567.89 - * 34567.89.floor(3) #=> 34567.89 - * - * Note that the limited precision of floating point arithmetic - * might lead to surprising results: - * - * (0.3 / 0.1).floor #=> 2 (!) - */ - static int flo_ndigits(int argc, VALUE *argv) { @@ -2139,6 +2100,42 @@ flo_ndigits(int argc, VALUE *argv) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2100 return 0; } +/* + * call-seq: + * floor(ndigits = 0) -> float or integer + * + * Returns the largest number less than or equal to +self+ with + * a precision of +ndigits+ decimal digits. + * + * When +ndigits+ is positive, returns a float with +ndigits+ + * digits after the decimal point (as available): + * + * f = 12345.6789 + * f.floor(1) # => 12345.6 + * f.floor(3) # => 12345.678 + * f = -12345.6789 + * f.floor(1) # => -12345.7 + * f.floor(3) # => -12345.679 + * + * When +ndigits+ is non-positive, returns an integer with at least + * <code>ndigits.abs</code> trailing zeros: + * + * f = 12345.6789 + * f.floor(0) # => 12345 + * f.floor(-3) # => 12000 + * f = -12345.6789 + * f.floor(0) # => -12346 + * f.floor(-3) # => -13000 + * + * Note that the limited precision of floating-point arithmetic + * may lead to surprising results: + * + * (0.3 / 0.1).floor #=> 2 (!) + * + * Related: Float#ceil. + * + */ + static VALUE flo_floor(int argc, VALUE *argv, VALUE num) { @@ -2148,41 +2145,38 @@ flo_floor(int argc, VALUE *argv, VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2145 /* * call-seq: - * float.ceil([ndigits]) -> integer or float + * ceil(ndigits = 0) -> float or integer * - * Returns the smallest number greater than or equal to +float+ with - * a precision of +ndigits+ decimal digits (default: 0). + * Returns the smallest number greater than or equal to +self+ with + * a precision of +ndigits+ decimal digits. * - * When the precision is negative, the returned value is an integer - * with at least <code>ndigits.abs</code> trailing zeros. - * - * Returns a floating point number when +ndigits+ is positive, - * otherwise returns an integer. - * - * 1.2.ceil #=> 2 - * 2.0.ceil #=> 2 - * (-1.2).ceil #=> -1 - * (-2.0).ceil #=> -2 - * - * 1.234567.ceil(2) #=> 1.24 - * 1.234567.ceil(3) #=> 1.235 - * 1.234567.ceil(4) #=> 1.2346 - * 1.234567.ceil(5) #=> 1.23457 - * - * 34567.89.ceil(-5) #=> 100000 - * 34567.89.ceil(-4) #=> 40000 - * 34567.89.ceil(-3) #=> 35000 - * 34567.89.ceil(-2) #=> 34600 - * 34567.89.ceil(-1) #=> 34570 - * 34567.89.ceil(0) #=> 34568 - * 34567.89.ceil(1) #=> 34567.9 - * 34567.89.ceil(2) #=> 34567.89 - * 34567.89.ceil(3) #=> 34567.89 - * - * Note that the limited precision of floating point arithmetic - * might lead to surprising results: + * When +ndigits+ is positive, returns a float with +ndigits+ + * digits after the decimal point (as available): + * + * f = 12345.6789 + * f.ceil(1) # => 12345.7 + * f.ceil(3) # => 12345.679 + * f = -12345.6789 + * f.ceil(1) # => -12345.6 + * f.ceil(3) # => -12345.678 + * + * When +ndigits+ is non-positive, returns an integer with at least + * <code>ndigits.abs</code> trailing zeros: + * + * f = 12345.6789 + * f.ceil(0) # => 12346 + * f.ceil(-3) # => 13000 + * f = -12345.6789 + * f.ceil(0) # => -12345 + * f.ceil(-3) # => -12000 + * + * Note that the limited precision of floating-point arithmetic + * may lead to surprising results: * * (2.1 / 0.7).ceil #=> 4 (!) + * + * Related: Float#floor. + * */ static VALUE @@ -2391,54 +2385,57 @@ rb_int_truncate(VALUE num, int ndigits) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2385 /* * call-seq: - * float.round([ndigits] [, half: mode]) -> integer or float + * round(ndigits = 0, half: :up]) -> integer or float + * + * Returns +self+ rounded to the nearest value with + * a precision of +ndigits+ decimal digits. * - * Returns +float+ rounded to the nearest value with - * a precision of +ndigits+ decimal digits (default: 0). + * When +ndigits+ is non-negative, returns a float with +ndigits+ + * after the decimal point (as available): + * + * f = 12345.6789 + * f.round(1) # => 12345.7 + * f.round(3) # => 12345.679 + * f = -12345.6789 + * f.round(1) # => -12345.7 + * f.round(3) # => -12345.679 + * + * When +ndigits+ is negative, returns an integer + * with at least <tt>ndigits.abs</tt> trailing zeros: + * + * f = 12345.6789 + * f.round(0) # => 12346 + * f.round(-3) # => 12000 + * f = -12345.6789 + * f.round(0) # => -12346 + * f.round(-3) # => -12000 + * + * If keyword argument +half+ is given, + * and +self+ is equidistant from the two candidate values, + * the rounding is according to the given +half+ value: + * + * - +:up+ or +nil+: round away from zero: + * + * 2.5.round(half: :up) # => 3 + * 3.5.round(half: :up) # => 4 + * (-2.5).round(half: :up) # => -3 + * + * - +:down+: round toward zero: + * + * 2.5.round(half: :down) # => 2 + * 3.5.round(half: :down) # => 3 + * (-2.5).round(half: :down) # => -2 + * + * - +:even+: round toward the candidate whose last nonzero digit is even: + * + * 2.5.round(half: :even) # => 2 + * 3.5.round(half: :even) # => 4 + * (-2.5).round(half: :even) # => -2 + * + * Raises and exception if the value for +half+ is invalid. + * + * Related: Float#truncate. * - * When the precision is negative, the returned value is an integer - * with at least <code>ndigits.abs</code> trailing zeros. - * - * Returns a floating point number when +ndigits+ is positive, - * otherwise returns an integer. - * - * 1.4.round #=> 1 - * 1.5.round #=> 2 - * 1.6.round #=> 2 - * (-1.5).round #=> -2 - * - * 1.234567.round(2) #=> 1.23 - * 1.234567.round(3) #=> 1.235 - * 1.234567.round(4) #=> 1.2346 - * 1.234567.round(5) #=> 1.23457 - * - * 34567.89.round(-5) #=> 0 - * 34567.89.round(-4) #=> 30000 - * 34567.89.round(-3) #=> 35000 - * 34567.89.round(-2) #=> 34600 - * 34567.89.round(-1) #=> 34570 - * 34567.89.round(0) #=> 34568 - * 34567.89.round(1) #=> 34567.9 - * 34567.89.round(2) #=> 34567.89 - * 34567.89.round(3) #=> 34567.89 - * - * If the optional +half+ keyword argument is given, - * numbers that are half-way between two possible rounded values - * will be rounded according to the specified tie-breaking +mode+: - * - * * <code>:up</code> or +nil+: round half away from zero (default) - * * <code>:down</code>: round half toward zero - * * <code>:even</code>: round half toward the nearest even number - * - * 2.5.round(half: :up) #=> 3 - * 2.5.round(half: :down) #=> 2 - * 2.5.round(half: :even) #=> 2 - * 3.5.round(half: :up) #=> 4 - * 3.5.round(half: :down) #=> 3 - * 3.5.round(half: :even) #=> 4 - * (-2.5).round(half: :up) #=> -3 - * (-2.5).round(half: :down) #=> -2 - * (-2.5).round(half: :even) #=> -2 */ static VALUE @@ -2519,20 +2516,19 @@ float_round_underflow(int ndigits, int binexp) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2516 /* * call-seq: - * float.to_i -> integer - * float.to_int -> integer + * to_i -> integer * - * Returns the +float+ truncated to an Integer. + * Returns +self+ truncated to an Integer. * - * 1.2.to_i #=> 1 - * (-1.2).to_i #=> -1 + * 1.2.to_i # => 1 + * (-1.2).to_i # => -1 * - * Note that the limited precision of floating point arithmetic - * might lead to surprising results: + * Note that the limited precision of floating-point arithmetic + * may lead to surprising results: * - * (0.3 / 0.1).to_i #=> 2 (!) + * (0.3 / 0.1).to_i # => 2 (!) * - * #to_int is an alias for #to_i. + * Float#to_int is an alias for Float#to_i. */ static VALUE @@ -2548,26 +2544,38 @@ flo_to_i(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2544 /* * call-seq: - * float.truncate([ndigits]) -> integer or float + * truncate(ndigits = 0) -> float or integer * - * Returns +float+ truncated (toward zero) to - * a (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/