123456789_123456789_123456789_123456789_123456789_

Class: Bignum

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Inherits: Integer
Defined in: bignum.c

Overview

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.

Constant Summary

Instance Attribute Summary

::Integer - Inherited

#even?

Returns true if int is an even number.

#integer?

Since int is already an ::Integer, this always returns true.

#odd?

Returns true if int is an odd number.

::Numeric - Inherited

#integer?

Returns true if num is an ::Integer (including ::Fixnum and Bignum).

#nonzero?

Returns self if num is not zero, nil otherwise.

#real

Returns self.

#real?

Returns true if num is a Real number.

#zero?

Returns true if num has a zero value.

Instance Method Summary

::Integer - Inherited

#ceil

Alias for Integer#to_i.

#chr

Returns a string containing the character represented by the int's value according to encoding.

#denominator

Returns 1.

#downto

Iterates the given block, passing decreasing values from int down to and including limit.

#floor

Alias for Integer#to_i.

#gcd

Returns the greatest common divisor (always positive).

#gcdlcm

Returns an array; [int.gcd(int2), int.lcm(int2)].

#lcm

Returns the least common multiple (always positive).

#next

Returns the ::Integer equal to int + 1, same as Fixnum#next.

#numerator

Returns self.

#ord

Returns the int itself.

#pred

Returns the ::Integer equal to int - 1.

#rationalize

Returns the value as a rational.

#round

Rounds int to a given precision in decimal digits (default 0 digits).

#succ

Alias for Integer#next.

#times

Iterates the given block int times, passing in values from zero to int - 1.

#to_i

As int is already an ::Integer, all these methods simply return the receiver.

#to_int

Alias for Integer#to_i.

#to_r

Returns the value as a rational.

#truncate

Alias for Integer#to_i.

#upto

Iterates the given block, passing in integer values from int up to and including limit.

::Numeric - Inherited

#%

x.modulo(y) means x-y*(x/y).floor.

#+@

Unary Plus—Returns the receiver's value.

#-@

Unary Minus—Returns the receiver's value, negated.

#<=>

Returns zero if number equals other, otherwise nil is returned if the two values are incomparable.

#abs

Returns the absolute value of num.

#abs2

Returns square of self.

#angle

Alias for Numeric#arg.

#arg

Returns 0 if the value is positive, pi otherwise.

#ceil

Returns the smallest possible ::Integer that is greater than or equal to num.

#coerce

If a +numeric is the same type as num, returns an array containing numeric and num.

#conj

Returns self.

#conjugate

Alias for Numeric#conj.

#denominator

Returns the denominator (always positive).

#div

Uses #/ to perform division, then converts the result to an integer.

#divmod

Returns an array containing the quotient and modulus obtained by dividing num by numeric.

#eql?

Returns true if num and numeric are the same type and have equal values.

#fdiv

Returns float division.

#floor

Returns the largest integer less than or equal to num.

#i

Returns the corresponding imaginary number.

#imag

Returns zero.

#imaginary

Alias for Numeric#imag.

#initialize_copy

Numerics are immutable values, which should not be copied.

#magnitude

Alias for Numeric#abs.

#modulo

Alias for Numeric#%.

#numerator

Returns the numerator.

#phase

Alias for Numeric#arg.

#polar

Returns an array; [num.abs, num.arg].

#quo

Returns most exact division (rational for integers, float for floats).

#rect

Returns an array; [num, 0].

#rectangular

Alias for Numeric#rect.

#remainder

x.remainder(y) means x-y*(x/y).truncate.

#round

Rounds num to a given precision in decimal digits (default 0 digits).

#singleton_method_added

Trap attempts to add methods to ::Numeric objects.

#step

Invokes the given block with the sequence of numbers starting at num, incremented by step (defaulted to 1) on each call.

#to_c

Returns the value as a complex.

#to_int

Invokes the child class's to_i method to convert num to an integer.

#truncate

Returns num truncated to an ::Integer.

::Comparable - Included

#<

Compares two objects based on the receiver's #<=> method, returning true if it returns -1.

#<=

Compares two objects based on the receiver's #<=> method, returning true if it returns -1 or 0.

#==

Compares two objects based on the receiver's #<=> method, returning true if it returns 0.

#>

Compares two objects based on the receiver's #<=> method, returning true if it returns 1.

#>=

Compares two objects based on the receiver's #<=> method, returning true if it returns 0 or 1.

#between?

Returns false if obj #<=> min is less than zero or if anObject #<=> max is greater than zero, true otherwise.

Instance Attribute Details

#even?Boolean (readonly)

Returns true if big is an even number.

#odd?Boolean (readonly)

Returns true if big is an odd number.

Instance Method Details

#%(other) ⇒ Numeric #modulo(other) ⇒ Numeric
Also known as: #modulo

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

#&(numeric) ⇒ Integer

Performs bitwise and between big and numeric.

#*(other) ⇒ Numeric

Multiplies big and other, returning the result.

#**(exponent) ⇒ Numeric

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)

#+(other) ⇒ Numeric

Adds big and other, returning the result.

#-(other) ⇒ Numeric

Subtracts other from big, returning the result.

#-Integer

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

#/(other) ⇒ Numeric

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

#<(real) ⇒ Boolean

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

#<<(numeric) ⇒ Integer

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

#<=(real) ⇒ Boolean

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

#<=>(numeric) ⇒ 1, ...

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.

#==(obj) ⇒ Boolean Also known as: #===

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

68719476736 == 68719476736.0   #=> true

#==(obj) ⇒ Boolean #===(obj) ⇒ Boolean

Alias for #==.

#>(real) ⇒ Boolean

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

#>=(real) ⇒ Boolean

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

#>>(numeric) ⇒ Integer

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

#[](n) ⇒ 0, 1

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

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

produces:

000101110110100000111000011110010100111100010111001

#^(numeric) ⇒ Integer

Performs bitwise exclusive or between big and numeric.

#absBignum #magnitudeBignum
Also known as: #magnitude

Returns the absolute value of big.

-1234567890987654321.abs   #=> 1234567890987654321

#bit_lengthInteger

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

#coerce(numeric) ⇒ Array

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]

#div(other) ⇒ Integer

Performs integer division: returns integer value.

#divmod(numeric) ⇒ Array

#eql?(obj) ⇒ Boolean

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

68719476736.eql?(68719476736.0)   #=> false

#fdiv(numeric) ⇒ Float

Returns the floating point result of dividing big by numeric.

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

#hashFixnum

Compute a hash based on the value of big.

See also Object#hash.

#to_s(base = 10) ⇒ String #inspect(base = 10) ⇒ String

Alias for #to_s.

#absBignum #magnitudeBignum

Alias for #abs.

#%(other) ⇒ Numeric #modulo(other) ⇒ Numeric

Alias for #%.

#remainder(numeric) ⇒ Numeric

Returns the remainder after dividing big by numeric.

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

#sizeInteger

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

#to_fFloat

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

#to_s(base = 10) ⇒ String Also known as: #inspect

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"

#|(numeric) ⇒ Integer

Performs bitwise or between big and numeric.

#~Integer

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"