=begin pod

=TITLE class Int

=SUBTITLE Integer (arbitrary-precision)

    class Int is Cool does Real { ... }

C<Int> objects store integral numbers of arbitrary size. C<Int>s are immutable.

There are two main syntax forms for C<Int> literals

    123         # Int in decimal notation
    :16<BEEF>   # Int in radix notations

Both forms allow underscores between any two digits which can serve as visual
separators, but don't carry any meaning:

    5_00000     # five Lakhs
    500_000     # five hundred thousand

=head1 Methods

=head2 routine chr

Defined as:

    multi sub    chr(Int:D ) returns Str:D
    multi method chr(Int:D:) returns Str:D

Usage:

    chr INTEGER
    INTEGER.chr

Returns a one-character string, by interpreting the integer as a Unicode
codepoint number and converting it the corresponding character.

Example:

    65.chr  # returns "A"
    196.chr # returns "Ä"

=head2 routine expmod

Defined as:

    multi sub    expmod (Int:D: Int $y, Int $mod) returns Int:D
    multi method expmod (Int:D: Int $y, Int $mod) returns Int:D

Usage:

    expmod(INTEGER, POWER, MODULUS)
    INTEGER.expmod(POWER, MODULUS)

Returns the given C<Int> raised to the C<$y> power within modulus C<$mod>.

=head2 routine is-prime

Defined as:

    multi sub    is-prime (Int:D $number) returns Bool:D
    multi method is-prime (Int:D:) returns Bool:D

Usage:

    is-prime INTEGER
    INTEGER.is-prime
    INTEGER.is-prime

Returns C<True> if this C<Int> is known to be a prime, or is likely to be a
prime based on a probabilistic Miller-Rabin test.

Returns C<False> if this C<Int> is known not to be a prime.

=head2 routine lsb

Defined as:

    multi method lsb(Int:D:)
    multi sub    lsb(Int:D)

Usage:

    lsb INTEGER
    INTEGER.lsb

Returns L<Nil|/type/Nil> if the number is 0. Otherwise returns the zero-based
index from the right of the first 1 in the binary representation of the
number.

    say 0b01011.lsb;        # 0
    say 0b01010.lsb;        # 1
    say 0b10100.lsb;        # 2
    say 0b01000.lsb;        # 3
    say 0b10000.lsb;        # 4

=head2 routine msb

Defined as:

    multi method msb(Int:D:)
    multi sub    msb(Int:D)

Usage:

    msb INTEGER
    INTEGER.msb

Returns L<Nil|/type/Nil> if the number is 0. Otherwise returns the zero-based
index from the left of the first 1 in the binary representation of the
number.

    say 0b00001.msb;        # 0
    say 0b00011.msb;        # 1
    say 0b00101.msb;        # 2
    say 0b01010.msb;        # 3
    say 0b10011.msb;        # 4

=head2 routine unival

Defined as:

    multi sub    unival(Int:D)  returns Numeric
    multi method unival(Int:D:) returns Numeric

Usage:

    unival INTEGER
    INTEGER.unival

Returns the number represented by the Unicode codepoint with the given integer
number, or L<NaN> if it does not represent a number.

=head1 Operators

=head2 infix div

    multi sub infix:<div>(Int:D, Int:D) returns Int:D

Does an integer division, rounded down.

=end pod
