BigInt - Crystal 0.35.1

# struct BigInt

- BigInt
- Int
- Number
- Value
- Object

##
Overview

A `BigInt` can represent arbitrarily large integers.

It is implemented under the hood with GMP.

##
Included Modules

- Comparable(Float)
- Comparable(BigInt)
- Comparable(UInt128 | UInt16 | UInt32 | UInt64 | UInt8)
- Comparable(Int128 | Int16 | Int32 | Int64 | Int8)

##
Defined in:

##
Constructors

- .new(str : String, base = 10)

  Creates a `BigInt` with the value denoted by str in the given base.

- .new(num : Int::Signed)

  Creates a `BigInt` from the given num.

- .new(num : Int::Unsigned)

  Creates a `BigInt` from the given num.

- .new(num : Float::Primitive)

  Creates a `BigInt` from the given num.

- .new(num : BigFloat)

  Creates a `BigInt` from the given num.

- .new(num : BigDecimal)

  Creates a `BigInt` from the given num.

- .new(num : BigRational)

  Creates a `BigInt` from the given num.

- .new(num : BigInt)

  Returns num.

- .new

  Creates a `BigInt` with the value zero.

##
Instance Method Summary

- #%(other : Int) : BigInt

  Returns `self` modulo other.

- #&(other : Int) : BigInt
- #&*(other) : BigInt
- #&+(other) : BigInt
- #&-(other) : BigInt
- #*(other : Int) : BigInt
- #*(other : LibGMP::IntPrimitiveUnsigned) : BigInt
- #*(other : LibGMP::IntPrimitiveSigned) : BigInt
- #*(other : BigInt) : BigInt
- #**(other : Int) : BigInt

  Returns the value of raising `self` to the power of exponent.

- #+(other : Int) : BigInt
- #+(other : BigInt) : BigInt
- #- : BigInt
- #-(other : Int) : BigInt
- #-(other : BigInt) : BigInt
- #/(other : UInt128) : BigFloat
- #/(other : Int128) : BigFloat
- #/(other : Float32) : BigFloat
- #/(other : UInt64) : BigFloat
- #/(other : Int64) : BigFloat
- #/(other : UInt32) : BigFloat
- #/(other : Int32) : BigFloat
- #/(other : UInt16) : BigFloat
- #/(other : Int16) : BigFloat
- #/(other : Int8) : BigFloat
- #/(other : BigRational) : BigRational
- #/(other : BigDecimal) : BigDecimal
- #/(other : BigInt) : BigFloat
- #/(other : UInt8) : BigFloat
- #/(other : Float64) : BigFloat
- #//(other : Int::Unsigned) : BigInt
- #//(other : Int) : BigInt
- #<<(other : Int) : BigInt

  Returns the result of shifting this number's bits count positions to the left.

- #<=>(other : BigInt)
- #<=>(other : Float)

  The comparison operator.

- #<=>(other : Int::Unsigned)
- #<=>(other : Int::Signed)
- #>>(other : Int) : BigInt

  Returns the result of shifting this number's bits count positions to the right.

- #^(other : Int) : BigInt
- #abs : BigInt

  Returns the absolute value of this number.

- #bit_length : Int32

  Returns the number of bits of this int value.

- #clone
- #divmod(number : Int::Unsigned)
- #divmod(number : Int::Signed)
- #divmod(number : LibGMP::ULong)
- #divmod(number : BigInt)
- #factorial : BigInt
- #gcd(other : Int) : Int
- #gcd(other : BigInt) : BigInt
- #hash(hasher)

  TODO improve this

- #lcm(other : Int) : BigInt
- #lcm(other : BigInt) : BigInt
- #popcount

  Counts `1`-bits in the binary representation of this integer.

- #remainder(other : Int) : BigInt

  Returns `self` remainder other.

- #tdiv(other : Int) : BigInt

  Divides `self` by other using truncated division.

- #to_big_d

  Converts `self` to `BigDecimal`.

- #to_big_f
- #to_big_i

  Returns a `BigInt` representing this integer.

- #to_big_r

  Returns a `BigRational` representing this integer.

- #to_f
- #to_f!
- #to_f32
- #to_f32!
- #to_f64
- #to_f64!
- #to_i
- #to_i!
- #to_i16
- #to_i16!
- #to_i32
- #to_i32!
- #to_i64
- #to_i64!
- #to_i8
- #to_i8!
- #to_s : String

  Returns a string representation of self.

- #to_s(base : Int) : String

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

- #to_s(io : IO) : Nil

  Returns a string representation of self.

- #to_u
- #to_u!
- #to_u16
- #to_u16!
- #to_u32
- #to_u32!
- #to_u64
- #to_u64!
- #to_u8
- #to_u8!
- #to_unsafe
- #trailing_zeros_count

  Returns the number of trailing `0`-bits.

- #unsafe_floored_div(other : BigInt) : BigInt
- #unsafe_floored_div(other : Int) : BigInt
- #unsafe_floored_divmod(number : LibGMP::ULong)
- #unsafe_floored_divmod(number : BigInt)
- #unsafe_floored_mod(other : Int) : BigInt
- #unsafe_floored_mod(other : BigInt) : BigInt
- #unsafe_truncated_div(other : Int) : BigInt
- #unsafe_truncated_div(other : BigInt) : BigInt
- #unsafe_truncated_divmod(number : BigInt)
- #unsafe_truncated_divmod(number : LibGMP::ULong)
- #unsafe_truncated_mod(other : Int) : BigInt
- #unsafe_truncated_mod(other : BigInt) : BigInt
- #unsafe_truncated_mod(other : LibGMP::IntPrimitive) : BigInt
- #|(other : Int) : BigInt
- #~ : BigInt

### Instance methods inherited from module `Comparable(Float)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(BigInt)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(UInt128 | UInt16 | UInt32 | UInt64 | UInt8)`

<(other : T | T | T | T | T) <, <=(other : T | T | T | T | T) <=, <=>(other : T | T | T | T | T) <=>, ==(other : T | T | T | T | T) ==, >(other : T | T | T | T | T) >, >=(other : T | T | T | T | T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(Int128 | Int16 | Int32 | Int64 | Int8)`

<(other : T | T | T | T | T) <, <=(other : T | T | T | T | T) <=, <=>(other : T | T | T | T | T) <=>, ==(other : T | T | T | T | T) ==, >(other : T | T | T | T | T) >, >=(other : T | T | T | T | T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Int`

%(other : BigInt) : BigInt
%(other : Int) %, &*(other : BigInt) : BigInt &*, &**(exponent : Int) : self &**, &+(other : BigInt) : BigInt &+, &-(other : BigInt) : BigInt &-, *(other : BigDecimal)
*(other : BigRational)
*(other : BigInt) : BigInt *, **(exponent : Float) : Float64
**(exponent : Int) : self **, +(other : BigDecimal)
+(other : BigRational)
+(other : BigInt) : BigInt +, -(other : BigInt) : BigInt
-(other : BigDecimal)
-(other : BigRational) -, /(other : BigRational) /, //(other : Int::Primitive) //, <<(count : Int) <<, <=>(other : BigDecimal)
<=>(other : BigRational)
<=>(other : Int) : Int32
<=>(other : BigInt) <=>, ===(char : Char) ===, >>(count : Int) >>, abs abs, bit(bit) bit, bit_length : Int32 bit_length, bits(range : Range) bits, bits_set?(mask) bits_set?, ceil ceil, chr chr, day : Time::Span day, days : Time::Span days, digits(base = 10) : Array(Int32) digits, divisible_by?(num) divisible_by?, downto(to, &block : self -> ) : Nil
downto(to) downto, even? even?, fdiv(other) fdiv, floor floor, gcd(other : self) : self gcd, gcm(other : BigInt) : Int gcm, hash(hasher) hash, hour : Time::Span hour, hours : Time::Span hours, humanize_bytes(io : IO, precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : Nil
humanize_bytes(precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : String humanize_bytes, lcm(other : Int)
lcm(other : BigInt) : BigInt lcm, microsecond : Time::Span microsecond, microseconds : Time::Span microseconds, millisecond : Time::Span millisecond, milliseconds : Time::Span milliseconds, minute : Time::Span minute, minutes : Time::Span minutes, modulo(other) modulo, month : Time::MonthSpan month, months : Time::MonthSpan months, nanosecond : Time::Span nanosecond, nanoseconds : Time::Span nanoseconds, odd? odd?, popcount popcount, pred pred, remainder(other : Int) remainder, round round, second : Time::Span second, seconds : Time::Span seconds, succ succ, tdiv(other : Int) tdiv, times(&block : self -> ) : Nil
times times, to(to)
to(to, &block : self -> ) : Nil to, to_big_d to_big_d, to_big_i : BigInt to_big_i, to_big_r to_big_r, to_io(io : IO, format : IO::ByteFormat) to_io, to_json(json : JSON::Builder) to_json, to_json_object_key to_json_object_key, to_s(base : Int = 10, *, upcase : Bool = false) : String
to_s(io : IO, base : Int = 10, *, upcase : Bool = false) : Nil
to_s(base : Int, _upcase : Bool) : String
to_s(base : Int, io : IO, upcase : Bool = false) : Nil to_s, trailing_zeros_count trailing_zeros_count, trunc trunc, upto(to)
upto(to, &block : self -> ) : Nil upto, week : Time::Span week, weeks : Time::Span weeks, year : Time::MonthSpan year, years : Time::MonthSpan years, ~ ~

### Constructor methods inherited from struct `Int`

from_io(io : IO, format : IO::ByteFormat) : self from_io

### Instance methods inherited from module `Comparable(BigDecimal)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(BigRational)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(BigInt)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Number`

*(other : Complex)
*(other : BigFloat) *, +(other : BigFloat)
+(other : Complex)
+ +, -(other : Complex)
-(other : BigFloat) -, /(other : Complex)
/(other : BigFloat) /, //(other) //, <=>(other : BigFloat)
<=>(other) : Int32? <=>, ==(other : Complex) ==, abs abs, abs2 abs2, cis cis, divmod(number) divmod, format(separator = '.', delimiter = ',', decimal_places : Int? = nil, *, group : Int = 3, only_significant : Bool = false) : String
format(io : IO, separator = '.', delimiter = ',', decimal_places : Int? = nil, *, group : Int = 3, only_significant : Bool = false) : Nil format, humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Indexable = SI_PREFIXES) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &) : String
humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &prefixes : Int32, Float64 -> Tuple(Int32, _) | Tuple(Int32, _, Bool)) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes = SI_PREFIXES) : String
humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil humanize, i i, round(digits = 0, base = 10) round, sign sign, significant(digits, base = 10) significant, step(*, to = nil, by = 1)
step(*, to = nil, by = 1, &) step, to_big_f to_big_f, to_c to_c, to_yaml(yaml : YAML::Nodes::Builder) to_yaml, zero? : Bool zero?

### Constructor methods inherited from struct `Number`

zero : self zero

### Class methods inherited from struct `Number`

si_prefix(magnitude : Int, prefixes = SI_PREFIXES) : Char? si_prefix

### Instance methods inherited from module `Comparable(BigFloat)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(Number)`

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Value`

==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(*values : Object) : Bool
in?(collection) : Bool in?, inspect : String
inspect(io : IO) : Nil inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

def self.new(str : String, base = 10) #

Creates a `BigInt` with the value denoted by str in the given base.

Raises `ArgumentError` if the string doesn't denote a valid integer.

    require "big"

    BigInt.new("123456789123456789123456789123456789") # => 123456789123456789123456789123456789
    BigInt.new("123_456_789_123_456_789_123_456_789")  # => 123456789123456789123456789
    BigInt.new("1234567890ABCDEF", base: 16)           # => 1311768467294899695

def self.new(num : Int::Signed) #

Creates a `BigInt` from the given num.

def self.new(num : Int::Unsigned) #

Creates a `BigInt` from the given num.

def self.new(num : Float::Primitive) #

Creates a `BigInt` from the given num.

def self.new(num : BigFloat) #

Creates a `BigInt` from the given num.

def self.new(num : BigDecimal) #

Creates a `BigInt` from the given num.

def self.new(num : BigRational) #

Creates a `BigInt` from the given num.

def self.new(num : BigInt) #

Returns num. Useful for generic code that does `T.new(...)` with `T` being a `Number`.

def self.new #

Creates a `BigInt` with the value zero.

    require "big"

    BigInt.new # => 0

##
Instance Method Detail

def %(other : Int) : BigInt #
Description copied from struct Int

Returns `self` modulo other.

This uses floored division.

See `Int#/` for more details.

def &(other : Int) : BigInt #
def &*(other) : BigInt #
def &+(other) : BigInt #
def &-(other) : BigInt #
def *(other : Int) : BigInt #
def *(other : LibGMP::IntPrimitiveUnsigned) : BigInt #
def *(other : LibGMP::IntPrimitiveSigned) : BigInt #
def *(other : BigInt) : BigInt #
def **(other : Int) : BigInt #
Description copied from struct Int

Returns the value of raising `self` to the power of exponent.

Raises `ArgumentError` if exponent is negative: if this is needed, either use a float base or a float exponent.

Raises `OverflowError` in case of overflow.

    2 ** 3  # => 8
    2 ** 0  # => 1
    2 ** -1 # ArgumentError

def +(other : Int) : BigInt #
def +(other : BigInt) : BigInt #
def - : BigInt #
def -(other : Int) : BigInt #
def -(other : BigInt) : BigInt #
def /(other : UInt128) : BigFloat #
def /(other : Int128) : BigFloat #
def /(other : Float32) : BigFloat #
def /(other : UInt64) : BigFloat #
def /(other : Int64) : BigFloat #
def /(other : UInt32) : BigFloat #
def /(other : Int32) : BigFloat #
def /(other : UInt16) : BigFloat #
def /(other : Int16) : BigFloat #
def /(other : Int8) : BigFloat #
def /(other : BigRational) : BigRational #
def /(other : BigDecimal) : BigDecimal #
def /(other : BigInt) : BigFloat #
def /(other : UInt8) : BigFloat #
def /(other : Float64) : BigFloat #
def //(other : Int::Unsigned) : BigInt #
def //(other : Int) : BigInt #
def <<(other : Int) : BigInt #
Description copied from struct Int

Returns the result of shifting this number's bits count positions to the left.

- If count is greater than the number of bits of this integer, returns 0
- If count is negative, a right shift is performed

    8000 << 1  # => 16000
    8000 << 2  # => 32000
    8000 << 32 # => 0
    8000 << -1 # => 4000

def <=>(other : BigInt) #
def <=>(other : Float) #
Description copied from module Comparable(Float)

The comparison operator. Returns `0` if the two objects are equal, a negative number if this object is considered less than other, a positive number if this object is considered greter than other, or `nil` if the two objects are not comparable.

Subclasses define this method to provide class-specific ordering.

The comparison operator is usually used to sort values:

    # Sort in a descending way:
    [3, 1, 2].sort { |x, y| y <=> x } # => [3, 2, 1]

    # Sort in an ascending way:
    [3, 1, 2].sort { |x, y| x <=> y } # => [1, 2, 3]

def <=>(other : Int::Unsigned) #
def <=>(other : Int::Signed) #
def >>(other : Int) : BigInt #
Description copied from struct Int

Returns the result of shifting this number's bits count positions to the right. Also known as arithmetic right shift.

- If count is greater than the number of bits of this integer, returns 0
- If count is negative, a left shift is performed

    8000 >> 1  # => 4000
    8000 >> 2  # => 2000
    8000 >> 32 # => 0
    8000 >> -1 # => 16000

    -8000 >> 1 # => -4000

def ^(other : Int) : BigInt #
def abs : BigInt #
Description copied from struct Number

Returns the absolute value of this number.

    123.abs  # => 123
    -123.abs # => 123

def bit_length : Int32 #
Description copied from struct Int

Returns the number of bits of this int value.

“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(self < 0 ? -self : self + 1))`.

    0.bit_length # => 0
    1.bit_length # => 1
    2.bit_length # => 2
    3.bit_length # => 2
    4.bit_length # => 3
    5.bit_length # => 3

    # The above is the same as
    0b0.bit_length   # => 0
    0b1.bit_length   # => 1
    0b10.bit_length  # => 2
    0b11.bit_length  # => 2
    0b100.bit_length # => 3
    0b101.bit_length # => 3

def clone #
def divmod(number : Int::Unsigned) #
def divmod(number : Int::Signed) #
def divmod(number : LibGMP::ULong) #
def divmod(number : BigInt) #
def factorial : BigInt #
def gcd(other : Int) : Int #
def gcd(other : BigInt) : BigInt #
def hash(hasher) #

TODO improve this

def lcm(other : Int) : BigInt #
def lcm(other : BigInt) : BigInt #
def popcount #
Description copied from struct Int

Counts `1`-bits in the binary representation of this integer.

    5.popcount   # => 2
    -15.popcount # => 29

def remainder(other : Int) : BigInt #
Description copied from struct Int

Returns `self` remainder other.

This uses truncated division.

See `Int#tdiv` for more details.

def tdiv(other : Int) : BigInt #
Description copied from struct Int

Divides `self` by other using truncated division.

In truncated division, given two integers x and y:

- `q = x.tdiv(y)` is rounded toward zero
- `r = x.remainder(y)` has the sign of the first argument
- `x == q*y + r`

For example:

     x     y     x / y     x % y
     5     3       1         2
    -5     3      -1        -2
     5    -3      -1         2
    -5    -3       1        -2

Raises if other is `0`, or if other is `-1` and `self` is signed and is the minimum value for that integer type.

def to_big_d #
Description copied from struct Int

Converts `self` to `BigDecimal`.

    require "big"
    12123415151254124124.to_big_d

def to_big_f #
def to_big_i #
Description copied from struct Int

Returns a `BigInt` representing this integer.

    require "big"

    123.to_big_i

def to_big_r #
Description copied from struct Int

Returns a `BigRational` representing this integer.

    require "big"

    123.to_big_r

def to_f #
def to_f! #
def to_f32 #
def to_f32! #
def to_f64 #
def to_f64! #
def to_i #
def to_i! #
def to_i16 #
def to_i16! #
def to_i32 #
def to_i32! #
def to_i64 #
def to_i64! #
def to_i8 #
def to_i8! #
def to_s : String #

Returns a string representation of self.

    require "big"

    BigInt.new("123456789101101987654321").to_s # => 123456789101101987654321

def to_s(base : Int) : String #

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

    require "big"

    BigInt.new("123456789101101987654321").to_s(8)  # => "32111154373025463465765261"
    BigInt.new("123456789101101987654321").to_s(16) # => "1a249b1f61599cd7eab1"
    BigInt.new("123456789101101987654321").to_s(36) # => "k3qmt029k48nmpd"

def to_s(io : IO) : Nil #

Returns a string representation of self.

    require "big"

    BigInt.new("123456789101101987654321").to_s # => 123456789101101987654321

def to_u #
def to_u! #
def to_u16 #
def to_u16! #
def to_u32 #
def to_u32! #
def to_u64 #
def to_u64! #
def to_u8 #
def to_u8! #
def to_unsafe #
def trailing_zeros_count #
Description copied from struct Int

Returns the number of trailing `0`-bits.

def unsafe_floored_div(other : BigInt) : BigInt #
def unsafe_floored_div(other : Int) : BigInt #
def unsafe_floored_divmod(number : LibGMP::ULong) #
def unsafe_floored_divmod(number : BigInt) #
def unsafe_floored_mod(other : Int) : BigInt #
def unsafe_floored_mod(other : BigInt) : BigInt #
def unsafe_truncated_div(other : Int) : BigInt #
def unsafe_truncated_div(other : BigInt) : BigInt #
def unsafe_truncated_divmod(number : BigInt) #
def unsafe_truncated_divmod(number : LibGMP::ULong) #
def unsafe_truncated_mod(other : Int) : BigInt #
def unsafe_truncated_mod(other : BigInt) : BigInt #
def unsafe_truncated_mod(other : LibGMP::IntPrimitive) : BigInt #
def |(other : Int) : BigInt #
def ~ : BigInt #