module Kernel

Returns the BigDecimal converted from value with a precision of ndigits decimal digits.

When ndigits is less than the number of significant digits in the value, the result is rounded to that number of digits, according to the current rounding mode; see BigDecimal.mode.

When ndigits is 0, the number of digits to correctly represent a float number is determined automatically.

Returns value converted to a BigDecimal, depending on the type of value:

• Integer, Float, Rational, Complex, or BigDecimal: converted directly:

  # Integer, Complex, or BigDecimal value does not require ndigits; ignored if given.
  BigDecimal(2)                     # => 0.2e1
  BigDecimal(Complex(2, 0))         # => 0.2e1
  BigDecimal(BigDecimal(2))         # => 0.2e1
  # Float or Rational value requires ndigits.
  BigDecimal(2.0, 0)                # => 0.2e1
  BigDecimal(Rational(2, 1), 0)     # => 0.2e1
  

• String: converted by parsing if it contains an integer or floating-point literal; leading and trailing whitespace is ignored:

  # String does not require ndigits; ignored if given.
  BigDecimal('2')     # => 0.2e1
  BigDecimal('2.0')   # => 0.2e1
  BigDecimal('0.2e1') # => 0.2e1
  BigDecimal(' 2.0 ') # => 0.2e1
  

• Other type that responds to method :to_str: first converted to a string, then converted to a BigDecimal, as above.

• Other type:

  • Raises an exception if keyword argument exception is true.

  • Returns nil if keyword argument exception is true.

Raises an exception if value evaluates to a Float and digits is larger than Float::DIG + 1.

static VALUE
f_BigDecimal(int argc, VALUE *argv, VALUE self)
{
    VALUE val, digs_v, opts = Qnil;
    argc = rb_scan_args(argc, argv, "11:", &val, &digs_v, &opts);
    int exception = opts_exception_p(opts);

    size_t digs = SIZE_MAX; /* this means digs is omitted */
    if (argc > 1) {
        digs_v = rb_to_int(digs_v);
        if (FIXNUM_P(digs_v)) {
            long n = FIX2LONG(digs_v);
            if (n < 0)
                goto negative_digs;
            digs = (size_t)n;
        }
        else {
            if (RBIGNUM_NEGATIVE_P(digs_v)) {
              negative_digs:
                if (!exception)
                    return Qnil;
                rb_raise(rb_eArgError, "negative precision");
            }
            digs = NUM2SIZET(digs_v);
        }
    }

    return rb_convert_to_BigDecimal(val, digs, exception);
}