1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improve docs for #truncate, #floor, and #ceil methods

Browse Source 
* numeric.c: [DOC] improve and harmonize documentation
  for {Float,Integer,Numeric}#{truncate,floor,ceil}.
* rational.c: [DOC] ditto for Rational#{truncate,floor,ceil}.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58244 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
stomar 2017-04-03 19:23:13 +00:00
parent d9e1cfe219
commit 5f22cfcc30
2 changed files with 125 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
numeric.c
View File

@ -1936,31 +1936,34 @@ flo_prev_float(VALUE vx)
* call-seq: * call-seq:
* float.floor([ndigits]) -> integer or float * float.floor([ndigits]) -> integer or float
* *
* Returns the largest number less than or equal to +float+ in * Returns the largest number less than or equal to +float+ with
* decimal digits (default 0 digits). * a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is positive, +self+ for zero, and floor down for negative. * 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 * 1.2.floor #=> 1
* 2.0.floor #=> 2 * 2.0.floor #=> 2
* (-1.2).floor #=> -2 * (-1.2).floor #=> -2
* (-2.0).floor #=> -2 * (-2.0).floor #=> -2
* *
* 1.234567.floor(2) #=> 1.23 * 1.234567.floor(2) #=> 1.23
* 1.234567.floor(3) #=> 1.234 * 1.234567.floor(3) #=> 1.234
* 1.234567.floor(4) #=> 1.2345 * 1.234567.floor(4) #=> 1.2345
* 1.234567.floor(5) #=> 1.23456 * 1.234567.floor(5) #=> 1.23456
* *
* 34567.89.floor(-5) #=> 0 * 34567.89.floor(-5) #=> 0
* 34567.89.floor(-4) #=> 30000 * 34567.89.floor(-4) #=> 30000
* 34567.89.floor(-3) #=> 34000 * 34567.89.floor(-3) #=> 34000
* 34567.89.floor(-2) #=> 34500 * 34567.89.floor(-2) #=> 34500
* 34567.89.floor(-1) #=> 34560 * 34567.89.floor(-1) #=> 34560
* 34567.89.floor(0) #=> 34567 * 34567.89.floor(0) #=> 34567
* 34567.89.floor(1) #=> 34567.8 * 34567.89.floor(1) #=> 34567.8
* 34567.89.floor(2) #=> 34567.89 * 34567.89.floor(2) #=> 34567.89
* 34567.89.floor(3) #=> 34567.89 * 34567.89.floor(3) #=> 34567.89
*/ */
static VALUE static VALUE
@ -1995,30 +1998,34 @@ flo_floor(int argc, VALUE *argv, VALUE num)
* call-seq: * call-seq:
* float.ceil([ndigits]) -> integer or float * float.ceil([ndigits]) -> integer or float
* *
* Returns the smallest number greater than or equal to +float+ in decimal * Returns the smallest number greater than or equal to +float+ with
* digits (default 0 digits). * a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is positive, +self+ for zero, and ceil up for negative. * 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 * 1.2.ceil #=> 2
* 2.0.ceil #=> 2 * 2.0.ceil #=> 2
* (-1.2).ceil #=> -1 * (-1.2).ceil #=> -1
* (-2.0).ceil #=> -2 * (-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 * 1.234567.ceil(2) #=> 1.24
* 34567.89.ceil(-4) #=> 40000 * 1.234567.ceil(3) #=> 1.235
* 34567.89.ceil(-3) #=> 35000 * 1.234567.ceil(4) #=> 1.2346
* 34567.89.ceil(-2) #=> 34600 * 1.234567.ceil(5) #=> 1.23457
* 34567.89.ceil(-1) #=> 34570 *
* 34567.89.ceil(0) #=> 34568 * 34567.89.ceil(-5) #=> 100000
* 34567.89.ceil(1) #=> 34567.9 * 34567.89.ceil(-4) #=> 40000
* 34567.89.ceil(2) #=> 34567.89 * 34567.89.ceil(-3) #=> 35000
* 34567.89.ceil(3) #=> 34567.89 * 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 static VALUE
@ -2357,10 +2364,19 @@ flo_to_i(VALUE num)
* call-seq: * call-seq:
* float.truncate([ndigits]) -> integer or float * 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).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is more than zero. * with at least <code>ndigits.abs</code> trailing zeros.
*
* Returns a floating point number when +ndigits+ is positive,
* otherwise returns an integer.
*
* 2.8.truncate #=> 2
* (-2.8).truncate #=> -2
* 1.234567.truncate(2) #=> 1.23
* 34567.89.truncate(-2) #=> 34500
*/ */
static VALUE static VALUE
flo_truncate(int argc, VALUE *argv, VALUE num) flo_truncate(int argc, VALUE *argv, VALUE num)
@ -2403,13 +2419,11 @@ flo_negative_p(VALUE num)
* call-seq: * call-seq:
* num.floor([ndigits]) -> integer or float * num.floor([ndigits]) -> integer or float
* *
* Returns the largest integer less than or equal to +num+. * Returns the largest number less than or equal to +num+ with
* a precision of +ndigits+ decimal digits (default: 0).
* *
* Numeric implements this by converting an Integer to a Float and invoking * Numeric implements this by converting its value to a Float and
* Float#floor. * invoking Float#floor.
*
* 1.floor #=> 1
* (-1).floor #=> -1
*/ */
static VALUE static VALUE
@ -2423,16 +2437,11 @@ num_floor(int argc, VALUE *argv, VALUE num)
* call-seq: * call-seq:
* num.ceil([ndigits]) -> integer or float * num.ceil([ndigits]) -> integer or float
* *
* Returns the smallest possible Integer that is greater than or equal to * Returns the smallest number greater than or equal to +num+ with
* +num+. * a precision of +ndigits+ decimal digits (default: 0).
* *
* Numeric achieves this by converting itself to a Float then invoking * Numeric implements this by converting its value to a Float and
* Float#ceil. * invoking Float#ceil.
*
* 1.ceil #=> 1
* 1.2.ceil #=> 2
* (-1.2).ceil #=> -1
* (-1.0).ceil #=> -1
*/ */
static VALUE static VALUE
@ -2462,10 +2471,11 @@ num_round(int argc, VALUE* argv, VALUE num)
* call-seq: * call-seq:
* num.truncate([ndigits]) -> integer or float * 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 * Numeric implements this by converting its value to a Float and
* Float#truncate. * invoking Float#truncate.
*/ */
static VALUE static VALUE
@ -5069,15 +5079,19 @@ int_round(int argc, VALUE* argv, VALUE num)
* call-seq: * call-seq:
* int.floor([ndigits]) -> integer or float * int.floor([ndigits]) -> integer or float
* *
* Returns the largest number less than or equal to +int+ in decimal * Returns the largest number less than or equal to +int+ with
* digits (default 0 digits). * a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is positive, +self+ for zero, and floor down for negative. * with at least <code>ndigits.abs</code> trailing zeros.
* *
* 1.floor #=> 1 * Returns a floating point number when +ndigits+ is positive,
* 1.floor(2) #=> 1.0 * +self+ for zero, and an integer for negative.
* 15.floor(-1) #=> 10 *
* 1.floor #=> 1
* 1.floor(2) #=> 1.0
* 18.floor(-1) #=> 10
* (-18).floor(-1) #=> -20
*/ */
static VALUE static VALUE
@ -5101,15 +5115,19 @@ int_floor(int argc, VALUE* argv, VALUE num)
* call-seq: * call-seq:
* int.ceil([ndigits]) -> integer or float * int.ceil([ndigits]) -> integer or float
* *
* Returns the smallest number than or equal to +int+ in decimal * Returns the smallest number greater than or equal to +int+ with
* digits (default 0 digits). * a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is positive, +self+ for zero, and ceil up for negative. * with at least <code>ndigits.abs</code> trailing zeros.
* *
* 1.ceil #=> 1 * Returns a floating point number when +ndigits+ is positive,
* 1.ceil(2) #=> 1.0 * +self+ for zero, and an integer for negative.
* 15.ceil(-1) #=> 20 *
* 1.ceil #=> 1
* 1.ceil(2) #=> 1.0
* 18.ceil(-1) #=> 20
* (-18).ceil(-1) #=> -10
*/ */
static VALUE static VALUE
@ -5133,15 +5151,19 @@ int_ceil(int argc, VALUE* argv, VALUE num)
* call-seq: * call-seq:
* int.truncate([ndigits]) -> integer or float * int.truncate([ndigits]) -> integer or float
* *
* Returns the smallest number than or equal to +int+ in decimal * Returns +int+ truncated (toward zero) to
* digits (default 0 digits). * a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * When the precision is negative, the returned value is an integer
* is positive, +self+ for zero, and truncate up for negative. * with at least <code>ndigits.abs</code> trailing zeros.
* *
* 1.truncate #=> 1 * Returns a floating point number when +ndigits+ is positive,
* 1.truncate(2) #=> 1.0 * +self+ for zero, and an integer for negative.
* 15.truncate(-1) #=> 10 *
* 1.truncate #=> 1
* 1.truncate(2) #=> 1.0
* 18.truncate(-1) #=> 10
* (-18).truncate(-1) #=> -10
*/ */
static VALUE static VALUE

36
rational.c
View File

@ -1438,10 +1438,16 @@ f_round_common(int argc, VALUE *argv, VALUE self, VALUE (*func)(VALUE))
/* /*
* call-seq: * call-seq:
* rat.floor -> integer * rat.floor([ndigits]) -> integer or rational
* rat.floor(precision=0) -> 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(3).floor #=> 3
* Rational(2, 3).floor #=> 0 * Rational(2, 3).floor #=> 0
@ -1462,10 +1468,16 @@ nurat_floor_n(int argc, VALUE *argv, VALUE self)
/* /*
* call-seq: * call-seq:
* rat.ceil -> integer * rat.ceil([ndigits]) -> integer or rational
* rat.ceil(precision=0) -> integer or rational
* *
* Returns the truncated value (toward positive infinity). * Returns the smallest number greater 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).ceil #=> 3 * Rational(3).ceil #=> 3
* Rational(2, 3).ceil #=> 1 * Rational(2, 3).ceil #=> 1
@ -1486,10 +1498,16 @@ nurat_ceil_n(int argc, VALUE *argv, VALUE self)
/* /*
* call-seq: * call-seq:
* rat.truncate -> integer * rat.truncate([ndigits]) -> integer or rational
* rat.truncate(precision=0) -> integer or rational
* *
* Returns the truncated value (toward zero). * 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 a rational when +ndigits+ is positive,
* otherwise returns an integer.
* *
* Rational(3).truncate #=> 3 * Rational(3).truncate #=> 3
* Rational(2, 3).truncate #=> 0 * Rational(2, 3).truncate #=> 0