abstract struct Int

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 Int32, or Int64 if the number doesn't fit into an Int32:

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

Literals without a suffix that are larger than Int64::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 with 0b:

0b1101 # == 13

Octal numbers start with 0o:

0o123 # == 83

Hexadecimal numbers start with 0x:

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

See Integer 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:419
time/span.cr:589

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 : 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, root : String)
from_json(string_or_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 given io in the given format.

See also: IO#read_bytes.


[View source]

Instance Method Detail

def %(other : BigInt) : BigInt #

[View source]
def %(other : Int) #

Returns self modulo other.

This uses floored division.

See Int#/ for more details.


[View source]
def &*(other : BigInt) : BigInt #

[View source]
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

[View source]
def &+(other : BigInt) : BigInt #

[View source]
def &-(other : BigInt) : BigInt #

[View source]
def *(other : BigInt) : BigInt #

[View source]
def *(other : BigRational) : BigRational #

[View source]
def *(other : BigDecimal) : BigDecimal #

[View source]
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

[View source]
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

[View source]
def +(other : BigInt) : BigInt #

[View source]
def +(other : BigRational) : BigRational #

[View source]
def +(other : BigDecimal) : BigDecimal #

[View source]
def -(other : BigInt) : BigInt #

[View source]
def -(other : BigFloat) : BigFloat #

[View source]
def -(other : BigRational) : BigRational #

[View source]
def -(other : BigDecimal) : BigDecimal #

[View source]
def /(other : BigFloat) : BigFloat #

[View source]
def /(other : BigRational) #

[View source]
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.


[View source]
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

[View source]
def <=>(other : BigInt) #

[View source]
def <=>(other : Int) : Int32 #

[View source]
def <=>(other : BigFloat) #

[View source]
def <=>(other : BigRational) #

[View source]
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 greater 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]

[View source]
def ===(char : Char) #

[View source]
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

[View source]
def ~ #

[View source]
def abs : self #
Description copied from struct Number

Returns the absolute value of this number.

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

[View source]
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

[View source]
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 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

[View source]
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

[View source]
def bits_set?(mask) : Bool #

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

[View source]
def ceil : self #

[View source]
def chr : Char #

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..0xd7ff and 0xe000..0x10ffff).

97.chr # => 'a'

[View source]
def day : Time::Span #

Returns a Time::Span of self days.


[View source]
def days : Time::Span #

Returns a Time::Span of self days.


[View source]
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

[View source]
def divisible_by?(num) : Bool #

[View source]
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

[View source]
def downto(to) #

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


[View source]
def even? : Bool #

[View source]
def fdiv(other) : Float64 #

[View source]
def floor : self #

[View source]
def gcd(other : self) : self #

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

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

[View source]
def gcd(other : BigInt) : Int #

Returns the greatest common divisor of self and other.


[View source]
def hour : Time::Span #

Returns a Time::Span of self hours.


[View source]
def hours : Time::Span #

Returns a Time::Span of self hours.


[View source]
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 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, Ri, Qi) 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, R, Q) 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.


[View source]
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 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, Ri, Qi) 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, R, Q) 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.


[View source]
def integer? : Bool #

Returns true if self is an integer.

Non-integer types may return true as long as self 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 returns true for Int.


[View source]
def lcm(other : BigInt) : BigInt #

Returns the least common multiple of self and other.


[View source]
def lcm(other : Int) #

Returns the least common multiple of self and other.

Raises OverflowError in case of overflow.


[View source]
def microsecond : Time::Span #

Returns a Time::Span of self microseconds.


[View source]
def microseconds : Time::Span #

Returns a Time::Span of self microseconds.


[View source]
def millisecond : Time::Span #

Returns a Time::Span of self milliseconds.


[View source]
def milliseconds : Time::Span #

Returns a Time::Span of self milliseconds.


[View source]
def minute : Time::Span #

Returns a Time::Span of self minutes.


[View source]
def minutes : Time::Span #

Returns a Time::Span of self minutes.


[View source]
def modulo(other) #

[View source]
def month : Time::MonthSpan #

Returns a Time::MonthSpan of self months.


[View source]
def months : Time::MonthSpan #

Returns a Time::MonthSpan of self months.


[View source]
def nanosecond : Time::Span #

Returns a Time::Span of self nanoseconds.


[View source]
def nanoseconds : Time::Span #

Returns a Time::Span of self nanoseconds.


[View source]
def odd? : Bool #

[View source]
abstract def popcount #

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

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

[View source]
def pred : self #

[View source]
def remainder(other : Int) #

Returns self remainder other.

This uses truncated division.

See Int#tdiv for more details.


[View source]
def round(mode : RoundingMode) : self #
Description copied from struct Number

Rounds self to an integer value using rounding mode.

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


[View source]
def round_away #

Returns self.


[View source]
def round_even : self #

Returns self.


[View source]
def second : Time::Span #

Returns a Time::Span of self seconds.


[View source]
def seconds : Time::Span #

Returns a Time::Span of self seconds.


[View source]
def succ : self #

[View source]
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.


[View source]
def times(&block : self -> ) : Nil #

[View source]
def times #

[View source]
def to(to, &block : self -> ) : Nil #

[View source]
def to(to) #

[View source]
def to_big_d : BigDecimal #

Converts self to BigDecimal.

require "big"
123456789012345678.to_big_d

[View source]
def to_big_i : BigInt #

Returns a BigInt representing this integer.

require "big"

123.to_big_i

[View source]
def to_big_r : BigRational #

Returns a BigRational representing this integer.

require "big"

123.to_big_r

[View source]
def to_io(io : IO, format : IO::ByteFormat) : Nil #

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

See also: IO#write_bytes.


[View source]
def to_json(json : JSON::Builder) : Nil #

[View source]
def to_json_object_key : String #

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

Appends a string representation of this integer to the given io.

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 if upcase is true, unless base 62 is used. In that case, lowercase letters are used for 10 to 35, and uppercase ones for 36 to 61, and upcase must be false.

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. If self and precision are both zero, returns an empty string.


[View source]
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 if upcase is true, unless base 62 is used. In that case, lowercase letters are used for 10 to 35, and uppercase ones for 36 to 61, and upcase must be false.

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. If self and precision 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"

[View source]
abstract def trailing_zeros_count #

Returns the number of trailing 0-bits.


[View source]
def trunc : self #

[View source]
def upto(to, &block : self -> ) : Nil #

[View source]
def upto(to) #

[View source]
def week : Time::Span #

Returns a Time::Span of self weeks.


[View source]
def weeks : Time::Span #

Returns a Time::Span of self weeks.


[View source]
def year : Time::MonthSpan #

Returns a Time::MonthSpan of self years.


[View source]
def years : Time::MonthSpan #

Returns a Time::MonthSpan of self years.


[View source]