kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

improve docs for #round methods

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

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58242 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
stomar 2017-04-03 19:19:20 +00:00
parent b16f9112ed
commit c76aac30f2
2 changed files with 82 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
numeric.c
View file

@ -2215,47 +2215,54 @@ rb_int_truncate(VALUE num, int ndigits)
/* /*
* call-seq: * call-seq:
* float.round([ndigits] [, half: symbol]) -> integer or float * float.round([ndigits] [, half: mode]) -> integer or float
* *
* Rounds +float+ to a given precision in decimal digits (default 0 digits). * Returns +float+ rounded to the nearest value with
* 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.
* *
* 1.4.round #=> 1 * 1.4.round #=> 1
* 1.5.round #=> 2 * 1.5.round #=> 2
* 1.6.round #=> 2 * 1.6.round #=> 2
* (-1.5).round #=> -2 * (-1.5).round #=> -2
* *
* 1.234567.round(2) #=> 1.23 * 1.234567.round(2) #=> 1.23
* 1.234567.round(3) #=> 1.235 * 1.234567.round(3) #=> 1.235
* 1.234567.round(4) #=> 1.2346 * 1.234567.round(4) #=> 1.2346
* 1.234567.round(5) #=> 1.23457 * 1.234567.round(5) #=> 1.23457
* *
* 34567.89.round(-5) #=> 0 * 34567.89.round(-5) #=> 0
* 34567.89.round(-4) #=> 30000 * 34567.89.round(-4) #=> 30000
* 34567.89.round(-3) #=> 35000 * 34567.89.round(-3) #=> 35000
* 34567.89.round(-2) #=> 34600 * 34567.89.round(-2) #=> 34600
* 34567.89.round(-1) #=> 34570 * 34567.89.round(-1) #=> 34570
* 34567.89.round(0) #=> 34568 * 34567.89.round(0) #=> 34568
* 34567.89.round(1) #=> 34567.9 * 34567.89.round(1) #=> 34567.9
* 34567.89.round(2) #=> 34567.89 * 34567.89.round(2) #=> 34567.89
* 34567.89.round(3) #=> 34567.89 * 34567.89.round(3) #=> 34567.89
* *
* If the <code>half:</code> optional keyword is given, just-half number * If the optional +half+ keyword argument is given,
* will be rounded according to that value. * numbers that are half-way between two possible rounded values
* Supported values for this keyword are follows. * will be rounded according to the specified tie-breaking +mode+:
* *
* * <code>:up</code> or +nil+: the result will be rounded away from zero * * <code>:up</code> or +nil+: round half away from zero (default)
* * <code>:even</code>: the result will be rounded to nearest even number * * <code>:down</code>: round half toward zero
* * <code>:down</code>: the result will be rounded close to zero * * <code>:even</code>: round half toward the nearest even number
* *
* 2.5.round(half: :up) #=> 3 * 2.5.round(half: :up) #=> 3
* 2.5.round(half: :even) #=> 2 * 2.5.round(half: :down) #=> 2
* 2.5.round(half: :down) #=> 2 * 2.5.round(half: :even) #=> 2
* 3.5.round(half: :up) #=> 4 * 3.5.round(half: :up) #=> 4
* 3.5.round(half: :even) #=> 4 * 3.5.round(half: :down) #=> 3
* 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 static VALUE
@ -2438,13 +2445,11 @@ num_ceil(int argc, VALUE *argv, VALUE num)
* call-seq: * call-seq:
* num.round([ndigits]) -> integer or float * num.round([ndigits]) -> integer or float
* *
* Rounds +num+ to a given precision in decimal digits (default 0 digits). * Returns +num+ rounded to the nearest value with
* a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a floating point number when +ndigits+ * Numeric implements this by converting its value to a Float and
* is more than zero. * invoking Float#round.
*
* Numeric implements this by converting itself to a Float and invoking
* Float#round.
*/ */
static VALUE static VALUE
@ -5010,25 +5015,34 @@ int_dotimes(VALUE num)
/* /*
* Document-method: Integer#round * Document-method: Integer#round
* call-seq: * call-seq:
* int.round([ndigits] [, half: symbol]) -> integer or float * int.round([ndigits] [, half: mode]) -> integer or float
* *
* Rounds +int+ to a given precision in decimal digits (default 0 digits). * Returns +int+ rounded to the nearest value with
* 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 round down for negative. * with at least <code>ndigits.abs</code> trailing zeros.
* *
* 1.round #=> 1 * Returns a floating point number when +ndigits+ is positive,
* 1.round(2) #=> 1.0 * +self+ for zero, and an integer for negative.
* 15.round(-1) #=> 20
* *
* The <code>half:</code> optional keyword same as Float#round is available. * 1.round #=> 1
* 1.round(2) #=> 1.0
* 15.round(-1) #=> 20
* (-15).round(-1) #=> -20
* *
* 25.round(-1, half: :up) #=> 30 * The optional +half+ keyword argument is available
* 25.round(-1, half: :even) #=> 20 * similar to Float#round.
* 25.round(-1, half: :down) #=> 20 *
* 35.round(-1, half: :up) #=> 40 * 25.round(-1, half: :up) #=> 30
* 35.round(-1, half: :even) #=> 40 * 25.round(-1, half: :down) #=> 20
* 35.round(-1, half: :down) #=> 30 * 25.round(-1, half: :even) #=> 20
* 35.round(-1, half: :up) #=> 40
* 35.round(-1, half: :down) #=> 30
* 35.round(-1, half: :even) #=> 40
* (-25).round(-1, half: :up) #=> -30
* (-25).round(-1, half: :down) #=> -20
* (-25).round(-1, half: :even) #=> -20
*/ */
static VALUE static VALUE

30
rational.c
View file

@ -1510,12 +1510,16 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
/* /*
* call-seq: * call-seq:
* rat.round([ndigits] [, half: symbol]) -> integer or rational * rat.round([ndigits] [, half: mode]) -> integer or rational
* *
* Rounds +rat+ to a given precision in decimal digits (default 0 digits). * Returns +rat+ rounded to the nearest value with
* a precision of +ndigits+ decimal digits (default: 0).
* *
* Precision may be negative. Returns a rational 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 rational when +ndigits+ is positive,
* otherwise returns an integer.
* *
* Rational(3).round #=> 3 * Rational(3).round #=> 3
* Rational(2, 3).round #=> 1 * Rational(2, 3).round #=> 1
@ -1528,14 +1532,18 @@ nurat_truncate_n(int argc, VALUE *argv, VALUE self)
* Rational('-123.456').round(+1).to_f #=> -123.5 * Rational('-123.456').round(+1).to_f #=> -123.5
* Rational('-123.456').round(-1) #=> -120 * Rational('-123.456').round(-1) #=> -120
* *
* The <code>half:</code> optional keyword same as Float#round is available. * The optional +half+ keyword argument is available
* similar to Float#round.
* *
* Rational(25, 100).round(1, half: :up) #=> (3/10) * Rational(25, 100).round(1, half: :up) #=> (3/10)
* Rational(25, 100).round(1, half: :even) #=> (1/5) * Rational(25, 100).round(1, half: :down) #=> (1/5)
* Rational(25, 100).round(1, half: :down) #=> (1/5) * Rational(25, 100).round(1, half: :even) #=> (1/5)
* Rational(35, 100).round(1, half: :up) #=> (2/5) * Rational(35, 100).round(1, half: :up) #=> (2/5)
* Rational(35, 100).round(1, half: :even) #=> (2/5) * Rational(35, 100).round(1, half: :down) #=> (3/10)
* Rational(35, 100).round(1, half: :down) #=> (3/10) * Rational(35, 100).round(1, half: :even) #=> (2/5)
* Rational(-25, 100).round(1, half: :up) #=> (-3/10)
* Rational(-25, 100).round(1, half: :down) #=> (-1/5)
* Rational(-25, 100).round(1, half: :even) #=> (-1/5)
*/ */
static VALUE static VALUE
nurat_round_n(int argc, VALUE *argv, VALUE self) nurat_round_n(int argc, VALUE *argv, VALUE self)