ruby-changes:70469
From: BurdetteLamar <ko1@a...>
Date: Fri, 24 Dec 2021 02:29:58 +0900 (JST)
Subject: [ruby-changes:70469] 01b2ccaa95 (master): [ruby/bigdecimal] Enhanced RDoc for bigdecimal.c
https://git.ruby-lang.org/ruby.git/commit/?id=01b2ccaa95 From 01b2ccaa958b7a4a3d38706277045882a509379d Mon Sep 17 00:00:00 2001 From: BurdetteLamar <BurdetteLamar@Y...> Date: Thu, 14 Oct 2021 13:57:36 -0500 Subject: [ruby/bigdecimal] Enhanced RDoc for bigdecimal.c https://github.com/ruby/bigdecimal/commit/31a7a37426 --- ext/bigdecimal/bigdecimal.c | 266 +++++++++++++++++++++++++++++++++----------- 1 file changed, 201 insertions(+), 65 deletions(-) diff --git a/ext/bigdecimal/bigdecimal.c b/ext/bigdecimal/bigdecimal.c index 1d829132290..22d9c5c01c5 100644 --- a/ext/bigdecimal/bigdecimal.c +++ b/ext/bigdecimal/bigdecimal.c @@ -275,11 +275,13 @@ GetVpValue(VALUE v, int must) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L275 } /* call-seq: - * BigDecimal.double_fig + * BigDecimal.double_fig + * + * Returns the number of digits a Float object is allowed to have; + * the result is system-dependent: + * + * BigDecimal.double_fig # => 16 * - * The BigDecimal.double_fig class method returns the number of digits a - * Float number is allowed to have. The result depends upon the CPU and OS - * in use. */ static VALUE BigDecimal_double_fig(VALUE self) @@ -288,9 +290,9 @@ BigDecimal_double_fig(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L290 } /* call-seq: - * big_decimal.precs -> array + * precs -> array * - * Returns an Array of two Integer values that represent platform-dependent + * Returns an array of two integer values that represent platform-dependent * internal storage properties. * * This method is deprecated and will be removed in the future. @@ -298,7 +300,6 @@ BigDecimal_double_fig(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L300 * significant digits in scientific notation, and BigDecimal#precision for * obtaining the number of digits in decimal notation. * - * BigDecimal('5').precs #=> [9, 18] */ static VALUE @@ -319,20 +320,26 @@ BigDecimal_prec(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L320 } /* - * call-seq: - * big_decimal.precision -> intreger + * call-seq: + * precision -> integer * - * Returns the number of decimal digits in this number. + * Returns the number of decimal digits in +self+: * - * Example: + * %w[0 1 -1e20 1e-20 Infinity -Infinity NaN].each do |s| + * precision = BigDecimal(s).precision + * puts format("%9s has precision %2d", s, precision) + * end + * + * Output: + * + * 0 has precision 0 + * 1 has precision 1 + * -1e20 has precision 21 + * 1e-20 has precision 20 + * Infinity has precision 0 + * -Infinity has precision 0 + * NaN has precision 0 * - * BigDecimal("0").precision # => 0 - * BigDecimal("1").precision # => 1 - * BigDecimal("-1e20").precision # => 21 - * BigDecimal("1e-20").precision # => 20 - * BigDecimal("Infinity").precision # => 0 - * BigDecimal("-Infinity").precision # => 0 - * BigDecimal("NaN").precision # => 0 */ static VALUE BigDecimal_precision(VALUE self) @@ -412,12 +419,18 @@ BigDecimal_n_significant_digits(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L419 } /* - * call-seq: hash + * call-seq: + * hash -> integer + * + * Returns the integer hash value for +self+. + * + * Two instances of \BigDecimal have the same hash value if and only if + * they have equal: * - * Creates a hash for this BigDecimal. + * - Sign. + * - Fractional part. + * - Exponent. * - * Two BigDecimals with equal sign, - * fractional part and exponent have the same hash. */ static VALUE BigDecimal_hash(VALUE self) @@ -437,16 +450,16 @@ BigDecimal_hash(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L450 } /* - * call-seq: _dump + * call-seq: + * _dump * - * Method used to provide marshalling support. + * Returns a string representing the marshalling of +self+. + * See module Marshal. * - * inf = BigDecimal('Infinity') - * #=> Infinity - * BigDecimal._load(inf._dump) - * #=> Infinity + * inf = BigDecimal('Infinity') # => Infinity + * dumped = inf._dump # => "9:Infinity" + * BigDecimal._load(dumped) # => Infinity * - * See the Marshal module. */ static VALUE BigDecimal_dump(int argc, VALUE *argv, VALUE self) @@ -580,42 +593,165 @@ check_rounding_mode(VALUE const v) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L593 return sw; } -/* call-seq: - * BigDecimal.mode(mode, value) - * - * Controls handling of arithmetic exceptions and rounding. If no value - * is supplied, the current value is returned. - * - * Six values of the mode parameter control the handling of arithmetic - * exceptions: - * - * BigDecimal::EXCEPTION_NaN - * BigDecimal::EXCEPTION_INFINITY - * BigDecimal::EXCEPTION_UNDERFLOW - * BigDecimal::EXCEPTION_OVERFLOW - * BigDecimal::EXCEPTION_ZERODIVIDE - * BigDecimal::EXCEPTION_ALL - * - * For each mode parameter above, if the value set is false, computation - * continues after an arithmetic exception of the appropriate type. - * When computation continues, results are as follows: - * - * EXCEPTION_NaN:: NaN - * EXCEPTION_INFINITY:: +Infinity or -Infinity - * EXCEPTION_UNDERFLOW:: 0 - * EXCEPTION_OVERFLOW:: +Infinity or -Infinity - * EXCEPTION_ZERODIVIDE:: +Infinity or -Infinity - * - * One value of the mode parameter controls the rounding of numeric values: - * BigDecimal::ROUND_MODE. The values it can take are: - * - * ROUND_UP, :up:: round away from zero - * ROUND_DOWN, :down, :truncate:: round towards zero (truncate) - * ROUND_HALF_UP, :half_up, :default:: round towards the nearest neighbor, unless both neighbors are equidistant, in which case round away from zero. (default) - * ROUND_HALF_DOWN, :half_down:: round towards the nearest neighbor, unless both neighbors are equidistant, in which case round towards zero. - * ROUND_HALF_EVEN, :half_even, :banker:: round towards the nearest neighbor, unless both neighbors are equidistant, in which case round towards the even neighbor (Banker's rounding) - * ROUND_CEILING, :ceiling, :ceil:: round towards positive infinity (ceil) - * ROUND_FLOOR, :floor:: round towards negative infinity (floor) +/* call-seq: + * BigDecimal.mode(mode, setting = nil) -> integer + * + * Returns an integer representing the mode settings + * for exception handling and rounding. + * + * These modes control exception handling: + * + * - \BigDecimal::EXCEPTION_NaN. + * - \BigDecimal::EXCEPTION_INFINITY. + * - \BigDecimal::EXCEPTION_UNDERFLOW. + * - \BigDecimal::EXCEPTION_OVERFLOW. + * - \BigDecimal::EXCEPTION_ZERODIVIDE. + * - \BigDecimal::EXCEPTION_ALL. + * + * Values for +setting+ for exception handling: + * + * - +true+: sets the given +mode+ to +true+. + * - +false+: sets the given +mode+ to +false+. + * - +nil+: does not modify the mode settings. + * + * You can use method BigDecimal.save_exception_mode + * to temporarily change, and then automatically restore, exception modes. + * + * For clarity, some examples below begins by setting all + * exception modes to +false+. + * + * This mode controls the way rounding is to be performed: + * + * - \BigDecimal::ROUND_MODE + * + * You can use method BigDecimal.save_rounding_mode + * to temporarily change, and then automatically restore, the rounding mode. + * + * <b>NaNs</b> + * + * Mode \BigDecimal::EXCEPTION_NaN controls behavior + * when a \BigDecimal NaN is created. + * Settings" + * + * - +false+ (default): Returns <tt>BigDecimal('NaN')</tt>. + * - +true+: Raises FloatDomainError. + * + * Examples: + * + * BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0 + * BigDecimal('NaN') # => NaN + * BigDecimal.mode(BigDecimal::EXCEPTION_NaN, true) # => 2 + * BigDecimal('NaN') # Raises FloatDomainError + * + * <b>Infinities</b> + * + * Mode \BigDecimal::EXCEPTION_INFINITY controls behavior + * when a \BigDecimal Infinity or -Infinity is created. + * Settings: + * + * - +false+ (default): Returns <tt>BigDecimal('Infinity')</tt> + * or <tt>BigDecimal('-Infinity')</tt>. + * - +true+: Raises FloatDomainError. + * + * Examples: + * + * BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0 + * BigDecimal('Infinity') # => Infinity + * BigDecimal('-Infinity') # => -Infinity + * BigDecimal.mode(BigDecimal::EXCEPTION_INFINITY, true) # => 1 + * BigDecimal('Infinity') # Raises FloatDomainError + * BigDecimal('-Infinity') # Raises FloatDomainError + * + * <b>Underflow</b> + * + * Mode \BigDecimal::EXCEPTION_UNDERFLOW controls behavior + * when a \BigDecimal underflow occurs. + * Settings: + * + * - +false+ (default): Returns <tt>BigDecimal('0')</tt> + * or <tt>BigDecimal('-Infinity')</tt>. + * - +true+: Raises FloatDomainError. + * + * Examples: + * + * BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0 + * def flow_under + * x = BigDecimal('0.1') + * 100.times { x *= x } + * end + * flow_under # => 100 + * BigDecimal.mode(BigDecimal::EXCEPTION_UNDERFLOW, true) # => 4 + * flow_under # Raises FloatDomainError + * + * <b>Overflow</b> + * + * Mode \BigDecimal::EXCEPTION_OVERFLOW controls behavior + * when a \BigDecimal overflow occurs. + * Settings: + * + * - +false+ (default): Returns <tt>BigDecimal('Infinity')</tt> + * or <tt>BigDecimal('-Infinity')</tt>. + * - +true+: Raises FloatDomainError. + * + * Examples: + * + * BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0 + * def flow_over + * x = BigDecimal('10') + * 100.times { x *= x } + * end + * flow_over # => 100 + * BigDecimal.mode(BigDecimal::EXCEPTION_OVERFLOW, true) # => 1 + * flow_ove (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/