/Crystal

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

Defined in:

big/big_decimal.cr
big/big_int.cr
big/big_rational.cr
humanize.cr
int.cr
json/to_json.cr
time/span.cr:390
time/span.cr:558

Constructor Detail

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

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

See also: `IO#read_bytes`.

Instance Method Detail

def %(other : Int)Source

Returns `self` modulo other.

This uses floored division.

See `Int#/` for more details.

def &**(exponent : Int) : selfSource

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 **(exponent : Float) : Float64Source

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) : selfSource

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::Primitive)Source

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)Source

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)Source

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 >>(count : Int)Source

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 absSource

Description copied from struct Number

Returns the absolute value of this number.

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

def bit(bit)Source

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 bit_length : Int32Source

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 bits(range : Range)Source

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

def chrSource

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

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

def days : Time::SpanSource

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

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

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 gcd(other : self) : selfSource

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) # => 5
5.gcd(7)  # => 1```

def hash(hasher)Source

See `Object#hash(hasher)`

def hour : Time::SpanSource

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

def hours : Time::SpanSource

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

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

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) : StringSource

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 microsecond : Time::SpanSource

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

def microseconds : Time::SpanSource

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

def millisecond : Time::SpanSource

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

def milliseconds : Time::SpanSource

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

def minute : Time::SpanSource

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

def minutes : Time::SpanSource

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

def month : Time::MonthSpanSource

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

def months : Time::MonthSpanSource

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

def nanosecond : Time::SpanSource

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

def nanoseconds : Time::SpanSource

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

abstract def popcountSource

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

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

def remainder(other : Int)Source

Returns `self` remainder other.

This uses truncated division.

See `Int#tdiv` for more details.

def roundSource

Description copied from struct Number

Rounds this number to a given precision in decimal digits.

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

def second : Time::SpanSource

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

def seconds : Time::SpanSource

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

def tdiv(other : Int)Source

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_dSource

Converts `self` to `BigDecimal`.

```require "big"
12123415151254124124.to_big_d```

def to_big_i : BigIntSource

Returns a `BigInt` representing this integer.

```require "big"

123.to_big_i```

def to_big_rSource

Returns a `BigRational` representing this integer.

```require "big"

123.to_big_r```

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

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

See also: `IO#write_bytes`.

def to_s(base : Int, _upcase : Bool) : StringSource

DEPRECATED Use `#to_s(base : Int, *, upcase : Bool = false)` instead

def to_s(base : Int, io : IO, upcase : Bool = false) : NilSource

DEPRECATED Use `#to_s(io : IO, base : Int, *, upcase : Bool = false)` instead

abstract def trailing_zeros_countSource

Returns the number of trailing `0`-bits.

def week : Time::SpanSource

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

def weeks : Time::SpanSource

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

def year : Time::MonthSpanSource

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

def years : Time::MonthSpanSource

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