From 9faa59919674ab33a326e479e97864a7bd8067d3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar 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(-) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index 64d8536413..b589acd192 100644 --- a/numeric.c +++ b/numeric.c @@ -2091,45 +2091,6 @@ rb_float_floor(VALUE num, int ndigits) } } -/* - * 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 ndigits.abs 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) 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 + * ndigits.abs 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) /* * 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 ndigits.abs 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 + * ndigits.abs 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) /* * 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 ndigits.abs 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 ndigits.abs 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+: - * - * * :up or +nil+: round half away from zero (default) - * * :down: round half toward zero - * * :even: 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) /* * 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) /* * call-seq: - * float.truncate([ndigits]) -> integer or float + * truncate(ndigits = 0) -> float or integer * - * Returns +float+ truncated (toward zero) to - * a precision of +ndigits+ decimal digits (default: 0). + * Returns +self+ truncated (toward zero) to + * a precision of +ndigits+ decimal digits. * - * When the precision is negative, the returned value is an integer - * with at least ndigits.abs trailing zeros. + * When +ndigits+ is positive, returns a float with +ndigits+ digits + * after the decimal point (as available): * - * Returns a floating point number when +ndigits+ is positive, - * otherwise returns an integer. + * f = 12345.6789 + * f.truncate(1) # => 12345.6 + * f.truncate(3) # => 12345.678 + * f = -12345.6789 + * f.truncate(1) # => -12345.6 + * f.truncate(3) # => -12345.678 * - * 2.8.truncate #=> 2 - * (-2.8).truncate #=> -2 - * 1.234567.truncate(2) #=> 1.23 - * 34567.89.truncate(-2) #=> 34500 + * When +ndigits+ is negative, returns an integer + * with at least ndigits.abs trailing zeros: * - * Note that the limited precision of floating point arithmetic - * might lead to surprising results: + * f = 12345.6789 + * f.truncate(0) # => 12345 + * f.truncate(-3) # => 12000 + * f = -12345.6789 + * f.truncate(0) # => -12345 + * f.truncate(-3) # => -12000 + * + * Note that the limited precision of floating-point arithmetic + * may lead to surprising results: * * (0.3 / 0.1).truncate #=> 2 (!) + * + * Related: Float#round. + * */ static VALUE flo_truncate(int argc, VALUE *argv, VALUE num) -- cgit v1.2.1