diff options
Diffstat (limited to 'api/integers.md')
| -rw-r--r-- | api/integers.md | 368 |
1 files changed, 0 insertions, 368 deletions
diff --git a/api/integers.md b/api/integers.md deleted file mode 100644 index 653322fd..00000000 --- a/api/integers.md +++ /dev/null @@ -1,368 +0,0 @@ -# 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 -``` - ---- - -## `clamped` - -**Description:** -Returns the given number clamped between two values so that it is within -that range. - -**Usage:** -```tomo -clamped(x, low, high: Int) -> Int -``` - -**Parameters:** - -- `x`: The integer to clamp. -- `low`: The lowest value the result can take. -- `high`: The highest value the result can take. - -**Returns:** -The first argument clamped between the other two arguments. - -**Example:** -```tomo ->> 2:clamped(5, 10) -= 5 -``` |