code / tomo

📦 Download .tar.gz
Lines41.3K C23.7K Markdown9.7K YAML5.0K Tomo2.3K
7 others 763
Python231 Shell230 make212 INI47 Text21 SVG16 Lua6
(343 lines)
Rendered Source
Raw

% API

Builtins

Int

Int.abs

Int.abs : func(x: Int -> Int)

Calculates the absolute value of an integer.

Argument Type Description Default
x Int The integer whose absolute value is to be calculated. -

Return: The absolute value of x.

Example:

assert (-10).abs() == 10

Int.choose

Int.choose : func(n: Int, k: Int -> Int)

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()).

Argument Type Description Default
n Int The number of things to choose from. -
k Int The number of things to be chosen. -

Return: The binomial coefficient, equivalent to the number of ways to uniquely choose k objects from among n objects, ignoring order.

Example:

assert 4.choose(2) == 6

Int.clamped

Int.clamped : func(x: Int, low: Int, high: Int -> Int)

Returns the given number clamped between two values so that it is within that range.

Argument Type Description Default
x Int The integer to clamp. -
low Int The lowest value the result can take. -
high Int The highest value the result can take. -

Return: The first argument clamped between the other two arguments.

Example:

assert 2.clamped(5, 10) == 5

Int.factorial

Int.factorial : func(n: Int -> Text)

Computes the factorial of an integer.

Argument Type Description Default
n Int The integer to compute the factorial of. -

Return: The factorial of the given integer.

Example:

assert 10.factorial() == 3628800

Int.get_bit

Int.get_bit : func(i: Int, bit_index: Int -> Bool)

In the binary representation of an integer, check whether a given bit index is set to 1 or not.

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.

Argument Type Description Default
i Int The integer whose bits are being inspected. -
bit_index Int The index of the bit to check (1-indexed). -

Return: Whether or not the given bit index is set to 1 in the binary representation of the integer.

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

Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)

Converts an integer to its hexadecimal representation.

Argument Type Description Default
i Int The integer to be converted. -
digits Int The minimum number of digits in the output string. 0
uppercase Bool Whether to use uppercase letters for hexadecimal digits. yes
prefix Bool Whether to include a "0x" prefix. yes

Return: The hexadecimal string representation of the integer.

Example:

assert 255.hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"

Int.is_between

Int.is_between : func(x: Int, a: Int, b: Int -> Bool)

Determines if an integer is between two numbers (inclusive).

Argument Type Description Default
x Int The integer to be checked. -
a Int One end of the range to check (inclusive). -
b Int The other end of the range to check (inclusive). -

Return: yes if a <= x and x <= b or a >= x and x >= b, otherwise no

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

Int.is_prime : func(x: Int, reps: Int = 50 -> Bool)

Determines if an integer is a prime number.

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 for more details.

Argument Type Description Default
x Int The integer to be checked. -
reps Int The number of repetitions for primality tests. 50

Return: yes if x is a prime number, no otherwise.

Example:

assert 7.is_prime() == yes
assert 6.is_prime() == no

Int.next_prime

Int.next_prime : func(x: Int -> Int)

Finds the next prime number greater than the given integer.

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 for more details.

Argument Type Description Default
x Int The integer after which to find the next prime. -

Return: The next prime number greater than x.

Example:

assert 11.next_prime() == 13

Int.octal

Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)

Converts an integer to its octal representation.

Argument Type Description Default
i Int The integer to be converted. -
digits Int The minimum number of digits in the output string. 0
prefix Bool Whether to include a "0o" prefix. yes

Return: The octal string representation of the integer.

Example:

assert 64.octal(digits=4, prefix=yes) == "0o0100"

Int.onward

Int.onward : func(first: Int, step: Int = 1 -> Text)

Return an iterator that counts infinitely from the starting integer (with an optional step size).

Argument Type Description Default
first Int The starting integer. -
step Int The increment step size. 1

Return: An iterator function that counts onward from the starting integer.

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

Int.parse : func(text: Text, base: Int? = none, remainder: &Text? = none -> Int?)

Converts a text representation of an integer into an integer.

Argument Type Description Default
text Text The text containing the integer. -
base Int? 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. none
remainder &Text? 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. none

Return: 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.

Example:

assert Int.parse("123") == 123
assert Int.parse("0xFF") == 255
assert Int.parse("123xyz") == none
remainder : Text
assert Int.parse("123xyz", remainder=&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.sqrt

Int.sqrt : func(x: Int -> Int)

Calculates the nearest square root of an integer.

Argument Type Description Default
x Int The integer whose square root is to be calculated. -

Return: The integer part of the square root of x.

Example:

assert 16.sqrt() == 4
assert 17.sqrt() == 4

Int.to

Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?))

Returns an iterator function that iterates over the range of numbers specified.

Argument Type Description Default
first Int The starting value of the range. -
last Int The ending value of the range. -
step Int? An optional step size to use. If unspecified or none, the step will be inferred to be +1 if last >= first, otherwise -1. none

Return: An iterator function that returns each integer in the given range (inclusive).

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]


   1 % API

   3 # Builtins

   5 # Int

   6 ## Int.abs

   8 ```tomo

   9 Int.abs : func(x: Int -> Int)

  10 ```

  12 Calculates the absolute value of an integer.

  14 Argument | Type | Description | Default

  15 ---------|------|-------------|---------

  16 x | `Int` | The integer whose absolute value is to be calculated.  | -

  18 **Return:** The absolute value of `x`.

  21 **Example:**

  22 ```tomo

  23 assert (-10).abs() == 10

  25 ```

  26 ## Int.choose

  28 ```tomo

  29 Int.choose : func(n: Int, k: Int -> Int)

  30 ```

  32 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())`.

  34 Argument | Type | Description | Default

  35 ---------|------|-------------|---------

  36 n | `Int` | The number of things to choose from.  | -

  37 k | `Int` | The number of things to be chosen.  | -

  39 **Return:** The binomial coefficient, equivalent to the number of ways to uniquely choose `k` objects from among `n` objects, ignoring order.

  42 **Example:**

  43 ```tomo

  44 assert 4.choose(2) == 6

  46 ```

  47 ## Int.clamped

  49 ```tomo

  50 Int.clamped : func(x: Int, low: Int, high: Int -> Int)

  51 ```

  53 Returns the given number clamped between two values so that it is within that range.

  55 Argument | Type | Description | Default

  56 ---------|------|-------------|---------

  57 x | `Int` | The integer to clamp.  | -

  58 low | `Int` | The lowest value the result can take.  | -

  59 high | `Int` | The highest value the result can take.  | -

  61 **Return:** The first argument clamped between the other two arguments.

  64 **Example:**

  65 ```tomo

  66 assert 2.clamped(5, 10) == 5

  68 ```

  69 ## Int.factorial

  71 ```tomo

  72 Int.factorial : func(n: Int -> Text)

  73 ```

  75 Computes the factorial of an integer.

  77 Argument | Type | Description | Default

  78 ---------|------|-------------|---------

  79 n | `Int` | The integer to compute the factorial of.  | -

  81 **Return:** The factorial of the given integer.

  84 **Example:**

  85 ```tomo

  86 assert 10.factorial() == 3628800

  88 ```

  89 ## Int.get_bit

  91 ```tomo

  92 Int.get_bit : func(i: Int, bit_index: Int -> Bool)

  93 ```

  95 In the binary representation of an integer, check whether a given bit index is set to 1 or not.

  97 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.

  99 Argument | Type | Description | Default

 100 ---------|------|-------------|---------

 101 i | `Int` | The integer whose bits are being inspected.  | -

 102 bit_index | `Int` | The index of the bit to check (1-indexed).  | -

 104 **Return:** Whether or not the given bit index is set to 1 in the binary representation of the integer.

 107 **Example:**

 108 ```tomo

 109 assert 6.get_bit(1) == no

 110 assert 6.get_bit(2) == yes

 111 assert 6.get_bit(3) == yes

 112 assert 6.get_bit(4) == no

 114 ```

 115 ## Int.hex

 117 ```tomo

 118 Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)

 119 ```

 121 Converts an integer to its hexadecimal representation.

 123 Argument | Type | Description | Default

 124 ---------|------|-------------|---------

 125 i | `Int` | The integer to be converted.  | -

 126 digits | `Int` | The minimum number of digits in the output string.  | `0`

 127 uppercase | `Bool` | Whether to use uppercase letters for hexadecimal digits.  | `yes`

 128 prefix | `Bool` | Whether to include a "0x" prefix.  | `yes`

 130 **Return:** The hexadecimal string representation of the integer.

 133 **Example:**

 134 ```tomo

 135 assert 255.hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"

 137 ```

 138 ## Int.is_between

 140 ```tomo

 141 Int.is_between : func(x: Int, a: Int, b: Int -> Bool)

 142 ```

 144 Determines if an integer is between two numbers (inclusive).

 146 Argument | Type | Description | Default

 147 ---------|------|-------------|---------

 148 x | `Int` | The integer to be checked.  | -

 149 a | `Int` | One end of the range to check (inclusive).  | -

 150 b | `Int` | The other end of the range to check (inclusive).  | -

 152 **Return:** `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no`

 155 **Example:**

 156 ```tomo

 157 assert 7.is_between(1, 10) == yes

 158 assert 7.is_between(10, 1) == yes

 159 assert 7.is_between(100, 200) == no

 160 assert 7.is_between(1, 7) == yes

 162 ```

 163 ## Int.is_prime

 165 ```tomo

 166 Int.is_prime : func(x: Int, reps: Int = 50 -> Bool)

 167 ```

 169 Determines if an integer is a prime number.

 171 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.

 173 Argument | Type | Description | Default

 174 ---------|------|-------------|---------

 175 x | `Int` | The integer to be checked.  | -

 176 reps | `Int` | The number of repetitions for primality tests.  | `50`

 178 **Return:** `yes` if `x` is a prime number, `no` otherwise.

 181 **Example:**

 182 ```tomo

 183 assert 7.is_prime() == yes

 184 assert 6.is_prime() == no

 186 ```

 187 ## Int.next_prime

 189 ```tomo

 190 Int.next_prime : func(x: Int -> Int)

 191 ```

 193 Finds the next prime number greater than the given integer.

 195 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.

 197 Argument | Type | Description | Default

 198 ---------|------|-------------|---------

 199 x | `Int` | The integer after which to find the next prime.  | -

 201 **Return:** The next prime number greater than `x`.

 204 **Example:**

 205 ```tomo

 206 assert 11.next_prime() == 13

 208 ```

 209 ## Int.octal

 211 ```tomo

 212 Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)

 213 ```

 215 Converts an integer to its octal representation.

 217 Argument | Type | Description | Default

 218 ---------|------|-------------|---------

 219 i | `Int` | The integer to be converted.  | -

 220 digits | `Int` | The minimum number of digits in the output string.  | `0`

 221 prefix | `Bool` | Whether to include a "0o" prefix.  | `yes`

 223 **Return:** The octal string representation of the integer.

 226 **Example:**

 227 ```tomo

 228 assert 64.octal(digits=4, prefix=yes) == "0o0100"

 230 ```

 231 ## Int.onward

 233 ```tomo

 234 Int.onward : func(first: Int, step: Int = 1 -> Text)

 235 ```

 237 Return an iterator that counts infinitely from the starting integer (with an optional step size).

 239 Argument | Type | Description | Default

 240 ---------|------|-------------|---------

 241 first | `Int` | The starting integer.  | -

 242 step | `Int` | The increment step size.  | `1`

 244 **Return:** An iterator function that counts onward from the starting integer.

 247 **Example:**

 248 ```tomo

 249 nums : &[Int] = &[]

 250 for i in 5.onward()

 251     nums.insert(i)

 252     stop if i == 10

 253 assert nums[] == [5, 6, 7, 8, 9, 10]

 255 ```

 256 ## Int.parse

 258 ```tomo

 259 Int.parse : func(text: Text, base: Int? = none, remainder: &Text? = none -> Int?)

 260 ```

 262 Converts a text representation of an integer into an integer.

 264 Argument | Type | Description | Default

 265 ---------|------|-------------|---------

 266 text | `Text` | The text containing the integer.  | -

 267 base | `Int?` | 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.  | `none`

 268 remainder | `&Text?` | 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.  | `none`

 270 **Return:** 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.

 273 **Example:**

 274 ```tomo

 275 assert Int.parse("123") == 123

 276 assert Int.parse("0xFF") == 255

 277 assert Int.parse("123xyz") == none

 278 remainder : Text

 279 assert Int.parse("123xyz", remainder=&remainder) == 123

 280 assert remainder == "xyz"

 282 # Can't parse:

 283 assert Int.parse("asdf") == none

 285 # Outside valid range:

 286 assert Int8.parse("9999999") == none

 288 # Explicitly specifying base:

 289 assert Int.parse("10", base=16) == 16

 291 ```

 292 ## Int.sqrt

 294 ```tomo

 295 Int.sqrt : func(x: Int -> Int)

 296 ```

 298 Calculates the nearest square root of an integer.

 300 Argument | Type | Description | Default

 301 ---------|------|-------------|---------

 302 x | `Int` | The integer whose square root is to be calculated.  | -

 304 **Return:** The integer part of the square root of `x`.

 307 **Example:**

 308 ```tomo

 309 assert 16.sqrt() == 4

 310 assert 17.sqrt() == 4

 312 ```

 313 ## Int.to

 315 ```tomo

 316 Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?))

 317 ```

 319 Returns an iterator function that iterates over the range of numbers specified.

 321 Argument | Type | Description | Default

 322 ---------|------|-------------|---------

 323 first | `Int` | The starting value of the range.  | -

 324 last | `Int` | The ending value of the range.  | -

 325 step | `Int?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.  | `none`

 327 **Return:** An iterator function that returns each integer in the given range (inclusive).

 330 **Example:**

 331 ```tomo

 332 iter := 2.to(5)

 333 assert iter() == 2

 334 assert iter() == 3

 335 assert iter() == 4

 336 assert iter() == 5

 337 assert iter() == none

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

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

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

 343 ```