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 `low <= x and x <= high`, otherwise `no`
  args:
    x:
      type: 'Int'
      description: >
        The integer to be checked.
    low:
      type: 'Int'
      description: >
        The lower bound to check (inclusive).
    high:
      type: 'Int'
      description: >
        The upper bound to check (inclusive).
  example: |
    assert (7).is_between(1, 10) == 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.
    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

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]