# abstract struct Int

- Int
- Number
- Value
- Object

##
Overview

Int is the base type of all integer types.

There are four signed integer types: `Int8`, `Int16`, `Int32` and `Int64`, being able to represent numbers of 8, 16, 32 and 64 bits respectively. There are four unsigned integer types: `UInt8`, `UInt16`, `UInt32` and `UInt64`.

An integer literal is an optional `#+` or `#-` sign, followed by a sequence of digits and underscores, optionally followed by a suffix. If no suffix is present, the literal's type is the lowest between `Int32`, `Int64` and `UInt64` in which the number fits:

    1 # Int32

    1_i8  # Int8
    1_i16 # Int16
    1_i32 # Int32
    1_i64 # Int64

    1_u8  # UInt8
    1_u16 # UInt16
    1_u32 # UInt32
    1_u64 # UInt64

    +10 # Int32
    -20 # Int32

    2147483648          # Int64
    9223372036854775808 # UInt64

The underscore `_` before the suffix is optional.

Underscores can be used to make some numbers more readable:

    1_000_000 # better than 1000000

Binary numbers start with `0b`:

    0b1101 # == 13

Octal numbers start with `0o`:

    0o123 # == 83

Hexadecimal numbers start with `0x`:

    0xFE012D # == 16646445
    0xfe012d # == 16646445

##
Included Modules

- Comparable(BigDecimal)
- Comparable(BigRational)
- Comparable(BigInt)

##
Direct Known Subclasses

- BigInt
- Int128
- Int16
- Int32
- Int64
- Int8
- UInt128
- UInt16
- UInt32
- UInt64
- UInt8

##
Defined in:

##
Constructors

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

  Reads an integer from the given io in the given format.

##
Instance Method Summary

- #%(other : BigInt) : BigInt
- #%(other : Int)

  Returns `self` modulo other.

- #&*(other : BigInt) : BigInt
- #&**(exponent : Int) : self

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

- #&+(other : BigInt) : BigInt
- #&-(other : BigInt) : BigInt
- #*(other : BigDecimal)
- #*(other : BigRational)
- #*(other : BigInt) : BigInt
- #**(exponent : Float) : Float64

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

- #**(exponent : Int) : self

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

- #+(other : BigDecimal)
- #+(other : BigRational)
- #+(other : BigInt) : BigInt
- #-(other : BigInt) : BigInt
- #-(other : BigDecimal)
- #-(other : BigRational)
- #/(other : BigRational)
- #//(other : Int::Primitive)

  Divides `self` by other using floored division.

- #<<(count : Int)

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

- #<=>(other : BigDecimal)

  The comparison operator.

- #<=>(other : BigRational)
- #<=>(other : Int) : Int32
- #<=>(other : BigInt)
- #===(char : Char)
- #>>(count : Int)

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

- #abs

  Returns the absolute value of this number.

- #bit(bit)

  Returns this number's bitth bit, starting with the least-significant.

- #bits(range : Range)

  Returns the requested range of bits

- #bits_set?(mask)

  Returns `true` if all bits in mask are set on `self`.

- #ceil
- #chr

  Returns a `Char` that has the unicode codepoint of `self`.

- #day : Time::Span

  Returns a `Time::Span` of `self` days.

- #days : Time::Span

  Returns a `Time::Span` of `self` days.

- #divisible_by?(num)
- #downto(to, &block : self -> ) : Nil
- #downto(to)
- #even?
- #fdiv(other)
- #floor
- #gcd(other : self) : self

  Returns the greatest common divisor of `self` and `other`.

- #gcm(other : BigInt) : Int
- #hash(hasher)

  See `Object#hash(hasher)`

- #hour : Time::Span

  Returns a `Time::Span` of `self` hours.

- #hours : Time::Span

  Returns a `Time::Span` of `self` hours.

- #humanize_bytes(io : IO, precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : Nil

  Prints this integer as a binary value in a human-readable format using a `BinaryPrefixFormat`.

- #humanize_bytes(precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : String

  Prints this integer as a binary value in a human-readable format using a `BinaryPrefixFormat`.

- #lcm(other : Int)
- #lcm(other : BigInt) : BigInt
- #microsecond : Time::Span

  Returns a `Time::Span` of `self` microseconds.

- #microseconds : Time::Span

  Returns a `Time::Span` of `self` microseconds.

- #millisecond : Time::Span

  Returns a `Time::Span` of `self` milliseconds.

- #milliseconds : Time::Span

  Returns a `Time::Span` of `self` milliseconds.

- #minute : Time::Span

  Returns a `Time::Span` of `self` minutes.

- #minutes : Time::Span

  Returns a `Time::Span` of `self` minutes.

- #modulo(other)
- #month : Time::MonthSpan

  Returns a `Time::MonthSpan` of `self` months.

- #months : Time::MonthSpan

  Returns a `Time::MonthSpan` of `self` months.

- #nanosecond : Time::Span

  Returns a `Time::Span` of `self` nanoseconds.

- #nanoseconds : Time::Span

  Returns a `Time::Span` of `self` nanoseconds.

- #odd?
- #popcount

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

- #pred
- #remainder(other : Int)

  Returns `self` remainder other.

- #round

  Rounds this number to a given precision in decimal digits.

- #second : Time::Span

  Returns a `Time::Span` of `self` seconds.

- #seconds : Time::Span

  Returns a `Time::Span` of `self` seconds.

- #succ
- #tdiv(other : Int)

  Divides `self` by other using truncated division.

- #times
- #times(&block : self -> ) : Nil
- #to(to, &block : self -> ) : Nil
- #to(to)
- #to_big_d

  Converts `self` to `BigDecimal`.

- #to_big_i : BigInt

  Returns a `BigInt` representing this integer.

- #to_big_r

  Returns a `BigRational` representing this integer.

- #to_io(io : IO, format : IO::ByteFormat)

  Writes this integer to the given io in the given format.

- #to_json(json : JSON::Builder)
- #to_json_object_key
- #to_s : String

  Returns a string representation of this object.

- #to_s(io : IO) : Nil

  Appends a `String` representation of this object to the given `IO` object.

- #to_s(base : Int, io : IO, upcase : Bool = false) : Nil
- #to_s(base : Int, upcase : Bool = false) : String
- #trailing_zeros_count

  Returns the number of trailing `0`-bits.

- #trunc
- #upto(to)
- #upto(to, &block : self -> ) : Nil
- #week : Time::Span

  Returns a `Time::Span` of `self` weeks.

- #weeks : Time::Span

  Returns a `Time::Span` of `self` weeks.

- #year : Time::MonthSpan

  Returns a `Time::MonthSpan` of `self` years.

- #years : Time::MonthSpan

  Returns a `Time::MonthSpan` of `self` years.

- #~

### 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`

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, __crystal_pseudo_! : Bool __crystal_pseudo_!, __crystal_pseudo_as(type : Class) __crystal_pseudo_as, __crystal_pseudo_as?(type : Class) __crystal_pseudo_as?, __crystal_pseudo_is_a?(type : Class) : Bool __crystal_pseudo_is_a?, __crystal_pseudo_nil? : Bool __crystal_pseudo_nil?, __crystal_pseudo_responds_to?(name : Symbol) : Bool __crystal_pseudo_responds_to?, class class, dup dup, hash(hasher)
hash hash, inspect : String
inspect(io : IO) : Nil inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, 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.from_io(io : IO, format : IO::ByteFormat) : self #

Reads an integer from the given io in the given format.

See also: `IO#read_bytes`.

##
Instance Method Detail

def %(other : BigInt) : BigInt #
def %(other : Int) #

Returns `self` modulo other.

This uses floored division.

See `Int#/` for more details.

def &*(other : BigInt) : BigInt #
def &**(exponent : Int) : self #

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.

Intermediate multiplication will wrap around silently in case of overflow.

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

def &+(other : BigInt) : BigInt #
def &-(other : BigInt) : BigInt #
def *(other : BigDecimal) #
def *(other : BigRational) #
def *(other : BigInt) : BigInt #
def **(exponent : Float) : Float64 #

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

    2 ** 3.0  # => 8.0
    2 ** 0.0  # => 1.0
    2 ** -1.0 # => 0.5

def **(exponent : Int) : self #

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 : BigDecimal) #
def +(other : BigRational) #
def +(other : BigInt) : BigInt #
def -(other : BigInt) : BigInt #
def -(other : BigDecimal) #
def -(other : BigRational) #
def /(other : BigRational) #
def //(other : Int::Primitive) #

Divides `self` by other using floored division.

In floored division, given two integers x and y:

- q = x / y is rounded toward negative infinity
- r = x % y has the sign of the second argument
- x == q*y + r

For example:

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

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

def <<(count : 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 : BigDecimal) #
Description copied from module Comparable(BigDecimal)

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 : BigRational) #
def <=>(other : Int) : Int32 #
def <=>(other : BigInt) #
def ===(char : Char) #
def >>(count : 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 abs #
Description copied from struct Number

Returns the absolute value of this number.

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

def bit(bit) #

Returns this number's bitth bit, starting with the least-significant.

    11.bit(0) # => 1
    11.bit(1) # => 1
    11.bit(2) # => 0
    11.bit(3) # => 1
    11.bit(4) # => 0

def bits(range : Range) #

Returns the requested range of bits

    0b10011.bits(0..1) # => 0b11
    0b10011.bits(0..2) # => 0b11
    0b10011.bits(0..3) # => 0b11
    0b10011.bits(0..4) # => 0b10011
    0b10011.bits(0..5) # => 0b10011
    0b10011.bits(1..4) # => 0b1001

def bits_set?(mask) #

Returns `true` if all bits in mask are set on `self`.

    0b0110.bits_set?(0b0110) # => true
    0b1101.bits_set?(0b0111) # => false
    0b1101.bits_set?(0b1100) # => true

def ceil #
def chr #

Returns a `Char` that has the unicode codepoint of `self`.

Raises `ArgumentError` if this integer's value doesn't fit a char's range (`0..0x10ffff`).

    97.chr # => 'a'

def day : Time::Span #

Returns a `Time::Span` of `self` days.

def days : Time::Span #

Returns a `Time::Span` of `self` days.

def divisible_by?(num) #
def downto(to, &block : self -> ) : Nil #
def downto(to) #
def even? #
def fdiv(other) #
def floor #
def gcd(other : self) : self #

Returns the greatest common divisor of `self` and `other`. Signed integers may raise overflow if either has value equal to `MIN` of its type.

    5.gcd(10) # => 2
    5.gcd(7)  # => 1

def gcm(other : BigInt) : Int #
def hash(hasher) #

See `Object#hash(hasher)`

def hour : Time::Span #

Returns a `Time::Span` of `self` hours.

def hours : Time::Span #

Returns a `Time::Span` of `self` hours.

def humanize_bytes(io : IO, precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : Nil #

Prints this integer as a binary value in a human-readable format using a `BinaryPrefixFormat`.

Values with binary measurements such as computer storage (e.g. RAM size) are typically expressed using unit prefixes based on 1024 (instead of multiples of 1000 as per SI standard). This method by default uses the IEC standard prefixes (`Ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`, `Zi`, `Yi`) based on powers of 1000 (see `BinaryPrefixFormat::IEC`).

format can be set to use the extended range of JEDEC units (`K`, `M`, `G`, `T`, `P`, `E`, `Z`, `Y`) which equals to the prefixes of the SI system except for uppercase `K` and is based on powers of 1024 (see `BinaryPrefixFormat::JEDEC`).

    1.humanize_bytes                        # => "1B"
    1024.humanize_bytes                     # => "1.0kiB"
    1536.humanize_bytes                     # => "1.5kiB"
    524288.humanize_bytes                   # => "512kiB"
    1073741824.humanize_bytes(format: :IEC) # => "1.0GiB"

See `Number#humanize` for more details on the behaviour and arguments.

def humanize_bytes(precision : Int = 3, separator = '.', *, significant : Bool = true, format : BinaryPrefixFormat = :IEC) : String #

Prints this integer as a binary value in a human-readable format using a `BinaryPrefixFormat`.

Values with binary measurements such as computer storage (e.g. RAM size) are typically expressed using unit prefixes based on 1024 (instead of multiples of 1000 as per SI standard). This method by default uses the IEC standard prefixes (`Ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`, `Zi`, `Yi`) based on powers of 1000 (see `BinaryPrefixFormat::IEC`).

format can be set to use the extended range of JEDEC units (`K`, `M`, `G`, `T`, `P`, `E`, `Z`, `Y`) which equals to the prefixes of the SI system except for uppercase `K` and is based on powers of 1024 (see `BinaryPrefixFormat::JEDEC`).

    1.humanize_bytes                        # => "1B"
    1024.humanize_bytes                     # => "1.0kiB"
    1536.humanize_bytes                     # => "1.5kiB"
    524288.humanize_bytes                   # => "512kiB"
    1073741824.humanize_bytes(format: :IEC) # => "1.0GiB"

See `Number#humanize` for more details on the behaviour and arguments.

def lcm(other : Int) #
def lcm(other : BigInt) : BigInt #
def microsecond : Time::Span #

Returns a `Time::Span` of `self` microseconds.

def microseconds : Time::Span #

Returns a `Time::Span` of `self` microseconds.

def millisecond : Time::Span #

Returns a `Time::Span` of `self` milliseconds.

def milliseconds : Time::Span #

Returns a `Time::Span` of `self` milliseconds.

def minute : Time::Span #

Returns a `Time::Span` of `self` minutes.

def minutes : Time::Span #

Returns a `Time::Span` of `self` minutes.

def modulo(other) #
def month : Time::MonthSpan #

Returns a `Time::MonthSpan` of `self` months.

def months : Time::MonthSpan #

Returns a `Time::MonthSpan` of `self` months.

def nanosecond : Time::Span #

Returns a `Time::Span` of `self` nanoseconds.

def nanoseconds : Time::Span #

Returns a `Time::Span` of `self` nanoseconds.

def odd? #
abstract def popcount #

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

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

def pred #
def remainder(other : Int) #

Returns `self` remainder other.

This uses truncated division.

See `Int#tdiv` for more details.

def round #
Description copied from struct Number

Rounds this number to a given precision in decimal digits.

    -1763.116.round(2) # => -1763.12

def second : Time::Span #

Returns a `Time::Span` of `self` seconds.

def seconds : Time::Span #

Returns a `Time::Span` of `self` seconds.

def succ #
def tdiv(other : 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 times #
def times(&block : self -> ) : Nil #
def to(to, &block : self -> ) : Nil #
def to(to) #
def to_big_d #

Converts `self` to `BigDecimal`.

    require "big"
    12123415151254124124.to_big_d

def to_big_i : BigInt #

Returns a `BigInt` representing this integer.

    require "big"

    123.to_big_i

def to_big_r #

Returns a `BigRational` representing this integer.

    require "big"

    123.to_big_r

def to_io(io : IO, format : IO::ByteFormat) #

Writes this integer to the given io in the given format.

See also: `IO#write_bytes`.

def to_json(json : JSON::Builder) #
def to_json_object_key #
def to_s : String #
Description copied from class Object

Returns a string representation of this object.

Descendants must usually not override this method. Instead, they must override `#to_s(io)`, which must append to the given IO object.

def to_s(io : IO) : Nil #
Description copied from class Object

Appends a `String` representation of this object to the given `IO` object.

An object must never append itself to the io argument, as this will in turn call `#to_s(io)` on it.

def to_s(base : Int, io : IO, upcase : Bool = false) : Nil #
def to_s(base : Int, upcase : Bool = false) : String #
abstract def trailing_zeros_count #

Returns the number of trailing `0`-bits.

def trunc #
def upto(to) #
def upto(to, &block : self -> ) : Nil #
def week : Time::Span #

Returns a `Time::Span` of `self` weeks.

def weeks : Time::Span #

Returns a `Time::Span` of `self` weeks.

def year : Time::MonthSpan #

Returns a `Time::MonthSpan` of `self` years.

def years : Time::MonthSpan #

Returns a `Time::MonthSpan` of `self` years.

def ~ #