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.crbig/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
-
.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 : BigInt) : BigInt
- #*(other : BigRational) : BigRational
- #*(other : BigDecimal) : BigDecimal
-
#**(exponent : Int) : self
Returns the value of raising
self
to the power of exponent. -
#**(exponent : Float) : Float64
Returns the value of raising
self
to the power of exponent. - #+(other : BigInt) : BigInt
- #+(other : BigRational) : BigRational
- #+(other : BigDecimal) : BigDecimal
- #-(other : BigInt) : BigInt
- #-(other : BigRational) : BigRational
- #-(other : BigDecimal) : BigDecimal
- #/(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 : BigInt)
- #<=>(other : Int) : Int32
- #<=>(other : BigFloat)
- #<=>(other : BigRational)
-
#<=>(other : BigDecimal)
The comparison operator.
- #===(char : Char)
-
#>>(count : Int)
Returns the result of shifting this number's bits count positions to the right.
- #~
-
#abs : self
Returns the absolute value of this number.
-
#bit(bit)
Returns this number's bitth bit, starting with the least-significant.
-
#bit_length : Int32
Returns the number of bits of this int value.
-
#bits(range : Range)
Returns the requested range of bits
-
#bits_set?(mask) : Bool
Returns
true
if all bits in mask are set onself
. - #ceil : self
-
#chr : Char
Returns a
Char
that has the unicode codepoint ofself
. -
#day : Time::Span
Returns a
Time::Span
ofself
days. -
#days : Time::Span
Returns a
Time::Span
ofself
days. -
#digits(base = 10) : Array(Int32)
Returns the digits of a number in a given base.
- #divisible_by?(num) : Bool
-
#downto(to, &block : self -> ) : Nil
Calls the given block with each integer value from self down to
#to
. -
#downto(to)
Get an iterator for counting down from self to
#to
. - #even? : Bool
- #fdiv(other) : Float64
- #floor : self
-
#gcd(other : self) : self
Returns the greatest common divisor of
self
and other. -
#gcd(other : BigInt) : Int
Returns the greatest common divisor of
self
and other. - #hash(hasher)
-
#hour : Time::Span
Returns a
Time::Span
ofself
hours. -
#hours : Time::Span
Returns a
Time::Span
ofself
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
. -
#integer? : Bool
Returns
true
ifself
is an integer. -
#lcm(other : BigInt) : BigInt
Returns the least common multiple of
self
and other. -
#lcm(other : Int)
Returns the least common multiple of
self
and other. -
#microsecond : Time::Span
Returns a
Time::Span
ofself
microseconds. -
#microseconds : Time::Span
Returns a
Time::Span
ofself
microseconds. -
#millisecond : Time::Span
Returns a
Time::Span
ofself
milliseconds. -
#milliseconds : Time::Span
Returns a
Time::Span
ofself
milliseconds. -
#minute : Time::Span
Returns a
Time::Span
ofself
minutes. -
#minutes : Time::Span
Returns a
Time::Span
ofself
minutes. - #modulo(other)
-
#month : Time::MonthSpan
Returns a
Time::MonthSpan
ofself
months. -
#months : Time::MonthSpan
Returns a
Time::MonthSpan
ofself
months. -
#nanosecond : Time::Span
Returns a
Time::Span
ofself
nanoseconds. -
#nanoseconds : Time::Span
Returns a
Time::Span
ofself
nanoseconds. - #odd? : Bool
-
#popcount
Counts
1
-bits in the binary representation of this integer. - #pred : self
-
#remainder(other : Int)
Returns
self
remainder other. -
#round(mode : RoundingMode) : self
Rounds
self
to an integer value using rounding mode. -
#round_away
Returns
self
. -
#round_even : self
Returns
self
. -
#second : Time::Span
Returns a
Time::Span
ofself
seconds. -
#seconds : Time::Span
Returns a
Time::Span
ofself
seconds. - #succ : self
-
#tdiv(other : Int)
Divides
self
by other using truncated division. - #times(&block : self -> ) : Nil
- #times
- #to(to, &block : self -> ) : Nil
- #to(to)
-
#to_big_d : BigDecimal
Converts
self
toBigDecimal
. -
#to_big_i : BigInt
Returns a
BigInt
representing this integer. -
#to_big_r : BigRational
Returns a
BigRational
representing this integer. -
#to_io(io : IO, format : IO::ByteFormat) : Nil
Writes this integer to the given io in the given format.
- #to_json(json : JSON::Builder) : Nil
- #to_json_object_key : String
-
#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.
-
#to_s(base : Int = 10, *, precision : Int = 1, upcase : Bool = false) : String
Returns a string representation of this integer.
-
#trailing_zeros_count
Returns the number of trailing
0
-bits. - #trunc : self
- #upto(to, &block : self -> ) : Nil
- #upto(to)
-
#week : Time::Span
Returns a
Time::Span
ofself
weeks. -
#weeks : Time::Span
Returns a
Time::Span
ofself
weeks. -
#year : Time::MonthSpan
Returns a
Time::MonthSpan
ofself
years. -
#years : Time::MonthSpan
Returns a
Time::MonthSpan
ofself
years.
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, humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Indexable = SI_PREFIXES) : Nil
humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : 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 : Int32, Float64 -> Tuple(Int32, _) | Tuple(Int32, _, Bool)) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &) : String
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, 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
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, &) : Nilstep(*, 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
Constructor Detail
Reads an integer from the given io in the given format.
See also: IO#read_bytes
.
Instance Method Detail
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
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
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
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.
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
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]
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
Returns the absolute value of this number.
123.abs # => 123
-123.abs # => 123
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
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
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
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
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'
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
Calls the given block with each integer value from self down to #to
.
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
Returns the greatest common divisor of self
and other.
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.
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.
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
.
Returns the least common multiple of self
and other.
Returns the least common multiple of self
and other.
Raises OverflowError
in case of overflow.
Counts 1
-bits in the binary representation of this integer.
5.popcount # => 2
-15.popcount # => 29
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).
Divides self
by other using truncated division.
In truncated division, given two integers x and y:
q = x.tdiv(y)
is rounded toward zeror = x.remainder(y)
has the sign of the first argumentx == 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.
Returns a BigInt
representing this integer.
require "big"
123.to_big_i
Returns a BigRational
representing this integer.
require "big"
123.to_big_r
Writes this integer to the given io in the given format.
See also: IO#write_bytes
.
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.
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"