integer.rbs

# Holds Integer values.  You cannot add a singleton method to an Integer object,
# any attempt to do so will raise a TypeError.
#
class Integer < Numeric
  # Returns the integer square root of the non-negative integer `n`, i.e. the
  # largest non-negative integer less than or equal to the square root of `n`.
  #
  #     Integer.sqrt(0)        #=> 0
  #     Integer.sqrt(1)        #=> 1
  #     Integer.sqrt(24)       #=> 4
  #     Integer.sqrt(25)       #=> 5
  #     Integer.sqrt(10**400)  #=> 10**200
  #
  # Equivalent to `Math.sqrt(n).floor`, except that the result of the latter code
  # may differ from the true value due to the limited precision of floating point
  # arithmetic.
  #
  #     Integer.sqrt(10**46)     #=> 100000000000000000000000
  #     Math.sqrt(10**46).floor  #=>  99999999999999991611392 (!)
  #
  # If `n` is not an Integer, it is converted to an Integer first. If `n` is
  # negative, a Math::DomainError is raised.
  #
  def self.sqrt: (int n) -> Integer

  public

  # Returns `int` modulo `other`.
  #
  # See Numeric#divmod for more information.
  #
  def %: (Float) -> Float
       | (Rational) -> Rational
       | (Integer) -> Integer
       | (Numeric) -> Numeric

  # Bitwise AND.
  #
  def &: (Integer) -> Integer

  # Performs multiplication: the class of the resulting object depends on the
  # class of `numeric`.
  #
  def *: (Float) -> Float
       | (Rational) -> Rational
       | (Complex) -> Complex
       | (Integer) -> Integer

  # Raises `int` to the power of `numeric`, which may be negative or fractional.
  # The result may be an Integer, a Float, a Rational, or a complex number.
  #
  #     2 ** 3        #=> 8
  #     2 ** -1       #=> (1/2)
  #     2 ** 0.5      #=> 1.4142135623730951
  #     (-1) ** 0.5   #=> (0.0+1.0i)
  #
  #     123456789 ** 2     #=> 15241578750190521
  #     123456789 ** 1.2   #=> 5126464716.0993185
  #     123456789 ** -2    #=> (1/15241578750190521)
  #
  def **: (Integer) -> Numeric
        | (Float) -> Numeric
        | (Rational) -> Numeric
        | (Complex) -> Complex

  # Performs addition: the class of the resulting object depends on the class of
  # `numeric`.
  #
  def +: (Integer) -> Integer
       | (Float) -> Float
       | (Rational) -> Rational
       | (Complex) -> Complex

  def +@: () -> Integer

  # Performs subtraction: the class of the resulting object depends on the class
  # of `numeric`.
  #
  def -: (Integer) -> Integer
       | (Float) -> Float
       | (Rational) -> Rational
       | (Complex) -> Complex

  # Returns `int`, negated.
  #
  def -@: () -> Integer

  # Performs division: the class of the resulting object depends on the class of
  # `numeric`.
  #
  def /: (Integer) -> Integer
       | (Float) -> Float
       | (Rational) -> Rational
       | (Complex) -> Complex

  # Returns `true` if the value of `int` is less than that of `real`.
  #
  def <: (Numeric) -> bool

  # Returns `int` shifted left `count` positions, or right if `count` is negative.
  #
  def <<: (int) -> Integer

  # Returns `true` if the value of `int` is less than or equal to that of `real`.
  #
  def <=: (Numeric) -> bool

  # Comparison---Returns -1, 0, or +1 depending on whether `int` is less than,
  # equal to, or greater than `numeric`.
  #
  # This is the basis for the tests in the Comparable module.
  #
  # `nil` is returned if the two values are incomparable.
  #
  def <=>: (Numeric) -> Integer?

  # Returns `true` if `int` equals `other` numerically. Contrast this with
  # Integer#eql?, which requires `other` to be an Integer.
  #
  #     1 == 2     #=> false
  #     1 == 1.0   #=> true
  #
  def ==: (untyped) -> bool

  # Returns `true` if `int` equals `other` numerically. Contrast this with
  # Integer#eql?, which requires `other` to be an Integer.
  #
  #     1 == 2     #=> false
  #     1 == 1.0   #=> true
  #
  def ===: (untyped) -> bool

  # Returns `true` if the value of `int` is greater than that of `real`.
  #
  def >: (Numeric) -> bool

  # Returns `true` if the value of `int` is greater than or equal to that of
  # `real`.
  #
  def >=: (Numeric) -> bool

  # Returns `int` shifted right `count` positions, or left if `count` is negative.
  #
  def >>: (int) -> Integer

  # Bit Reference---Returns the `n`th bit in the binary representation of `int`,
  # where `int[0]` is the least significant bit.
  #
  #     a = 0b11001100101010
  #     30.downto(0) {|n| print a[n] }
  #     #=> 0000000000000000011001100101010
  #
  #     a = 9**15
  #     50.downto(0) {|n| print a[n] }
  #     #=> 000101110110100000111000011110010100111100010111001
  #
  # In principle, `n[i]` is equivalent to `(n >> i) & 1`. Thus, any negative index
  # always returns zero:
  #
  #     p 255[-1] #=> 0
  #
  # Range operations `n[i, len]` and `n[i..j]` are naturally extended.
  #
  # *   `n[i, len]` equals to `(n >> i) & ((1 << len) - 1)`.
  # *   `n[i..j]` equals to `(n >> i) & ((1 << (j - i + 1)) - 1)`.
  # *   `n[i...j]` equals to `(n >> i) & ((1 << (j - i)) - 1)`.
  # *   `n[i..]` equals to `(n >> i)`.
  # *   `n[..j]` is zero if `n & ((1 << (j + 1)) - 1)` is zero.  Otherwise, raises
  #     an ArgumentError.
  # *   `n[...j]` is zero if `n & ((1 << j) - 1)` is zero.  Otherwise, raises an
  #     ArgumentError.
  #
  #
  # Note that range operation may exhaust memory. For example, `-1[0,
  # 1000000000000]` will raise NoMemoryError.
  #
  def []: (int) -> Integer
        | (int i, int len) -> Integer
        | (Range[int]) -> Integer

  # Bitwise EXCLUSIVE OR.
  #
  def ^: (Integer) -> Integer

  # Returns the absolute value of `int`.
  #
  #     (-12345).abs   #=> 12345
  #     -12345.abs     #=> 12345
  #     12345.abs      #=> 12345
  #
  # Integer#magnitude is an alias for Integer#abs.
  #
  def abs: () -> Integer

  def abs2: () -> Integer

  # Returns `true` if all bits of `int & mask` are 1.
  #
  def allbits?: (int mask) -> bool

  def angle: () -> (Integer | Float)

  # Returns `true` if any bits of `int & mask` are 1.
  #
  def anybits?: (int mask) -> bool

  alias arg angle

  # Returns the number of bits of the value of `int`.
  #
  # "Number of bits" means the bit position of the highest bit which is different
  # from the sign bit (where the least significant bit has bit position 1). If
  # there is no such bit (zero or minus one), zero is returned.
  #
  # I.e. this method returns *ceil(log2(int < 0 ? -int : int+1))*.
  #
  #     (-2**1000-1).bit_length   #=> 1001
  #     (-2**1000).bit_length     #=> 1000
  #     (-2**1000+1).bit_length   #=> 1000
  #     (-2**12-1).bit_length     #=> 13
  #     (-2**12).bit_length       #=> 12
  #     (-2**12+1).bit_length     #=> 12
  #     -0x101.bit_length         #=> 9
  #     -0x100.bit_length         #=> 8
  #     -0xff.bit_length          #=> 8
  #     -2.bit_length             #=> 1
  #     -1.bit_length             #=> 0
  #     0.bit_length              #=> 0
  #     1.bit_length              #=> 1
  #     0xff.bit_length           #=> 8
  #     0x100.bit_length          #=> 9
  #     (2**12-1).bit_length      #=> 12
  #     (2**12).bit_length        #=> 13
  #     (2**12+1).bit_length      #=> 13
  #     (2**1000-1).bit_length    #=> 1000
  #     (2**1000).bit_length      #=> 1001
  #     (2**1000+1).bit_length    #=> 1001
  #
  # This method can be used to detect overflow in Array#pack as follows:
  #
  #     if n.bit_length < 32
  #       [n].pack("l") # no overflow
  #     else
  #       raise "overflow"
  #     end
  #
  def bit_length: () -> Integer

  # Returns the smallest number greater than or equal to `int` with a precision of
  # `ndigits` decimal digits (default: 0).
  #
  # When the precision is negative, the returned value is an integer with at least
  # `ndigits.abs` trailing zeros.
  #
  # Returns `self` when `ndigits` is zero or positive.
  #
  #     1.ceil           #=> 1
  #     1.ceil(2)        #=> 1
  #     18.ceil(-1)      #=> 20
  #     (-18).ceil(-1)   #=> -10
  #
  def ceil: () -> Integer
          | (int digits) -> (Integer | Float)

  # Returns a string containing the character represented by the `int`'s value
  # according to `encoding`.
  #
  #     65.chr    #=> "A"
  #     230.chr   #=> "\xE6"
  #     255.chr(Encoding::UTF_8)   #=> "\u00FF"
  #
  def chr: (?encoding) -> String

  def clone: (?freeze: bool) -> self

  # Returns an array with both a `numeric` and a `big` represented as Bignum
  # objects.
  #
  # This is achieved by converting `numeric` to a Bignum.
  #
  # A TypeError is raised if the `numeric` is not a Fixnum or Bignum type.
  #
  #     (0x3FFFFFFFFFFFFFFF+1).coerce(42)   #=> [42, 4611686018427387904]
  #
  def coerce: (Numeric) -> [Numeric, Numeric]

  def conj: () -> Integer

  def conjugate: () -> Integer

  # Returns 1.
  #
  def denominator: () -> Integer

  # Returns the digits of `int`'s place-value representation with radix `base`
  # (default: 10). The digits are returned as an array with the least significant
  # digit as the first array element.
  #
  # `base` must be greater than or equal to 2.
  #
  #     12345.digits      #=> [5, 4, 3, 2, 1]
  #     12345.digits(7)   #=> [4, 6, 6, 0, 5]
  #     12345.digits(100) #=> [45, 23, 1]
  #
  #     -12345.digits(7)  #=> Math::DomainError
  #
  def digits: (?int base) -> ::Array[Integer]

  # Performs integer division: returns the integer result of dividing `int` by
  # `numeric`.
  #
  def div: (Numeric) -> Integer

  # See Numeric#divmod.
  #
  def divmod: (Integer) -> [Integer, Integer]
            | (Float) -> [Float, Float]
            | (Numeric) -> [Numeric, Numeric]

  # Iterates the given block, passing in decreasing values from `int` down to and
  # including `limit`.
  #
  # If no block is given, an Enumerator is returned instead.
  #
  #     5.downto(1) { |n| print n, ".. " }
  #     puts "Liftoff!"
  #     #=> "5.. 4.. 3.. 2.. 1.. Liftoff!"
  #
  def downto: (Integer limit) { (Integer) -> void } -> Integer
            | (Integer limit) -> ::Enumerator[Integer, self]

  def dup: () -> self

  def eql?: (untyped) -> bool

  # Returns `true` if `int` is an even number.
  #
  def even?: () -> bool

  # Returns the floating point result of dividing `int` by `numeric`.
  #
  #     654321.fdiv(13731)      #=> 47.652829364212366
  #     654321.fdiv(13731.24)   #=> 47.65199646936475
  #     -654321.fdiv(13731)     #=> -47.652829364212366
  #
  def fdiv: (Numeric) -> Float

  def finite?: () -> bool

  # Returns the largest number less than or equal to `int` with a precision of
  # `ndigits` decimal digits (default: 0).
  #
  # When the precision is negative, the returned value is an integer with at least
  # `ndigits.abs` trailing zeros.
  #
  # Returns `self` when `ndigits` is zero or positive.
  #
  #     1.floor           #=> 1
  #     1.floor(2)        #=> 1
  #     18.floor(-1)      #=> 10
  #     (-18).floor(-1)   #=> -20
  #
  def floor: () -> Integer
           | (int digits) -> (Integer | Float)

  # Returns the greatest common divisor of the two integers. The result is always
  # positive. 0.gcd(x) and x.gcd(0) return x.abs.
  #
  #     36.gcd(60)                  #=> 12
  #     2.gcd(2)                    #=> 2
  #     3.gcd(-7)                   #=> 1
  #     ((1<<31)-1).gcd((1<<61)-1)  #=> 1
  #
  def gcd: (Integer) -> Integer

  # Returns an array with the greatest common divisor and the least common
  # multiple of the two integers, [gcd, lcm].
  #
  #     36.gcdlcm(60)                  #=> [12, 180]
  #     2.gcdlcm(2)                    #=> [2, 2]
  #     3.gcdlcm(-7)                   #=> [1, 21]
  #     ((1<<31)-1).gcdlcm((1<<61)-1)  #=> [1, 4951760154835678088235319297]
  #
  def gcdlcm: (Integer) -> [ Integer, Integer ]

  def i: () -> Complex

  def imag: () -> Integer

  def imaginary: () -> Integer

  def infinite?: () -> Integer?

  alias inspect to_s

  # Since `int` is already an Integer, this always returns `true`.
  #
  def integer?: () -> true

  # Returns the least common multiple of the two integers. The result is always
  # positive. 0.lcm(x) and x.lcm(0) return zero.
  #
  #     36.lcm(60)                  #=> 180
  #     2.lcm(2)                    #=> 2
  #     3.lcm(-7)                   #=> 21
  #     ((1<<31)-1).lcm((1<<61)-1)  #=> 4951760154835678088235319297
  #
  def lcm: (Integer) -> Integer

  # Returns the absolute value of `int`.
  #
  #     (-12345).abs   #=> 12345
  #     -12345.abs     #=> 12345
  #     12345.abs      #=> 12345
  #
  # Integer#magnitude is an alias for Integer#abs.
  #
  def magnitude: () -> Integer

  # Returns `int` modulo `other`.
  #
  # See Numeric#divmod for more information.
  #
  alias modulo `%`

  def negative?: () -> bool

  # Returns the successor of `int`, i.e. the Integer equal to `int+1`.
  #
  #     1.next      #=> 2
  #     (-1).next   #=> 0
  #     1.succ      #=> 2
  #     (-1).succ   #=> 0
  #
  def next: () -> Integer

  # Returns `true` if no bits of `int & mask` are 1.
  #
  def nobits?: (int mask) -> bool

  def nonzero?: () -> self?

  # Returns self.
  #
  def numerator: () -> Integer

  # Returns `true` if `int` is an odd number.
  #
  def odd?: () -> bool

  # Returns the `int` itself.
  #
  #     97.ord   #=> 97
  #
  # This method is intended for compatibility to character literals in Ruby 1.9.
  #
  # For example, `?a.ord` returns 97 both in 1.8 and 1.9.
  #
  def ord: () -> Integer

  alias phase angle

  def polar: () -> [ Integer, Integer | Float ]

  def positive?: () -> bool

  # Returns (modular) exponentiation as:
  #
  #     a.pow(b)     #=> same as a**b
  #     a.pow(b, m)  #=> same as (a**b) % m, but avoids huge temporary values
  #
  def pow: (Integer other, ?Integer modulo) -> Integer
         | (Float) -> Float
         | (Rational) -> Rational
         | (Complex) -> Complex

  # Returns the predecessor of `int`, i.e. the Integer equal to `int-1`.
  #
  #     1.pred      #=> 0
  #     (-1).pred   #=> -2
  #
  def pred: () -> Integer

  def quo: (Integer) -> Rational
         | (Float) -> Float
         | (Rational) -> Rational
         | (Complex) -> Complex
         | (Numeric) -> Numeric

  # Returns the value as a rational.  The optional argument `eps` is always
  # ignored.
  #
  def rationalize: (?Numeric eps) -> Rational

  def real: () -> self

  def real?: () -> true

  def rect: () -> [ Integer, Numeric ]

  alias rectangular rect

  # Returns the remainder after dividing `int` by `numeric`.
  #
  # `x.remainder(y)` means `x-y*(x/y).truncate`.
  #
  #     5.remainder(3)     #=> 2
  #     -5.remainder(3)    #=> -2
  #     5.remainder(-3)    #=> 2
  #     -5.remainder(-3)   #=> -2
  #     5.remainder(1.5)   #=> 0.5
  #
  # See Numeric#divmod.
  #
  def remainder: (Integer) -> Integer
               | (Float) -> Float
               | (Rational) -> Rational
               | (Numeric) -> Numeric

  # Returns `int` rounded to the nearest value with a precision of `ndigits`
  # decimal digits (default: 0).
  #
  # When the precision is negative, the returned value is an integer with at least
  # `ndigits.abs` trailing zeros.
  #
  # Returns `self` when `ndigits` is zero or positive.
  #
  #     1.round           #=> 1
  #     1.round(2)        #=> 1
  #     15.round(-1)      #=> 20
  #     (-15).round(-1)   #=> -20
  #
  # The optional `half` keyword argument is available similar to Float#round.
  #
  #     25.round(-1, half: :up)      #=> 30
  #     25.round(-1, half: :down)    #=> 20
  #     25.round(-1, half: :even)    #=> 20
  #     35.round(-1, half: :up)      #=> 40
  #     35.round(-1, half: :down)    #=> 30
  #     35.round(-1, half: :even)    #=> 40
  #     (-25).round(-1, half: :up)   #=> -30
  #     (-25).round(-1, half: :down) #=> -20
  #     (-25).round(-1, half: :even) #=> -20
  #
  def round: (?half: :up | :down | :even) -> Integer
           | (int digits, ?half: :up | :down | :even) -> (Integer | Float)

  # Returns the number of bytes in the machine representation of `int` (machine
  # dependent).
  #
  #     1.size               #=> 8
  #     -1.size              #=> 8
  #     2147483647.size      #=> 8
  #     (256**10 - 1).size   #=> 10
  #     (256**20 - 1).size   #=> 20
  #     (256**40 - 1).size   #=> 40
  #
  def size: () -> Integer

  def step: () { (Integer) -> void } -> void
          | (Numeric limit, ?Integer step) { (Integer) -> void } -> void
          | (Numeric limit, ?Numeric step) { (Numeric) -> void } -> void
          | (to: Numeric, ?by: Integer) { (Integer) -> void } -> void
          | (?to: Numeric, by: Numeric) { (Numeric) -> void } -> void
          | () -> Enumerator[Integer, bot]
          | (Numeric limit, ?Integer step) -> Enumerator[Integer, void]
          | (Numeric limit, ?Numeric step) -> Enumerator[Numeric, void]
          | (to: Numeric, ?by: Integer) -> Enumerator[Integer, void]
          | (?to: Numeric, by: Numeric) -> Enumerator[Numeric, void]

  # Returns the successor of `int`, i.e. the Integer equal to `int+1`.
  #
  #     1.next      #=> 2
  #     (-1).next   #=> 0
  #     1.succ      #=> 2
  #     (-1).succ   #=> 0
  #
  def succ: () -> Integer

  # Iterates the given block `int` times, passing in values from zero to `int -
  # 1`.
  #
  # If no block is given, an Enumerator is returned instead.
  #
  #     5.times {|i| print i, " " }   #=> 0 1 2 3 4
  #
  def times: () { (Integer) -> void } -> self
           | () -> ::Enumerator[Integer, self]

  def to_c: () -> Complex

  # Converts `int` to a Float.  If `int` doesn't fit in a Float, the result is
  # infinity.
  #
  def to_f: () -> Float

  # Since `int` is already an Integer, returns `self`.
  #
  # #to_int is an alias for #to_i.
  #
  def to_i: () -> Integer

  # Since `int` is already an Integer, returns `self`.
  #
  # #to_int is an alias for #to_i.
  #
  alias to_int to_i

  # Returns the value as a rational.
  #
  #     1.to_r        #=> (1/1)
  #     (1<<64).to_r  #=> (18446744073709551616/1)
  #
  def to_r: () -> Rational

  # Returns a string containing the place-value representation of `int` with radix
  # `base` (between 2 and 36).
  #
  #     12345.to_s       #=> "12345"
  #     12345.to_s(2)    #=> "11000000111001"
  #     12345.to_s(8)    #=> "30071"
  #     12345.to_s(10)   #=> "12345"
  #     12345.to_s(16)   #=> "3039"
  #     12345.to_s(36)   #=> "9ix"
  #     78546939656932.to_s(36)  #=> "rubyrules"
  #
  def to_s: () -> String
          | (2) -> String
          | (3) -> String
          | (4) -> String
          | (5) -> String
          | (6) -> String
          | (7) -> String
          | (8) -> String
          | (9) -> String
          | (10) -> String
          | (11) -> String
          | (12) -> String
          | (13) -> String
          | (14) -> String
          | (15) -> String
          | (16) -> String
          | (17) -> String
          | (18) -> String
          | (19) -> String
          | (20) -> String
          | (21) -> String
          | (22) -> String
          | (23) -> String
          | (24) -> String
          | (25) -> String
          | (26) -> String
          | (27) -> String
          | (28) -> String
          | (29) -> String
          | (30) -> String
          | (31) -> String
          | (32) -> String
          | (33) -> String
          | (34) -> String
          | (35) -> String
          | (36) -> String
          | (int base) -> String

  # Returns `int` truncated (toward zero) to a precision of `ndigits` decimal
  # digits (default: 0).
  #
  # When the precision is negative, the returned value is an integer with at least
  # `ndigits.abs` trailing zeros.
  #
  # Returns `self` when `ndigits` is zero or positive.
  #
  #     1.truncate           #=> 1
  #     1.truncate(2)        #=> 1
  #     18.truncate(-1)      #=> 10
  #     (-18).truncate(-1)   #=> -10
  #
  def truncate: () -> Integer
              | (int ndigits) -> Integer

  # Iterates the given block, passing in integer values from `int` up to and
  # including `limit`.
  #
  # If no block is given, an Enumerator is returned instead.
  #
  #     5.upto(10) {|i| print i, " " }   #=> 5 6 7 8 9 10
  #
  def upto: (Integer limit) { (Integer) -> void } -> Integer
          | (Integer limit) -> ::Enumerator[Integer, self]

  def zero?: () -> bool

  # Bitwise OR.
  #
  def |: (Integer) -> Integer

  # One's complement: returns a number where each bit is flipped.
  #
  # Inverts the bits in an Integer. As integers are conceptually of infinite
  # length, the result acts as if it had an infinite number of one bits to the
  # left. In hex representations, this is displayed as two periods to the left of
  # the digits.
  #
  #     sprintf("%X", ~0x1122334455)    #=> "..FEEDDCCBBAA"
  #
  def ~: () -> Integer
end