module Kernel - bigdecimal: Ruby Standard Library Documentation

# module Kernel

### Public Instance Methods

BigDecimal(value, exception: true) → bigdecimal click to toggle source
BigDecimal(value, ndigits, exception: true) → bigdecimal

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 `false`.

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);
    }