# Bignum

Class

`Bignum` objects hold integers outside the range of `Fixnum`. `Bignum` objects are created automatically when integer calculations would otherwise overflow a `Fixnum`. When a calculation involving `Bignum` objects returns a result that will fit in a `Fixnum`, the result is automatically converted.

For the purposes of the bitwise operations and `[]`, a `Bignum` is treated as if it were an infinite-length bitstring with 2’s complement representation.

While `Fixnum` values are immediate, `Bignum` objects are not—assignment and parameter passing work with references to objects, not the objects themselves.

When mathn is required Bignum’s division is enhanced to return more precise values from mathematical expressions.

```(2**72) / ((2**70) * 3)  # => 4/3
```
Constants

#### GMP_VERSION

Instance Methods

Returns big modulo other. See `Numeric.divmod` for more information.

Performs bitwise `and` between big and numeric.

Multiplies big and other, returning the result.

Raises big to the exponent power (which may be an integer, float, or anything that will coerce to a number). The result may be a `Fixnum`, `Bignum`, or `Float`

```123456789 ** 2      #=> 15241578750190521
123456789 ** 1.2    #=> 5126464716.09932
123456789 ** -2     #=> (1/15241578750190521)
```

Adds big and other, returning the result.

Subtracts other from big, returning the result.

Unary minus (returns an integer whose value is 0-big)

Performs division: the class of the resulting object depends on the class of `numeric` and on the magnitude of the result.

Returns `true` if the value of `big` is less than that of `real`.

Shifts big left numeric positions (right if numeric is negative).

Returns `true` if the value of `big` is less than or equal to that of `real`.

Comparison—Returns -1, 0, or +1 depending on whether `big` is less than, equal to, or greater than `numeric`. This is the basis for the tests in `Comparable`.

`nil` is returned if the two values are incomparable.

Returns `true` only if obj has the same value as big. Contrast this with `Bignum#eql?`, which requires obj to be a `Bignum`.

```68719476736 == 68719476736.0   #=> true
```
An alias for ==

Returns `true` if the value of `big` is greater than that of `real`.

Returns `true` if the value of `big` is greater than or equal to that of `real`.

Shifts big right numeric positions (left if numeric is negative).

Bit Reference—Returns the nth bit in the (assumed) binary representation of big, where big[0] is the least significant bit.

```a = 9**15
50.downto(0) do |n|
print a[n]
end
```

produces:

```000101110110100000111000011110010100111100010111001
```

Performs bitwise +exclusive or+ between big and numeric.

Returns the absolute value of big.

```-1234567890987654321.abs   #=> 1234567890987654321
```

Returns the number of bits of the value of int.

“the number of bits” means that the bit position of the highest bit which is different to the sign bit. (The bit position of the bit 2**n is n+1.) If there is no such bit (zero or minus one), zero is returned.

I.e. This method returns ceil(log2(int < 0 ? -int : int+1)).

```(-2**10000-1).bit_length  #=> 10001
(-2**10000).bit_length    #=> 10000
(-2**10000+1).bit_length  #=> 10000

(-2**1000-1).bit_length   #=> 1001
(-2**1000).bit_length     #=> 1000
(-2**1000+1).bit_length   #=> 1000

(2**1000-1).bit_length    #=> 1000
(2**1000).bit_length      #=> 1001
(2**1000+1).bit_length    #=> 1001

(2**10000-1).bit_length   #=> 10000
(2**10000).bit_length     #=> 10001
(2**10000+1).bit_length   #=> 10001
```

This method can be used to detect overflow in `Array#pack` as follows.

```if n.bit_length < 32
[n].pack("l") # no overflow
else
raise "overflow"
end
```

Returns an array with both a `numeric` and a `big` represented as `Bignum` objects.

This is achieved by converting `numeric` to a `Bignum`.

A `TypeError` is raised if the `numeric` is not a `Fixnum` or `Bignum` type.

```(0x3FFFFFFFFFFFFFFF+1).coerce(42)   #=> [42, 4611686018427387904]
```

Performs integer division: returns integer value.

See `Numeric#divmod`.

Returns `true` only if obj is a `Bignum` with the same value as big. Contrast this with `Bignum#==`, which performs type conversions.

```68719476736.eql?(68719476736.0)   #=> false
```

Returns `true` if big is an even number.

Returns the floating point result of dividing big by numeric.

```-1234567890987654321.fdiv(13731)      #=> -89910996357705.5
-1234567890987654321.fdiv(13731.24)   #=> -89909424858035.7
```

Compute a hash based on the value of big.

See also `Object#hash`.

An alias for to_s
An alias for abs
An alias for %

Returns `true` if big is an odd number.

Returns the remainder after dividing big by numeric.

```-1234567890987654321.remainder(13731)      #=> -6966
-1234567890987654321.remainder(13731.24)   #=> -9906.22531493148
```

Returns the number of bytes in the machine representation of big.

```(256**10 - 1).size   #=> 12
(256**20 - 1).size   #=> 20
(256**40 - 1).size   #=> 40
```

Converts big to a `Float`. If big doesn’t fit in a `Float`, the result is infinity.

Returns a string containing the representation of big radix base (2 through 36).

```12345654321.to_s         #=> "12345654321"
12345654321.to_s(2)      #=> "1011011111110110111011110000110001"
12345654321.to_s(8)      #=> "133766736061"
12345654321.to_s(16)     #=> "2dfdbbc31"
78546939656932.to_s(36)  #=> "rubyrules"
```

Performs bitwise `or` between big and numeric.

Inverts the bits in big. As Bignums are conceptually infinite length, the result acts as if it had an infinite number of one bits to the left. In hex representations, this is displayed as two periods to the left of the digits.

```sprintf("%X", ~0x1122334455)    #=> "..FEEDDCCBBAA"
```