ruby-changes:46130
From: stomar <ko1@a...>
Date: Tue, 4 Apr 2017 04:23:18 +0900 (JST)
Subject: [ruby-changes:46130] stomar:r58244 (trunk): improve docs for #truncate, #floor, and #ceil methods
stomar 2017-04-04 04:23:13 +0900 (Tue, 04 Apr 2017) New Revision: 58244 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=58244 Log: improve docs for #truncate, #floor, and #ceil methods * numeric.c: [DOC] improve and harmonize documentation for {Float,Integer,Numeric}#{truncate,floor,ceil}. * rational.c: [DOC] ditto for Rational#{truncate,floor,ceil}. Modified files: trunk/numeric.c trunk/rational.c Index: rational.c =================================================================== --- rational.c (revision 58243) +++ rational.c (revision 58244) @@ -1438,10 +1438,16 @@ f_round_common(int argc, VALUE *argv, VA https://github.com/ruby/ruby/blob/trunk/rational.c#L1438 /* * call-seq: - * rat.floor -> integer - * rat.floor(precision=0) -> integer or rational + * rat.floor([ndigits]) -> integer or rational * - * Returns the truncated value (toward negative infinity). + * Returns the largest number less than or equal to +rat+ 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 rational when +ndigits+ is positive, + * otherwise returns an integer. * * Rational(3).floor #=> 3 * Rational(2, 3).floor #=> 0 @@ -1462,10 +1468,16 @@ nurat_floor_n(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/rational.c#L1468 /* * call-seq: - * rat.ceil -> integer - * rat.ceil(precision=0) -> integer or rational + * rat.ceil([ndigits]) -> integer or rational + * + * Returns the smallest number greater than or equal to +rat+ with + * a precision of +ndigits+ decimal digits (default: 0). * - * Returns the truncated value (toward positive infinity). + * When the precision is negative, the returned value is an integer + * with at least <code>ndigits.abs</code> trailing zeros. + * + * Returns a rational when +ndigits+ is positive, + * otherwise returns an integer. * * Rational(3).ceil #=> 3 * Rational(2, 3).ceil #=> 1 @@ -1486,10 +1498,16 @@ nurat_ceil_n(int argc, VALUE *argv, VALU https://github.com/ruby/ruby/blob/trunk/rational.c#L1498 /* * call-seq: - * rat.truncate -> integer - * rat.truncate(precision=0) -> integer or rational + * rat.truncate([ndigits]) -> integer or rational + * + * Returns +rat+ truncated (toward zero) to + * 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 the truncated value (toward zero). + * Returns a rational when +ndigits+ is positive, + * otherwise returns an integer. * * Rational(3).truncate #=> 3 * Rational(2, 3).truncate #=> 0 Index: numeric.c =================================================================== --- numeric.c (revision 58243) +++ numeric.c (revision 58244) @@ -1936,31 +1936,34 @@ flo_prev_float(VALUE vx) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1936 * call-seq: * float.floor([ndigits]) -> integer or float * - * Returns the largest number less than or equal to +float+ in - * decimal digits (default 0 digits). + * 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is positive, +self+ for zero, and floor down for negative. + * 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 + * 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 */ static VALUE @@ -1995,30 +1998,34 @@ flo_floor(int argc, VALUE *argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L1998 * call-seq: * float.ceil([ndigits]) -> integer or float * - * Returns the smallest number greater than or equal to +float+ in decimal - * digits (default 0 digits). + * Returns the smallest number greater 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is positive, +self+ for zero, and ceil up for negative. + * 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 + * + * 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 */ static VALUE @@ -2357,10 +2364,19 @@ flo_to_i(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2364 * call-seq: * float.truncate([ndigits]) -> integer or float * - * Truncates +float+ to a given precision in decimal digits (default 0 digits). + * Returns +float+ truncated (toward zero) to + * 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is more than zero. + * 2.8.truncate #=> 2 + * (-2.8).truncate #=> -2 + * 1.234567.truncate(2) #=> 1.23 + * 34567.89.truncate(-2) #=> 34500 */ static VALUE flo_truncate(int argc, VALUE *argv, VALUE num) @@ -2403,13 +2419,11 @@ flo_negative_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L2419 * call-seq: * num.floor([ndigits]) -> integer or float * - * Returns the largest integer less than or equal to +num+. - * - * Numeric implements this by converting an Integer to a Float and invoking - * Float#floor. + * Returns the largest number less than or equal to +num+ with + * a precision of +ndigits+ decimal digits (default: 0). * - * 1.floor #=> 1 - * (-1).floor #=> -1 + * Numeric implements this by converting its value to a Float and + * invoking Float#floor. */ static VALUE @@ -2423,16 +2437,11 @@ num_floor(int argc, VALUE *argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L2437 * call-seq: * num.ceil([ndigits]) -> integer or float * - * Returns the smallest possible Integer that is greater than or equal to - * +num+. - * - * Numeric achieves this by converting itself to a Float then invoking - * Float#ceil. + * Returns the smallest number greater than or equal to +num+ with + * a precision of +ndigits+ decimal digits (default: 0). * - * 1.ceil #=> 1 - * 1.2.ceil #=> 2 - * (-1.2).ceil #=> -1 - * (-1.0).ceil #=> -1 + * Numeric implements this by converting its value to a Float and + * invoking Float#ceil. */ static VALUE @@ -2462,10 +2471,11 @@ num_round(int argc, VALUE* argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L2471 * call-seq: * num.truncate([ndigits]) -> integer or float * - * Returns +num+ truncated to an Integer. + * Returns +num+ truncated (toward zero) to + * a precision of +ndigits+ decimal digits (default: 0). * - * Numeric implements this by converting its value to a Float and invoking - * Float#truncate. + * Numeric implements this by converting its value to a Float and + * invoking Float#truncate. */ static VALUE @@ -5069,15 +5079,19 @@ int_round(int argc, VALUE* argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L5079 * call-seq: * int.floor([ndigits]) -> integer or float * - * Returns the largest number less than or equal to +int+ in decimal - * digits (default 0 digits). + * Returns the largest number less than or equal to +int+ 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is positive, +self+ for zero, and floor down for negative. + * Returns a floating point number when +ndigits+ is positive, + * +self+ for zero, and an integer for negative. * - * 1.floor #=> 1 - * 1.floor(2) #=> 1.0 - * 15.floor(-1) #=> 10 + * 1.floor #=> 1 + * 1.floor(2) #=> 1.0 + * 18.floor(-1) #=> 10 + * (-18).floor(-1) #=> -20 */ static VALUE @@ -5101,15 +5115,19 @@ int_floor(int argc, VALUE* argv, VALUE n https://github.com/ruby/ruby/blob/trunk/numeric.c#L5115 * call-seq: * int.ceil([ndigits]) -> integer or float * - * Returns the smallest number than or equal to +int+ in decimal - * digits (default 0 digits). + * Returns the smallest number greater than or equal to +int+ 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is positive, +self+ for zero, and ceil up for negative. + * Returns a floating point number when +ndigits+ is positive, + * +self+ for zero, and an integer for negative. * - * 1.ceil #=> 1 - * 1.ceil(2) #=> 1.0 - * 15.ceil(-1) #=> 20 + * 1.ceil #=> 1 + * 1.ceil(2) #=> 1.0 + * 18.ceil(-1) #=> 20 + * (-18).ceil(-1) #=> -10 */ static VALUE @@ -5133,15 +5151,19 @@ int_ceil(int argc, VALUE* argv, VALUE nu https://github.com/ruby/ruby/blob/trunk/numeric.c#L5151 * call-seq: * int.truncate([ndigits]) -> integer or float * - * Returns the smallest number than or equal to +int+ in decimal - * digits (default 0 digits). + * Returns +int+ truncated (toward zero) to + * 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. * - * Precision may be negative. Returns a floating point number when +ndigits+ - * is positive, +self+ for zero, and truncate up for negative. + * Returns a floating point number when +ndigits+ is positive, + * +self+ for zero, and an integer for negative. * - * 1.truncate #=> 1 - * 1.truncate(2) #=> 1.0 - * 15.truncate(-1) #=> 10 + * 1.truncate #=> 1 + * 1.truncate(2) #=> 1.0 + * 18.truncate(-1) #=> 10 + * (-18).truncate(-1) #=> -10 */ static VALUE -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/