Add API docs

1 files changed, 338 insertions, 0 deletions

diff --git a/api/integers.md b/api/integers.md
new file mode 100644
index 00000000..acbab60c
--- /dev/null
+++ b/api/integers.md
@@ -0,0 +1,338 @@
+# Integers
+
+Tomo has five types of integers:
+
+- `Int`: the default integer type, which uses an efficient tagged 29-bit
+  integer value for small numbers, and falls back to a bigint implementation
+  when values are too large to fit in 29-bits. The bigint implementation uses
+  the GNU MP library. These integers are fast for small numbers and guaranteed
+  to always be correct and never overflow.
+- `Int8`/`Int16`/`Int32`/`Int64`: Fixed-size integers that take up `N` bits.
+  These integers must be manually specified with their suffix (e.g. `5_i64`)
+  and are subject to overflowing. If an overflow occurs, a runtime error will
+  be raised.
+
+Conversion between integer types can be done by calling the target type as a
+function: `Int32(x)`. For fixed-width types, the conversion function also
+accepts a second parameter, `truncate`. If `truncate` is `no` (the default),
+conversion will create a runtime error if the value is too large to fit in the
+target type. If `truncate` is `yes`, then the resulting value will be a
+truncated form of the input value.
+
+Integers support the standard math operations (`x+y`, `x-y`, `x*y`, `x/y`) as
+well as powers/exponentiation (`x^y`), modulus (`x mod y` and `x mod1 y`), and
+bitwise operations: `x and y`, `x or y`, `x xor y`, `x << y`, and `x >> y`. The
+operators `and`, `or`, and `xor` are _bitwise_, not logical operators.
+
+# Integer Functions
+
+Each integer type has its own version of the following functions. Functions
+can be called either on the type itself: `Int.sqrt(x)` or as a method call:
+`x:sqrt()`. Method call syntax is preferred.
+
+## `format`
+
+**Description:**  
+Formats an integer as a string with a specified number of digits.
+
+**Usage:**  
+```tomo
+format(i: Int, digits: Int = 0) -> Text
+```
+
+**Parameters:**
+
+- `i`: The integer to be formatted.
+- `digits`: The minimum number of digits to which the integer should be padded. Default is `0`.
+
+**Returns:**  
+A string representation of the integer, padded to the specified number of digits.
+
+**Example:**  
+```tomo
+>> 42:format(digits=5)
+= "00042"
+```
+
+---
+
+## `hex`
+
+**Description:**  
+Converts an integer to its hexadecimal representation.
+
+**Usage:**  
+```tomo
+hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes) -> Text
+```
+
+**Parameters:**
+
+- `i`: The integer to be converted.
+- `digits`: The minimum number of digits in the output string. Default is `0`.
+- `uppercase`: Whether to use uppercase letters for hexadecimal digits. Default is `yes`.
+- `prefix`: Whether to include a "0x" prefix. Default is `yes`.
+
+**Returns:**  
+The hexadecimal string representation of the integer.
+
+**Example:**  
+```tomo
+>> 255:hex(digits=4, uppercase=yes, prefix=yes)
+= "0x00FF"
+```
+
+---
+
+## `octal`
+
+**Description:**  
+Converts an integer to its octal representation.
+
+**Usage:**  
+```tomo
+octal(i: Int, digits: Int = 0, prefix: Bool = yes) -> Text
+```
+
+**Parameters:**
+
+- `i`: The integer to be converted.
+- `digits`: The minimum number of digits in the output string. Default is `0`.
+- `prefix`: Whether to include a "0o" prefix. Default is `yes`.
+
+**Returns:**  
+The octal string representation of the integer.
+
+**Example:**  
+```tomo
+>> 64:octal(digits=4, prefix=yes)
+= "0o0100"
+```
+
+---
+
+## `random`
+
+**Description:**  
+Generates a random integer between the specified minimum and maximum values.
+
+**Usage:**  
+```tomo
+random(min: Int, max: Int) -> Int
+```
+
+**Parameters:**
+
+- `min`: The minimum value of the range.
+- `max`: The maximum value of the range.
+
+**Returns:**  
+A random integer between `min` and `max` (inclusive).
+
+**Example:**  
+```tomo
+>> Int.random(1, 100)
+= 47
+```
+
+---
+
+## `from_text`
+
+**Description:**  
+Converts a text representation of an integer into an integer.
+
+**Usage:**  
+```tomo
+from_text(text: Text, the_rest: Text = "!&Text") -> Int
+```
+
+**Parameters:**
+
+- `text`: The string containing the integer.
+- `the_rest`: If non-null, this pointer will be set to point to any unparseable text after the integer.
+
+**Returns:**  
+The integer represented by the string.
+
+**Example:**  
+```tomo
+>> from_text("123")
+= 123
+>> from_text("0xFF")
+= 255
+```
+
+---
+
+## `to`
+
+**Description:**  
+Creates an inclusive range of integers between the specified start and end values.
+
+**Usage:**  
+```tomo
+to(from: Int, to: Int) -> Range
+```
+
+**Parameters:**
+
+- `from`: The starting value of the range.
+- `to`: The ending value of the range.
+
+**Returns:**  
+A range object representing all integers from `from` to `to` (inclusive).
+
+**Example:**  
+```tomo
+>> 1:to(5)
+= Range(first=1, last=5, step=1)
+```
+
+---
+
+## `abs`
+
+**Description:**  
+Calculates the absolute value of an integer.
+
+**Usage:**  
+```tomo
+abs(x: Int) -> Int
+```
+
+**Parameters:**
+
+- `x`: The integer whose absolute value is to be calculated.
+
+**Returns:**  
+The absolute value of `x`.
+
+**Example:**  
+```tomo
+>> -10:abs()
+= 10
+```
+
+---
+
+## `sqrt`
+
+**Description:**  
+Calculates the square root of an integer. 
+
+**Usage:**  
+```tomo
+sqrt(x: Int) -> Int
+```
+
+**Parameters:**
+
+- `x`: The integer whose square root is to be calculated.
+
+**Returns:**  
+The integer part of the square root of `x`.
+
+**Example:**  
+```tomo
+>> 16:sqrt()
+= 4
+>> 17:sqrt()
+= 4
+```
+
+---
+
+## `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.
+
+**Usage:**  
+```tomo
+is_prime(x: Int, reps: Int = 50) -> Bool
+```
+
+**Parameters:**
+
+- `x`: The integer to be checked.
+- `reps`: The number of repetitions for primality tests. Default is `50`.
+
+**Returns:**  
+`yes` if `x` is a prime number, `no` otherwise.
+
+**Example:**  
+```tomo
+>> 7:is_prime()
+= yes
+>> 6:is_prime()
+= no
+```
+
+---
+
+## `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.
+
+**Usage:**  
+```tomo
+next_prime(x: Int) -> Int
+```
+
+**Parameters:**
+
+- `x`: The integer after which to find the next prime.
+
+**Returns:**  
+The next prime number greater than `x`.
+
+**Example:**  
+```tomo
+11:next_prime()  // 13
+```
+
+---
+
+## `prev_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.
+
+**Usage:**  
+```tomo
+prev_prime(x: Int) -> Int
+```
+
+**Parameters:**
+
+- `x`: The integer before which to find the previous prime.
+
+**Returns:**  
+The previous prime number less than `x`.
+
+**Example:**  
+```tomo
+11:prev_prime()  // 7
+```