class Integer - RDoc Documentation

# class Integer

Holds `Integer` values. You cannot add a singleton method to an `Integer` object, any attempt to do so will raise a `TypeError`.

### Constants

GMP_VERSION

  The version of loaded GMP.

MILLER_RABIN_BASES

### Public Class Methods

each_prime(ubound) { |prime| ... } click to toggle source

Iterates the given block over all prime numbers.

See `Prime`#each for more details.

    # File lib/prime.rb, line 122
    def Integer.each_prime(ubound, &block) # :yields: prime
      Prime.each(ubound, &block)
    end

from_prime_division(pd) click to toggle source

Re-composes a prime factorization and returns the product.

See `Prime#int_from_prime_division` for more details.

    # File lib/prime.rb, line 22
    def Integer.from_prime_division(pd)
      Prime.int_from_prime_division(pd)
    end

sqrt(n) → integer click to toggle source

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.

    static VALUE
    rb_int_s_isqrt(VALUE self, VALUE num)
    {
        unsigned long n, sq;
        num = rb_to_int(num);
        if (FIXNUM_P(num)) {
            if (FIXNUM_NEGATIVE_P(num)) {
                domain_error("isqrt");
            }
            n = FIX2ULONG(num);
            sq = rb_ulong_isqrt(n);
            return LONG2FIX(sq);
        }
        else {
            size_t biglen;
            if (RBIGNUM_NEGATIVE_P(num)) {
                domain_error("isqrt");
            }
            biglen = BIGNUM_LEN(num);
            if (biglen == 0) return INT2FIX(0);
    #if SIZEOF_BDIGIT <= SIZEOF_LONG
            /* short-circuit */
            if (biglen == 1) {
                n = BIGNUM_DIGITS(num)[0];
                sq = rb_ulong_isqrt(n);
                return ULONG2NUM(sq);
            }
    #endif
            return rb_big_isqrt(num);
        }
    }

### Public Instance Methods

int % other → real click to toggle source

Returns `int` modulo `other`.

See `Numeric#divmod` for more information.

    VALUE
    rb_int_modulo(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_mod(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_modulo(x, y);
        }
        return num_modulo(x, y);
    }

Also aliased as: modulo
int & other_int → integer click to toggle source

Bitwise AND.

    VALUE
    rb_int_and(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_and(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_and(x, y);
        }
        return Qnil;
    }

int * numeric → numeric_result click to toggle source

Performs multiplication: the class of the resulting object depends on the class of `numeric`.

    VALUE
    rb_int_mul(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_mul(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_mul(x, y);
        }
        return rb_num_coerce_bin(x, y, '*');
    }

int ** numeric → numeric_result click to toggle source

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)

    VALUE
    rb_int_pow(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_pow(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_pow(x, y);
        }
        return Qnil;
    }

int + numeric → numeric_result click to toggle source

Performs addition: the class of the resulting object depends on the class of `numeric`.

    VALUE
    rb_int_plus(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_plus(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_plus(x, y);
        }
        return rb_num_coerce_bin(x, y, '+');
    }

int - numeric → numeric_result click to toggle source

Performs subtraction: the class of the resulting object depends on the class of `numeric`.

    VALUE
    rb_int_minus(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_minus(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_minus(x, y);
        }
        return rb_num_coerce_bin(x, y, '-');
    }

-int → integer click to toggle source

Returns `int`, negated.

    # File integer.rb, line 6
    def -@
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_uminus(self)'
    end

int / numeric → numeric_result click to toggle source

Performs division: the class of the resulting object depends on the class of `numeric`.

    VALUE
    rb_int_div(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_div(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_div(x, y);
        }
        return Qnil;
    }

int < real → true or false click to toggle source

Returns `true` if the value of `int` is less than that of `real`.

    static VALUE
    int_lt(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_lt(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_lt(x, y);
        }
        return Qnil;
    }

int << count → integer click to toggle source

Returns `int` shifted left `count` positions, or right if `count` is negative.

    VALUE
    rb_int_lshift(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return rb_fix_lshift(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_lshift(x, y);
        }
        return Qnil;
    }

int <= real → true or false click to toggle source

Returns `true` if the value of `int` is less than or equal to that of `real`.

    static VALUE
    int_le(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_le(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_le(x, y);
        }
        return Qnil;
    }

int <=> numeric → -1, 0, +1, or nil click to toggle source

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.

    VALUE
    rb_int_cmp(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_cmp(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_cmp(x, y);
        }
        else {
            rb_raise(rb_eNotImpError, "need to define `<=>' in %s", rb_obj_classname(x));
        }
    }

int == other → true or false

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

Alias for: ===

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

    VALUE
    rb_int_equal(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_equal(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_eq(x, y);
        }
        return Qnil;
    }

Also aliased as: ==
int > real → true or false click to toggle source

Returns `true` if the value of `int` is greater than that of `real`.

    VALUE
    rb_int_gt(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_gt(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_gt(x, y);
        }
        return Qnil;
    }

int >= real → true or false click to toggle source

Returns `true` if the value of `int` is greater than or equal to that of `real`.

    VALUE
    rb_int_ge(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_ge(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_ge(x, y);
        }
        return Qnil;
    }

int >> count → integer click to toggle source

Returns `int` shifted right `count` positions, or left if `count` is negative.

    static VALUE
    rb_int_rshift(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return rb_fix_rshift(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_rshift(x, y);
        }
        return Qnil;
    }

int[n] → 0, 1 click to toggle source
int[n, m] → num
int[range] → num

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

    static VALUE
    int_aref(int const argc, VALUE * const argv, VALUE const num)
    {
        rb_check_arity(argc, 1, 2);
        if (argc == 2) {
            return int_aref2(num, argv[0], argv[1]);
        }
        return int_aref1(num, argv[0]);

        return Qnil;
    }

int ^ other_int → integer click to toggle source

Bitwise EXCLUSIVE OR.

    static VALUE
    int_xor(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_xor(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_xor(x, y);
        }
        return Qnil;
    }

abs() click to toggle source

    # File integer.rb, line 27
    def abs
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_abs(self)'
    end

allbits?(mask) → true or false click to toggle source

Returns `true` if all bits of `int & mask` are 1.

    static VALUE
    int_allbits_p(VALUE num, VALUE mask)
    {
        mask = rb_to_int(mask);
        return rb_int_equal(rb_int_and(num, mask), mask);
    }

anybits?(mask) → true or false click to toggle source

Returns `true` if any bits of `int & mask` are 1.

    static VALUE
    int_anybits_p(VALUE num, VALUE mask)
    {
        mask = rb_to_int(mask);
        return int_zero_p(rb_int_and(num, mask)) ? Qfalse : Qtrue;
    }

bit_length → integer click to toggle source

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

    # File integer.rb, line 73
    def bit_length
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_bit_length(self)'
    end

ceil([ndigits]) → integer or float click to toggle source

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

    static VALUE
    int_ceil(int argc, VALUE* argv, VALUE num)
    {
        int ndigits;

        if (!rb_check_arity(argc, 0, 1)) return num;
        ndigits = NUM2INT(argv[0]);
        if (ndigits >= 0) {
            return num;
        }
        return rb_int_ceil(num, ndigits);
    }

chr([encoding]) → string click to toggle source

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"

    static VALUE
    int_chr(int argc, VALUE *argv, VALUE num)
    {
        char c;
        unsigned int i;
        rb_encoding *enc;

        if (rb_num_to_uint(num, &i) == 0) {
        }
        else if (FIXNUM_P(num)) {
            rb_raise(rb_eRangeError, "%ld out of char range", FIX2LONG(num));
        }
        else {
            rb_raise(rb_eRangeError, "bignum out of char range");
        }

        switch (argc) {
          case 0:
            if (0xff < i) {
                enc = rb_default_internal_encoding();
                if (!enc) {
                    rb_raise(rb_eRangeError, "%u out of char range", i);
                }
                goto decode;
            }
            c = (char)i;
            if (i < 0x80) {
                return rb_usascii_str_new(&c, 1);
            }
            else {
                return rb_str_new(&c, 1);
            }
          case 1:
            break;
          default:
            rb_error_arity(argc, 0, 1);
        }
        enc = rb_to_encoding(argv[0]);
        if (!enc) enc = rb_ascii8bit_encoding();
      decode:
        return rb_enc_uint_chr(i, enc);
    }

coerce(numeric) → array click to toggle source

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]

    static VALUE
    rb_int_coerce(VALUE x, VALUE y)
    {
        if (RB_INTEGER_TYPE_P(y)) {
            return rb_assoc_new(y, x);
        }
        else {
            x = rb_Float(x);
            y = rb_Float(y);
            return rb_assoc_new(y, x);
        }
    }

denominator → 1 click to toggle source

Returns 1.

    static VALUE
    integer_denominator(VALUE self)
    {
        return INT2FIX(1);
    }

digits → array click to toggle source
digits(base) → array

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

    static VALUE
    rb_int_digits(int argc, VALUE *argv, VALUE num)
    {
        VALUE base_value;
        long base;

        if (rb_num_negative_p(num))
            rb_raise(rb_eMathDomainError, "out of domain");

        if (rb_check_arity(argc, 0, 1)) {
            base_value = rb_to_int(argv[0]);
            if (!RB_INTEGER_TYPE_P(base_value))
                rb_raise(rb_eTypeError, "wrong argument type %s (expected Integer)",
                         rb_obj_classname(argv[0]));
            if (RB_TYPE_P(base_value, T_BIGNUM))
                return rb_int_digits_bigbase(num, base_value);

            base = FIX2LONG(base_value);
            if (base < 0)
                rb_raise(rb_eArgError, "negative radix");
            else if (base < 2)
                rb_raise(rb_eArgError, "invalid radix %ld", base);
        }
        else
            base = 10;

        if (FIXNUM_P(num))
            return rb_fix_digits(num, base);
        else if (RB_TYPE_P(num, T_BIGNUM))
            return rb_int_digits_bigbase(num, LONG2FIX(base));

        return Qnil;
    }

div(numeric) → integer click to toggle source

Performs integer division: returns the integer result of dividing `int` by `numeric`.

    VALUE
    rb_int_idiv(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_idiv(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_idiv(x, y);
        }
        return num_div(x, y);
    }

divmod(numeric) → array click to toggle source

See `Numeric#divmod`.

    VALUE
    rb_int_divmod(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_divmod(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_divmod(x, y);
        }
        return Qnil;
    }

downto(limit) {|i| block } → self click to toggle source
downto(limit) → an_enumerator

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!"

    static VALUE
    int_downto(VALUE from, VALUE to)
    {
        RETURN_SIZED_ENUMERATOR(from, 1, &to, int_downto_size);
        if (FIXNUM_P(from) && FIXNUM_P(to)) {
            long i, end;

            end = FIX2LONG(to);
            for (i=FIX2LONG(from); i >= end; i--) {
                rb_yield(LONG2FIX(i));
            }
        }
        else {
            VALUE i = from, c;

            while (!(c = rb_funcall(i, '<', 1, to))) {
                rb_yield(i);
                i = rb_funcall(i, '-', 1, INT2FIX(1));
            }
            if (NIL_P(c)) rb_cmperr(i, to);
        }
        return from;
    }

even? → true or false click to toggle source

Returns `true` if `int` is an even number.

    # File integer.rb, line 82
    def even?
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_even_p(self)'
    end

fdiv(numeric) → float click to toggle source

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

    VALUE
    rb_int_fdiv(VALUE x, VALUE y)
    {
        if (RB_INTEGER_TYPE_P(x)) {
            return DBL2NUM(rb_int_fdiv_double(x, y));
        }
        return Qnil;
    }

floor([ndigits]) → integer or float click to toggle source

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

    static VALUE
    int_floor(int argc, VALUE* argv, VALUE num)
    {
        int ndigits;

        if (!rb_check_arity(argc, 0, 1)) return num;
        ndigits = NUM2INT(argv[0]);
        if (ndigits >= 0) {
            return num;
        }
        return rb_int_floor(num, ndigits);
    }

gcd(other_int) → integer click to toggle source

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

    VALUE
    rb_gcd(VALUE self, VALUE other)
    {
        other = nurat_int_value(other);
        return f_gcd(self, other);
    }

gcdlcm(other_int) → array click to toggle source

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]

    VALUE
    rb_gcdlcm(VALUE self, VALUE other)
    {
        other = nurat_int_value(other);
        return rb_assoc_new(f_gcd(self, other), f_lcm(self, other));
    }

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"

Alias for: to_s
integer? → true click to toggle source

Since `int` is already an `Integer`, this always returns `true`.

    # File integer.rb, line 91
    def integer?
      return true
    end

lcm(other_int) → integer click to toggle source

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

    VALUE
    rb_lcm(VALUE self, VALUE other)
    {
        other = nurat_int_value(other);
        return f_lcm(self, other);
    }

magnitude() click to toggle source

    # File integer.rb, line 95
    def magnitude
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_abs(self)'
    end

modulo(other) → real

Returns `int` modulo `other`.

See `Numeric#divmod` for more information.

Alias for: %
next → integer

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

Alias for: succ
nobits?(mask) → true or false click to toggle source

Returns `true` if no bits of `int & mask` are 1.

    static VALUE
    int_nobits_p(VALUE num, VALUE mask)
    {
        mask = rb_to_int(mask);
        return int_zero_p(rb_int_and(num, mask));
    }

numerator → self click to toggle source

Returns self.

    static VALUE
    integer_numerator(VALUE self)
    {
        return self;
    }

odd? → true or false click to toggle source

Returns `true` if `int` is an odd number.

    # File integer.rb, line 104
    def odd?
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_odd_p(self)'
    end

ord → self click to toggle source

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.

    # File integer.rb, line 120
    def ord
      return self
    end

pow(numeric) → numeric click to toggle source
pow(integer, integer) → integer

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

    VALUE
    rb_int_powm(int const argc, VALUE * const argv, VALUE const num)
    {
        rb_check_arity(argc, 1, 2);

        if (argc == 1) {
            return rb_int_pow(num, argv[0]);
        }
        else {
            VALUE const a = num;
            VALUE const b = argv[0];
            VALUE m = argv[1];
            int nega_flg = 0;
            if ( ! RB_INTEGER_TYPE_P(b)) {
                rb_raise(rb_eTypeError, "Integer#pow() 2nd argument not allowed unless a 1st argument is integer");
            }
            if (rb_int_negative_p(b)) {
                rb_raise(rb_eRangeError, "Integer#pow() 1st argument cannot be negative when 2nd argument specified");
            }
            if (!RB_INTEGER_TYPE_P(m)) {
                rb_raise(rb_eTypeError, "Integer#pow() 2nd argument not allowed unless all arguments are integers");
            }

            if (rb_int_negative_p(m)) {
                m = rb_int_uminus(m);
                nega_flg = 1;
            }

            if (FIXNUM_P(m)) {
                long const half_val = (long)HALF_LONG_MSB;
                long const mm = FIX2LONG(m);
                if (!mm) rb_num_zerodiv();
                if (mm == 1) return INT2FIX(0);
                if (mm <= half_val) {
                    return int_pow_tmp1(rb_int_modulo(a, m), b, mm, nega_flg);
                }
                else {
                    return int_pow_tmp2(rb_int_modulo(a, m), b, mm, nega_flg);
                }
            }
            else {
                if (rb_bigzero_p(m)) rb_num_zerodiv();
    	    if (bignorm(m) == INT2FIX(1)) return INT2FIX(0);
                return int_pow_tmp3(rb_int_modulo(a, m), b, m, nega_flg);
            }
        }
        UNREACHABLE_RETURN(Qnil);
    }

pred → integer click to toggle source

Returns the predecessor of `int`, i.e. the `Integer` equal to `int-1`.

    1.pred      #=> 0
    (-1).pred   #=> -2

    static VALUE
    rb_int_pred(VALUE num)
    {
        if (FIXNUM_P(num)) {
            long i = FIX2LONG(num) - 1;
            return LONG2NUM(i);
        }
        if (RB_TYPE_P(num, T_BIGNUM)) {
            return rb_big_minus(num, INT2FIX(1));
        }
        return num_funcall1(num, '-', INT2FIX(1));
    }

prime?() click to toggle source

Returns true if `self` is a prime number, else returns false. Not recommended for very big integers (> 10**23).

    # File lib/prime.rb, line 35
    def prime?
      return self >= 2 if self <= 3

      if (bases = miller_rabin_bases)
        return miller_rabin_test(bases)
      end

      return true if self == 5
      return false unless 30.gcd(self) == 1
      (7..Integer.sqrt(self)).step(30) do |p|
        return false if
          self%(p)    == 0 || self%(p+4)  == 0 || self%(p+6)  == 0 || self%(p+10) == 0 ||
          self%(p+12) == 0 || self%(p+16) == 0 || self%(p+22) == 0 || self%(p+24) == 0
      end
      true
    end

prime_division(generator = Prime::Generator23.new) click to toggle source

Returns the factorization of `self`.

See `Prime#prime_division` for more details.

    # File lib/prime.rb, line 29
    def prime_division(generator = Prime::Generator23.new)
      Prime.prime_division(self, generator)
    end

rationalize([eps]) → rational click to toggle source

Returns the value as a rational. The optional argument `eps` is always ignored.

    static VALUE
    integer_rationalize(int argc, VALUE *argv, VALUE self)
    {
        rb_check_arity(argc, 0, 1);
        return integer_to_r(self);
    }

remainder(numeric) → real click to toggle source

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

    static VALUE
    int_remainder(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return num_remainder(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_remainder(x, y);
        }
        return Qnil;
    }

round([ndigits] [, half: mode]) → integer or float click to toggle source

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

    static VALUE
    int_round(int argc, VALUE* argv, VALUE num)
    {
        int ndigits;
        int mode;
        VALUE nd, opt;

        if (!rb_scan_args(argc, argv, "01:", &nd, &opt)) return num;
        ndigits = NUM2INT(nd);
        mode = rb_num_get_rounding_option(opt);
        if (ndigits >= 0) {
            return num;
        }
        return rb_int_round(num, ndigits, mode);
    }

size → int click to toggle source

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

    static VALUE
    int_size(VALUE num)
    {
        if (FIXNUM_P(num)) {
            return fix_size(num);
        }
        else if (RB_TYPE_P(num, T_BIGNUM)) {
            return rb_big_size_m(num);
        }
        return Qnil;
    }

succ → integer click to toggle source

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

    VALUE
    rb_int_succ(VALUE num)
    {
        if (FIXNUM_P(num)) {
            long i = FIX2LONG(num) + 1;
            return LONG2NUM(i);
        }
        if (RB_TYPE_P(num, T_BIGNUM)) {
            return rb_big_plus(num, INT2FIX(1));
        }
        return num_funcall1(num, '+', INT2FIX(1));
    }

Also aliased as: next
times {|i| block } → self click to toggle source
times → an_enumerator

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

    static VALUE
    int_dotimes(VALUE num)
    {
        RETURN_SIZED_ENUMERATOR(num, 0, 0, int_dotimes_size);

        if (FIXNUM_P(num)) {
            long i, end;

            end = FIX2LONG(num);
            for (i=0; i<end; i++) {
                rb_yield_1(LONG2FIX(i));
            }
        }
        else {
            VALUE i = INT2FIX(0);

            for (;;) {
                if (!RTEST(rb_funcall(i, '<', 1, num))) break;
                rb_yield(i);
                i = rb_funcall(i, '+', 1, INT2FIX(1));
            }
        }
        return num;
    }

to_bn() click to toggle source

Casts an `Integer` as an `OpenSSL::BN`

See `man bn` for more info.

    # File ext/openssl/lib/openssl/bn.rb, line 37
    def to_bn
      OpenSSL::BN::new(self)
    end

to_d → bigdecimal click to toggle source

Returns the value of `int` as a `BigDecimal`.

    require 'bigdecimal'
    require 'bigdecimal/util'

    42.to_d   # => 0.42e2

See also `BigDecimal::new`.

    # File ext/bigdecimal/lib/bigdecimal/util.rb, line 23
    def to_d
      BigDecimal(self)
    end

to_f → float click to toggle source

Converts `int` to a `Float`. If `int` doesn't fit in a `Float`, the result is infinity.

    static VALUE
    int_to_f(VALUE num)
    {
        double val;

        if (FIXNUM_P(num)) {
            val = (double)FIX2LONG(num);
        }
        else if (RB_TYPE_P(num, T_BIGNUM)) {
            val = rb_big2dbl(num);
        }
        else {
            rb_raise(rb_eNotImpError, "Unknown subclass for to_f: %s", rb_obj_classname(num));
        }

        return DBL2NUM(val);
    }

to_i → integer click to toggle source

Since `int` is already an `Integer`, returns `self`.

`to_int` is an alias for `to_i`.

    # File integer.rb, line 130
    def to_i
      return self
    end

to_int → integer click to toggle source

Since `int` is already an `Integer`, returns `self`.

    # File integer.rb, line 138
    def to_int
      return self
    end

to_r → rational click to toggle source

Returns the value as a rational.

    1.to_r        #=> (1/1)
    (1<<64).to_r  #=> (18446744073709551616/1)

    static VALUE
    integer_to_r(VALUE self)
    {
        return rb_rational_new1(self);
    }

to_s(base=10) → string click to toggle source

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"

    static VALUE
    int_to_s(int argc, VALUE *argv, VALUE x)
    {
        int base;

        if (rb_check_arity(argc, 0, 1))
            base = NUM2INT(argv[0]);
        else
            base = 10;
        return rb_int2str(x, base);
    }

Also aliased as: inspect
truncate([ndigits]) → integer or float click to toggle source

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

    static VALUE
    int_truncate(int argc, VALUE* argv, VALUE num)
    {
        int ndigits;

        if (!rb_check_arity(argc, 0, 1)) return num;
        ndigits = NUM2INT(argv[0]);
        if (ndigits >= 0) {
            return num;
        }
        return rb_int_truncate(num, ndigits);
    }

upto(limit) {|i| block } → self click to toggle source
upto(limit) → an_enumerator

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

    static VALUE
    int_upto(VALUE from, VALUE to)
    {
        RETURN_SIZED_ENUMERATOR(from, 1, &to, int_upto_size);
        if (FIXNUM_P(from) && FIXNUM_P(to)) {
            long i, end;

            end = FIX2LONG(to);
            for (i = FIX2LONG(from); i <= end; i++) {
                rb_yield(LONG2FIX(i));
            }
        }
        else {
            VALUE i = from, c;

            while (!(c = rb_funcall(i, '>', 1, to))) {
                rb_yield(i);
                i = rb_funcall(i, '+', 1, INT2FIX(1));
            }
            ensure_cmp(c, i, to);
        }
        return from;
    }

zero? → true or false click to toggle source

Returns `true` if `int` has a zero value.

    # File integer.rb, line 146
    def zero?
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_zero_p(self)'
    end

int | other_int → integer click to toggle source

Bitwise OR.

    static VALUE
    int_or(VALUE x, VALUE y)
    {
        if (FIXNUM_P(x)) {
            return fix_or(x, y);
        }
        else if (RB_TYPE_P(x, T_BIGNUM)) {
            return rb_big_or(x, y);
        }
        return Qnil;
    }

~int → integer click to toggle source

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"

    # File integer.rb, line 22
    def ~
      Primitive.attr! 'inline'
      Primitive.cexpr! 'rb_int_comp(self)'
    end

### Private Instance Methods

miller_rabin_bases() click to toggle source

    # File lib/prime.rb, line 69
            def miller_rabin_bases
      # Miller-Rabin's complexity is O(k log^3n).
      # So we can reduce the complexity by reducing the number of bases tested.
      # Using values from https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test
      i = case
      when self < 0xffff                            then
        # For small integers, Miller Rabin can be slower
        # There is no mathematical significance to 0xffff
        return nil
    # when self < 2_047                             then 0
      when self < 1_373_653                         then 1
      when self < 9_080_191                         then 2
      when self < 25_326_001                        then 3
      when self < 3_215_031_751                     then 4
      when self < 4_759_123_141                     then 5
      when self < 1_122_004_669_633                 then 6
      when self < 2_152_302_898_747                 then 7
      when self < 3_474_749_660_383                 then 8
      when self < 341_550_071_728_321               then 9
      when self < 3_825_123_056_546_413_051         then 10
      when self < 318_665_857_834_031_151_167_461   then 11
      when self < 3_317_044_064_679_887_385_961_981 then 12
      else return nil
      end
      MILLER_RABIN_BASES[i]
    end

miller_rabin_test(bases) click to toggle source

    # File lib/prime.rb, line 96
            def miller_rabin_test(bases)
      return false if even?

      r = 0
      d = self >> 1
      while d.even?
        d >>= 1
        r += 1
      end

      self_minus_1 = self-1
      bases.each do |a|
        x = a.pow(d, self)
        next if x == 1 || x == self_minus_1 || a == self

        return false if r.times do
          x = x.pow(2, self)
          break if x == self_minus_1
        end
      end
      true
    end