abstract struct Int

Overview

Int is the base type of all integer types.

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

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 isInt32, orInt64 if the number doesn't fit into anInt32:

1 # Int32

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

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

+10 # Int32
-20 # Int32

2147483648 # Int64

Literals without a suffix that are larger thanInt64::MAX represent a UInt64 if the number fits, e.g.9223372036854775808 and 0x80000000_00000000. This behavior is deprecated and will become an error in the future.

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 with0b:

0b1101 # == 13

Octal numbers start with0o:

0o123 # == 83

Hexadecimal numbers start with0x:

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

SeeInteger literals in the language reference.

Included Modules

Direct Known Subclasses

Defined in:

big/big_decimal.cr
big/big_float.cr
big/big_int.cr
big/big_rational.cr
big/number.cr
humanize.cr
int.cr
json/to_json.cr
time/span.cr:416
time/span.cr:586

Constructors

Instance Method Summary

Instance methods inherited from module Comparable(BigDecimal)

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

Instance methods inherited from module Comparable(BigRational)

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

Instance methods inherited from module Comparable(BigInt)

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

Instance methods inherited from struct Number

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

Constructor methods inherited from struct Number

additive_identity : self additive_identity, multiplicative_identity : self multiplicative_identity, zero : self zero

Class methods inherited from struct Number

si_prefix(magnitude : Int, prefixes = SI_PREFIXES) : Char | Nil si_prefix

Macros inherited from struct Number

[](*nums) [], slice(*nums, read_only = false) slice, static_array(*nums) static_array

Instance methods inherited from module Comparable(BigFloat)

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

Instance methods inherited from module Steppable

step(*, to limit = nil, by step, exclusive : Bool = false, &) : Nil
step(*, to limit = nil, by step, exclusive : Bool = false) step

Instance methods inherited from module Comparable(Number)

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

Instance methods inherited from struct Value

==(other : Log::Metadata::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?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
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) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

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

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.from_io(io : IO, format : IO::ByteFormat) : self #

Reads an integer from the givenio in the givenformat.

See also:IO#read_bytes.


Instance Method Detail

def %(other : BigInt) : BigInt #

def %(other : Int) #

Returnsself moduloother.

This uses floored division.

SeeInt#/ for more details.


def &*(other : BigInt) : BigInt #

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

Returns the value of raisingself to the power ofexponent.

RaisesArgumentError ifexponent 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 : BigInt) : BigInt #

def *(other : BigRational) : BigRational #

def *(other : BigDecimal) : BigDecimal #

def **(exponent : Int) : self #

Returns the value of raisingself to the power ofexponent.

RaisesArgumentError ifexponent is negative: if this is needed, either use a float base or a float exponent.

RaisesOverflowError in case of overflow.

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

def **(exponent : Float) : Float64 #

Returns the value of raisingself to the power ofexponent.

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

def +(other : BigInt) : BigInt #

def +(other : BigRational) : BigRational #

def +(other : BigDecimal) : BigDecimal #

def -(other : BigInt) : BigInt #

def -(other : BigFloat) : BigFloat #

def -(other : BigRational) : BigRational #

def -(other : BigDecimal) : BigDecimal #

def /(other : BigFloat) : BigFloat #

def /(other : BigRational) #

def //(other : Int::Primitive) #

Dividesself byother 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 ifother is zero, or ifother 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 bitscount positions to the left.

  • Ifcount is greater than the number of bits of this integer, returns 0
  • Ifcount is negative, a right shift is performed
8000 << 1  # => 16000
8000 << 2  # => 32000
8000 << 32 # => 0
8000 << -1 # => 4000

def <=>(other : BigInt) #

def <=>(other : Int) : Int32 #

def <=>(other : BigFloat) : Int32 #

def <=>(other : BigRational) : Int32 #

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

The comparison operator. Returns0 if the two objects are equal, a negative number if this object is considered less thanother, a positive number if this object is considered greater thanother, ornil 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 ===(char : Char) #

def >>(count : Int) #

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

  • Ifcount is greater than the number of bits of this integer, returns 0
  • Ifcount is negative, a left shift is performed
8000 >> 1  # => 4000
8000 >> 2  # => 2000
8000 >> 32 # => 0
8000 >> -1 # => 16000

-8000 >> 1 # => -4000

def ~ #

def abs : self #
Description copied from struct Number

Returns the absolute value of this number.

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

def bit(bit) #

Returns this number'sbitth 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 bit_length : Int32 #

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 returnsceil(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 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) : Bool #

Returnstrue if all bits inmask are set onself.

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

def ceil : self #

def chr : Char #

Returns aChar that has the unicode codepoint ofself.

RaisesArgumentError if this integer's value doesn't fit a char's range (0..0xd7ff and0xe000..0x10ffff).

97.chr # => 'a'

def day : Time::Span #

Returns aTime::Span ofself days.


def days : Time::Span #

Returns aTime::Span ofself days.


def digits(base = 10) : Array(Int32) #

Returns the digits of a number in a given base. The digits are returned as an array with the least significant digit as the first array element.

12345.digits      # => [5, 4, 3, 2, 1]
12345.digits(7)   # => [4, 6, 6, 0, 5]
12345.digits(100) # => [45, 23, 1]

-12345.digits(7) # => ArgumentError

def divisible_by?(num) : Bool #

def downto(to, &block : self -> ) : Nil #

Calls the given block with each integer value from self down to#to.

3.downto(1) do |i|
  puts i
end

Prints:

3
2
1

def downto(to) #

Get an iterator for counting down from self to#to.


def even? : Bool #

def fdiv(other) : Float64 #

def floor : self #

def gcd(other : self) : self #

Returns the greatest common divisor ofself andother. Signed integers may raiseOverflowError if either has value equal toMIN of its type.

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

def gcd(other : BigInt) : Int #

Returns the greatest common divisor ofself andother.


def hour : Time::Span #

Returns aTime::Span ofself hours.


def hours : Time::Span #

Returns aTime::Span ofself hours.


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

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

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,Ri,Qi) based on powers of 1000 (seeBinaryPrefixFormat::IEC).

format can be set to use the extended range of JEDEC units (K,M,G, T,P,E,Z,Y,R,Q) which equals to the prefixes of the SI system except for uppercaseK 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"

SeeNumber#humanize for more details on the behaviour and arguments.


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

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

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,Ri,Qi) based on powers of 1000 (seeBinaryPrefixFormat::IEC).

format can be set to use the extended range of JEDEC units (K,M,G, T,P,E,Z,Y,R,Q) which equals to the prefixes of the SI system except for uppercaseK 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"

SeeNumber#humanize for more details on the behaviour and arguments.


def integer? : Bool #

Returnstrue ifself is an integer.

Non-integer types may returntrue as long asself denotes a finite value without any fractional parts.

1.integer?       # => true
1.0.integer?     # => true
1.2.integer?     # => false
(1 / 0).integer? # => false
(0 / 0).integer? # => false

Always returnstrue forInt.


def lcm(other : BigInt) : BigInt #

Returns the least common multiple ofself andother.


def lcm(other : Int) #

Returns the least common multiple ofself andother.

RaisesOverflowError in case of overflow.


def microsecond : Time::Span #

Returns aTime::Span ofself microseconds.


def microseconds : Time::Span #

Returns aTime::Span ofself microseconds.


def millisecond : Time::Span #

Returns aTime::Span ofself milliseconds.


def milliseconds : Time::Span #

Returns aTime::Span ofself milliseconds.


def minute : Time::Span #

Returns aTime::Span ofself minutes.


def minutes : Time::Span #

Returns aTime::Span ofself minutes.


def modulo(other) #

def month : Time::MonthSpan #

Returns aTime::MonthSpan ofself months.


def months : Time::MonthSpan #

Returns aTime::MonthSpan ofself months.


def nanosecond : Time::Span #

Returns aTime::Span ofself nanoseconds.


def nanoseconds : Time::Span #

Returns aTime::Span ofself nanoseconds.


def odd? : Bool #

abstract def popcount #

Counts1-bits in the binary representation of this integer.

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

def pred : self #

def remainder(other : Int) #

Returnsself remainderother.

This uses truncated division.

SeeInt#tdiv for more details.


def round(mode : RoundingMode) : self #
Description copied from struct Number

Roundsself to an integer value using roundingmode.

The roundingmode controls the direction of the rounding. The default is RoundingMode::TIES_EVEN which rounds to the nearest integer, with ties (fractional value of0.5) being rounded to the even neighbor (Banker's rounding).


def round_away #

Returnsself.


def round_even : self #

Returnsself.


def second : Time::Span #

Returns aTime::Span ofself seconds.


def seconds : Time::Span #

Returns aTime::Span ofself seconds.


def succ : self #

def tdiv(other : Int) #

Dividesself byother 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 x
  • 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 ifother is0, or ifother is-1 and self is signed and is the minimum value for that integer type.


def tdivmod(other : Int) #

Returns aTuple of two elements containing the quotient and modulus obtained by dividingself bynumber using truncated division.

11.tdivmod(3)  # => {3, 2}
11.tdivmod(-3) # => {-4, -1}

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 x
  • 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 ifother is0, or ifother is-1 and self is signed and is the minimum value for that integer type.


def times(&block : self -> ) : Nil #

def times #

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

def to(to) #

def to_big_d : BigDecimal #

Convertsself toBigDecimal.

require "big"
123456789012345678.to_big_d

def to_big_i : BigInt #

Returns aBigInt representing this integer.

require "big"

123.to_big_i

def to_big_r : BigRational #

Returns aBigRational representing this integer.

require "big"

123.to_big_r

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

Writes this integer to the givenio in the givenformat.

See also:IO#write_bytes.


def to_json(json : JSON::Builder) : Nil #

def to_json_object_key : String #

def to_s(io : IO, base : Int = 10, *, precision : Int = 1, upcase : Bool = false) : Nil #

Appends a string representation of this integer to the givenio.

base specifies the radix of the written string, and must be either 62 or a number between 2 and 36. By default, digits above 9 are represented by ASCII lowercase letters (a for 10,b for 11, etc.), but uppercase letters may be used ifupcase istrue, unless base 62 is used. In that case, lowercase letters are used for 10 to 35, and uppercase ones for 36 to 61, andupcase must befalse.

precision specifies the minimum number of digits in the written string. If there are fewer digits than this number, the string is left-padded by zeros. Ifself andprecision are both zero, returns an empty string.


def to_s(base : Int = 10, *, precision : Int = 1, upcase : Bool = false) : String #

Returns a string representation of this integer.

base specifies the radix of the returned string, and must be either 62 or a number between 2 and 36. By default, digits above 9 are represented by ASCII lowercase letters (a for 10,b for 11, etc.), but uppercase letters may be used ifupcase istrue, unless base 62 is used. In that case, lowercase letters are used for 10 to 35, and uppercase ones for 36 to 61, andupcase must befalse.

precision specifies the minimum number of digits in the returned string. If there are fewer digits than this number, the string is left-padded by zeros. Ifself andprecision are both zero, returns an empty string.

1234.to_s                   # => "1234"
1234.to_s(2)                # => "10011010010"
1234.to_s(16)               # => "4d2"
1234.to_s(16, upcase: true) # => "4D2"
1234.to_s(36)               # => "ya"
1234.to_s(62)               # => "jU"
1234.to_s(precision: 2)     # => "1234"
1234.to_s(precision: 6)     # => "001234"

abstract def trailing_zeros_count #

Returns the number of trailing0-bits.


def trunc : self #

def upto(to, &block : self -> ) : Nil #

def upto(to) #

def week : Time::Span #

Returns aTime::Span ofself weeks.


def weeks : Time::Span #

Returns aTime::Span ofself weeks.


def year : Time::MonthSpan #

Returns aTime::MonthSpan ofself years.


def years : Time::MonthSpan #

Returns aTime::MonthSpan ofself years.