Int.abs:
  short: absolute value
  description: >
    Calculates the absolute value of an integer.
  return:
    type: 'Int'
    description: >
      The absolute value of `x`.
  args:
    x:
      type: 'Int'
      description: >
        The integer whose absolute value is to be calculated.
  example: |
    assert (-10).abs() == 10

Int.choose:
  short: binomial coefficient
  description: >
    Computes the binomial coefficient of the given numbers (the equivalent of `n`
    choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() *
    (n-k).factorial())`.
  return:
    type: 'Int'
    description: >
      The binomial coefficient, equivalent to the number of ways to uniquely choose
      `k` objects from among `n` objects, ignoring order.
  args:
    n:
      type: 'Int'
      description: >
        The number of things to choose from.
    k:
      type: 'Int'
      description: >
        The number of things to be chosen.
  example: |
    assert (4).choose(2) == 6

Int.clamped:
  short: clamp an integer
  description: >
    Returns the given number clamped between two values so that it is within
    that range.
  return:
    type: 'Int'
    description: >
      The first argument clamped between the other two arguments.
  args:
    x:
      type: 'Int'
      description: >
        The integer to clamp.
    low:
      type: 'Int'
      description: >
        The lowest value the result can take.
    high:
      type: 'Int'
      description: >
        The highest value the result can take.
  example: |
    assert (2).clamped(5, 10) == 5

Int.factorial:
  short: factorial
  description: >
    Computes the factorial of an integer.
  return:
    type: 'Text'
    description: >
      The factorial of the given integer.
  args:
    n:
      type: 'Int'
      description: >
        The integer to compute the factorial of.
  example: |
    assert (10).factorial() == 3628800

Int.get_bit:
  short: check whether a bit is set
  description: >
    In the binary representation of an integer, check whether a given bit index
    is set to 1 or not.
  note: >
    For fixed-size integers, the bit index must be between 1 and the number of
    bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must
    be between 1 and `Int64.max`. Values outside this range will produce a
    runtime error.
  return:
    type: 'Bool'
    description: >
      Whether or not the given bit index is set to 1 in the binary
      representation of the integer.
  args:
    i:
      type: 'Int'
      description: >
        The integer whose bits are being inspected.
    bit_index:
      type: 'Int'
      description: >
        The index of the bit to check (1-indexed).
  example: |
    assert (6).get_bit(1) == no
    assert (6).get_bit(2) == yes
    assert (6).get_bit(3) == yes
    assert (6).get_bit(4) == no

Int.hex:
  short: convert to hexidecimal
  description: >
    Converts an integer to its hexadecimal representation.
  return:
    type: 'Text'
    description: >
      The hexadecimal string representation of the integer.
  args:
    i:
      type: 'Int'
      description: >
        The integer to be converted.
    digits:
      type: 'Int'
      default: '0'
      description: >
        The minimum number of digits in the output string.
    uppercase:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to use uppercase letters for hexadecimal digits.
    prefix:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to include a "0x" prefix.
  example: |
    assert (255).hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"

Int.is_between:
  short: test if an int is in a range
  description: >
    Determines if an integer is between two numbers (inclusive).
  return:
    type: 'Bool'
    description: >
      `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no`
  args:
    x:
      type: 'Int'
      description: >
        The integer to be checked.
    a:
      type: 'Int'
      description: >
        One end of the range to check (inclusive).
    b:
      type: 'Int'
      description: >
        The other end of the range to check (inclusive).
  example: |
    assert (7).is_between(1, 10) == yes
    assert (7).is_between(10, 1) == yes
    assert (7).is_between(100, 200) == no
    assert (7).is_between(1, 7) == yes

Int.is_prime:
  short: check if an integer is prime
  description: >
    Determines if an integer is a prime number.
  note: >
    This function is _probabilistic_. With the default arguments, the chances of
    getting an incorrect answer are astronomically small (on the order of 10^(-30)).
    See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
    for more details.
  return:
    type: 'Bool'
    description: >
      `yes` if `x` is a prime number, `no` otherwise.
  args:
    x:
      type: 'Int'
      description: >
        The integer to be checked.
    reps:
      type: 'Int'
      default: '50'
      description: >
        The number of repetitions for primality tests.
  example: |
    assert (7).is_prime() == yes
    assert (6).is_prime() == no

Int.next_prime:
  short: get the next prime
  description: >
    Finds the next prime number greater than the given integer.
  note: >
    This function is _probabilistic_, but the chances of getting an incorrect
    answer are astronomically small (on the order of 10^(-30)).
    See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
    for more details.
  return:
    type: 'Int'
    description: >
      The next prime number greater than `x`.
  args:
    x:
      type: 'Int'
      description: >
        The integer after which to find the next prime.
  example: |
    assert (11).next_prime() == 13

Int.octal:
  short: convert to octal
  description: >
    Converts an integer to its octal representation.
  return:
    type: 'Text'
    description: >
      The octal string representation of the integer.
  args:
    i:
      type: 'Int'
      description: >
        The integer to be converted.
    digits:
      type: 'Int'
      default: '0'
      description: >
        The minimum number of digits in the output string.
    prefix:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether to include a "0o" prefix.
  example: |
    assert (64).octal(digits=4, prefix=yes) == "0o0100"

Int.onward:
  short: iterate from a number onward
  description: >
    Return an iterator that counts infinitely from the starting integer (with an
    optional step size).
  return:
    type: 'Text'
    description: >
      An iterator function that counts onward from the starting integer.
  args:
    first:
      type: 'Int'
      description: >
        The starting integer.
    step:
      type: 'Int'
      default: '1'
      description: >
        The increment step size.
  example: |
    nums : &[Int] = &[]
    for i in (5).onward()
    nums.insert(i)
    stop if i == 10
    assert nums[] == [5, 6, 7, 8, 9, 10]

Int.parse:
  short: convert text to integer
  description: >
    Converts a text representation of an integer into an integer.
  return:
    type: 'Int?'
    description: >
      The integer represented by the text. If the given text contains a value outside
      of the representable range or if the entire text can't be parsed as an integer,
      `none` will be returned.
  args:
    text:
      type: 'Text'
      description: >
        The text containing the integer.
    base:
      type: 'Int?'
      default: 'none'
      description: >
        The numeric base to use when parsing the integer. If unspecified, the
        integer's base will be inferred from the text prefix. After any "+" or
        "-" sign, if the text begins with "0x", the base will be assumed to be
        16, "0o" will assume base 8, "0b" will assume base 2, otherwise the
        base will be assumed to be 10.
    remainder:
      type: '&Text?'
      default: 'none'
      description: >
        If non-none, this argument will be set to the remainder of the text after the matching part.
        If none, parsing will only succeed if the entire text matches.
  example: |
    assert Int.parse("123") == 123
    assert Int.parse("0xFF") == 255
    assert Int.parse("123xyz") == none
    remainder : Text
    assert Int.parse("123xyz", &remainder) == 123
    assert remainder == "xyz"

    # Can't parse:
    assert Int.parse("asdf") == none

    # Outside valid range:
    assert Int8.parse("9999999") == none

    # Explicitly specifying base:
    assert Int.parse("10", base=16) == 16

Int.prev_prime:
  short: get the previous prime
  description: >
    Finds the previous prime number less than the given integer.
    If there is no previous prime number (i.e. if a number less than `2` is
    provided), then the function will create a runtime error.
  note: >
    This function is _probabilistic_, but the chances of getting an incorrect
    answer are astronomically small (on the order of 10^(-30)).
    See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
    for more details.
  return:
    type: 'Int?'
    description: >
      The previous prime number less than `x`, or `none` if `x` is less than 2.
  args:
    x:
      type: 'Int'
      description: >
        The integer before which to find the previous prime.
  example: |
    assert (11).prev_prime() == 7

Int.sqrt:
  short: square root
  description: >
    Calculates the nearest square root of an integer.
  return:
    type: 'Int'
    description: >
      The integer part of the square root of `x`.
  args:
    x:
      type: 'Int'
      description: >
        The integer whose square root is to be calculated.
  example: |
    assert (16).sqrt() == 4
    assert (17).sqrt() == 4

Int.to:
  short: iterate a range of integers
  description: >
    Returns an iterator function that iterates over the range of numbers specified.
  return:
    type: 'func(->Int?)'
    description: >
      An iterator function that returns each integer in the given range (inclusive).
  args:
    first:
      type: 'Int'
      description: >
        The starting value of the range.
    last:
      type: 'Int'
      description: >
        The ending value of the range.
    step:
      type: 'Int?'
      default: 'none'
      description: >
        An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.
  example: |
    iter := (2).to(5)
    assert iter() == 2
    assert iter() == 3
    assert iter() == 4
    assert iter() == 5
    assert iter() == none

    assert [x for x in (2).to(5)] == [2, 3, 4, 5]
    assert [x for x in (5).to(2)] == [5, 4, 3, 2]
    assert [x for x in (2).to(5, step=2)] == [2, 4]