Bruce/tomo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity

Alphabetize and index functions

Browse Source
This commit is contained in:
Bruce Hill 2025-03-05 00:21:30 -05:00
parent 665050940f
commit 0a3ad8ba91
13 changed files with 882 additions and 670 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/arrays.md
View File

@ -232,6 +232,33 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
## Array Methods
- [`func binary_search(arr: [T], by: func(x,y:&T->Int32) = T.compare -> Int)`](#`binary_search)
- [`func by(arr: [T], step: Int -> [T])`](#`by)
- [`func clear(arr: @[T] -> Void)`](#`clear)
- [`func counts(arr: [T] -> {T,Int})`](#`counts)
- [`func find(arr: [T], target: T -> Int?)`](#`find)
- [`func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)`](#`first)
- [`func from(arr: [T], first: Int -> [T])`](#`from)
- [`func has(arr: [T] -> Bool)`](#`has)
- [`func heap_pop(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)`](#`heap_pop)
- [`func heap_push(arr: @[T], item: T, by=T.compare -> Void)`](#`heap_push)
- [`func heapify(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)`](#`heapify)
- [`func insert(arr: @[T], item: T, at: Int = 0 -> Void)`](#`insert)
- [`func insert_all(arr: @[T], items: [T], at: Int = 0 -> Void)`](#`insert_all)
- [`func pop(arr: &[T], index: Int = -1 -> T?)`](#`pop)
- [`func random(arr: [T], rng: RNG = random -> T)`](#`random)
- [`func remove_at(arr: @[T], at: Int = -1, count: Int = 1 -> Void)`](#`remove_at)
- [`func remove_item(arr: @[T], item: T, max_count: Int = -1 -> Void)`](#`remove_item)
- [`func reversed(arr: [T] -> [T])`](#`reversed)
- [`func sample(arr: [T], count: Int, weights: [Num]? = ![Num], rng: RNG = random -> [T])`](#`sample)
- [`func shuffle(arr: @[T], rng: RNG = random -> Void)`](#`shuffle)
- [`func shuffled(arr: [T], rng: RNG = random -> [T])`](#`shuffled)
- [`func slice(arr: [T], from: Int, to: Int -> [T])`](#`slice)
- [`func sort(arr: @[T], by=T.compare -> Void)`](#`sort)
- [`sorted(arr: [T], by=T.compare -> [T])`](#`sorted)
- [`to(arr: [T], last: Int -> [T])`](#`to)
- [`unique(arr: [T] -> {T})`](#`unique)
### `binary_search`
**Description:**

2
docs/booleans.md
View File

@ -7,6 +7,8 @@ Boolean values have the type `Bool` and can be either `yes` ("true") or `no`
This documentation provides details on boolean functions available in the API.
- [`func parse(text: Text -> Bool?)`](#`parse)
### `parse`
**Description:**

339
docs/integers.md
View File

@ -122,6 +122,46 @@ 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.
- [`func abs(x: Int -> Int)`](#`abs)
- [`func choose(n: Int, k: Int -> Int)`](#`choose)
- [`func clamped(x, low, high: Int -> Int)`](#`clamped)
- [`func factorial(n: Int -> Text)`](#`factorial)
- [`func format(i: Int, digits: Int = 0 -> Text)`](#`format)
- [`func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)`](#`hex)
- [`func is_prime(x: Int, reps: Int = 50 -> Bool)`](#`is_prime)
- [`func next_prime(x: Int -> Int)`](#`next_prime)
- [`func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)`](#`octal)
- [`func onward(first: Int, step: Int = 1 -> Text)`](#`onward)
- [`func parse(text: Text -> Int?)`](#`parse)
- [`func prev_prime(x: Int -> Int)`](#`prev_prime)
- [`func sqrt(x: Int -> Int)`](#`sqrt)
- [`func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))`](#`to)
### `abs`
**Description:**
Calculates the absolute value of an integer.
**Signature:**
```tomo
func 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
```
---
### `choose`
**Description:**
@ -151,6 +191,34 @@ The binomial coefficient, equivalent to the number of ways to uniquely choose
---
### `clamped`
**Description:**
Returns the given number clamped between two values so that it is within
that range.
**Signature:**
```tomo
func 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
```
---
### `factorial`
**Description:**
@ -230,6 +298,71 @@ The hexadecimal string representation of the 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.
**Signature:**
```tomo
func 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.
**Signature:**
```tomo
func 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
```
---
### `octal`
**Description:**
@ -325,158 +458,6 @@ of the representable range or if the entire text can't be parsed as an integer,
---
### `to`
**Description:**
Returns an iterator function that iterates over the range of numbers specified.
Iteration is assumed to be nonempty and
**Signature:**
```tomo
func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))
```
**Parameters:**
- `first`: The starting value of the range.
- `last`: The ending value of the range.
- `step`: An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.
**Returns:**
An iterator function that returns each integer in the given range (inclusive).
**Example:**
```tomo
>> 2:to(5)
= func(->Int?)
>> [x for x in 2:to(5)]
= [2, 3, 4, 5]
>> [x for x in 5:to(2)]
= [5, 4, 3, 2]
>> [x for x in 2:to(5, step=2)]
= [2, 4]
```
---
### `abs`
**Description:**
Calculates the absolute value of an integer.
**Signature:**
```tomo
func 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.
**Signature:**
```tomo
func 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.
**Signature:**
```tomo
func 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.
**Signature:**
```tomo
func 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:**
@ -510,28 +491,62 @@ The previous prime number less than `x`.
---
### `clamped`
### `sqrt`
**Description:**
Returns the given number clamped between two values so that it is within
that range.
Calculates the square root of an integer.
**Signature:**
```tomo
func clamped(x, low, high: Int -> Int)
func sqrt(x: Int -> Int)
```
**Parameters:**
- `x`: The integer to clamp.
- `low`: The lowest value the result can take.
- `high`: The highest value the result can take.
- `x`: The integer whose square root is to be calculated.
**Returns:**
The first argument clamped between the other two arguments.
The integer part of the square root of `x`.
**Example:**
```tomo
>> 2:clamped(5, 10)
= 5
>> 16:sqrt()
= 4
>> 17:sqrt()
= 4
```
---
### `to`
**Description:**
Returns an iterator function that iterates over the range of numbers specified.
Iteration is assumed to be nonempty and
**Signature:**
```tomo
func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))
```
**Parameters:**
- `first`: The starting value of the range.
- `last`: The ending value of the range.
- `step`: An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.
**Returns:**
An iterator function that returns each integer in the given range (inclusive).
**Example:**
```tomo
>> 2:to(5)
= func(->Int?)
>> [x for x in 2:to(5)]
= [2, 3, 4, 5]
>> [x for x in 5:to(2)]
= [5, 4, 3, 2]
>> [x for x in 2:to(5, step=2)]
= [2, 4]
```

24
docs/moments.md
View File

@ -63,6 +63,30 @@ Time zones are specified by name, such as `America/New_York` or `UTC`.
## Moment Methods
- [`func after(moment: Moment, seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> Moment)`](#`after)
- [`func date(moment: Moment, timezone : Text? = !Text -> Text)`](#`date)
- [`func day_of_month(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_month)
- [`func day_of_week(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_week)
- [`func day_of_year(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_year)
- [`func format(moment: Moment, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)`](#`format)
- [`func from_unix_timestamp(timestamp: Int64 -> Moment)`](#`from_unix_timestamp)
- [`func get_local_timezone(->Text)`](#`get_local_timezone)
- [`func hour(moment: Moment, timezone : Text? = !Text -> Int)`](#`hour)
- [`func hours_till(moment: Moment, then:Moment -> Num)`](#`hours_till)
- [`func minute(moment: Moment, timezone : Text? = !Text -> Int)`](#`minute)
- [`func minutes_till(moment: Moment, then:Moment -> Num)`](#`minutes_till)
- [`func month(moment: Moment, timezone : Text? = !Text -> Int)`](#`month)
- [`func nanosecond(moment: Moment, timezone : Text? = !Text -> Int)`](#`nanosecond)
- [`func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> Moment)`](#`new)
- [`func now(->Moment)`](#`now)
- [`func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> Moment?)`](#`parse)
- [`func relative(moment: Moment, relative_to : Moment = Moment.now(), timezone : Text? = !Text -> Text)`](#`relative)
- [`func second(moment: Moment, timezone : Text? = !Text -> Int)`](#`second)
- [`func seconds_till(moment: Moment, then:Moment -> Num)`](#`seconds_till)
- [`func set_local_timezone(timezone : Text? = !Text -> Void)`](#`set_local_timezone)
- [`func time(moment: Moment, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)`](#`time)
- [`func unix_timestamp(moment:Moment->Int64)`](#`unix_timestamp)
### `after`
**Description:**

312
docs/nums.md
View File

@ -119,6 +119,56 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
---
- [`func abs(n: Num -> Num)`](#`abs)
- [`func acos(x: Num -> Num)`](#`acos)
- [`func acosh(x: Num -> Num)`](#`acosh)
- [`func asin(x: Num -> Num)`](#`asin)
- [`func asinh(x: Num -> Num)`](#`asinh)
- [`func atan(x: Num -> Num)`](#`atan)
- [`func atan2(x: Num, y: Num -> Num)`](#`atan2)
- [`func atanh(x: Num -> Num)`](#`atanh)
- [`func cbrt(x: Num -> Num)`](#`cbrt)
- [`func ceil(x: Num -> Num)`](#`ceil)
- [`clamped(x, low, high: Num -> Num)`](#`clamped)
- [`func copysign(x: Num, y: Num -> Num)`](#`copysign)
- [`func cos(x: Num -> Num)`](#`cos)
- [`func cosh(x: Num -> Num)`](#`cosh)
- [`func erf(x: Num -> Num)`](#`erf)
- [`func erfc(x: Num -> Num)`](#`erfc)
- [`func exp(x: Num -> Num)`](#`exp)
- [`func exp2(x: Num -> Num)`](#`exp2)
- [`func expm1(x: Num -> Num)`](#`expm1)
- [`func fdim(x: Num, y: Num -> Num)`](#`fdim)
- [`func floor(x: Num -> Num)`](#`floor)
- [`func format(n: Num, precision: Int = 0 -> Text)`](#`format)
- [`func hypot(x: Num, y: Num -> Num)`](#`hypot)
- [`func isfinite(n: Num -> Bool)`](#`isfinite)
- [`func isinf(n: Num -> Bool)`](#`isinf)
- [`func j0(x: Num -> Num)`](#`j0)
- [`func j1(x: Num -> Num)`](#`j1)
- [`func log(x: Num -> Num)`](#`log)
- [`func log10(x: Num -> Num)`](#`log10)
- [`func log1p(x: Num -> Num)`](#`log1p)
- [`func log2(x: Num -> Num)`](#`log2)
- [`func logb(x: Num -> Num)`](#`logb)
- [`func mix(amount: Num, x: Num, y: Num -> Num)`](#`mix)
- [`func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)`](#`near)
- [`func nextafter(x: Num, y: Num -> Num)`](#`nextafter)
- [`func parse(text: Text -> Num?)`](#`parse)
- [`func rint(x: Num -> Num)`](#`rint)
- [`func round(x: Num -> Num)`](#`round)
- [`func scientific(n: Num, precision: Int = 0 -> Text)`](#`scientific)
- [`func significand(x: Num -> Num)`](#`significand)
- [`func sin(x: Num -> Num)`](#`sin)
- [`func sinh(x: Num -> Num)`](#`sinh)
- [`func sqrt(x: Num -> Num)`](#`sqrt)
- [`func tan(x: Num -> Num)`](#`tan)
- [`func tanh(x: Num -> Num)`](#`tanh)
- [`func tgamma(x: Num -> Num)`](#`tgamma)
- [`func trunc(x: Num -> Num)`](#`trunc)
- [`func y0(x: Num -> Num)`](#`y0)
- [`func y1(x: Num -> Num)`](#`y1)
### `abs`
**Description:**
@ -244,6 +294,31 @@ The inverse hyperbolic sine of `x`.
---
### `atan`
**Description:**
Computes the arc tangent of a number.
**Signature:**
```tomo
func atan(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the arc tangent is to be calculated.
**Returns:**
The arc tangent of `x` in radians.
**Example:**
```tomo
>> 1.0:atan() // -> (π/4)
= 0.7854
```
---
### `atan2`
**Description:**
@ -270,31 +345,6 @@ The arc tangent of `x/y` in radians.
---
### `atan`
**Description:**
Computes the arc tangent of a number.
**Signature:**
```tomo
func atan(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the arc tangent is to be calculated.
**Returns:**
The arc tangent of `x` in radians.
**Example:**
```tomo
>> 1.0:atan() // -> (π/4)
= 0.7854
```
---
### `atanh`
**Description:**
@ -370,6 +420,34 @@ The smallest integer greater than or equal to `x`.
---
### `clamped`
**Description:**
Returns the given number clamped between two values so that it is within
that range.
**Signature:**
```tomo
clamped(x, low, high: Num -> Num)
```
**Parameters:**
- `x`: The number 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.5:clamped(5.5, 10.5)
= 5.5
```
---
### `copysign`
**Description:**
@ -496,31 +574,6 @@ The complementary error function of `x`.
---
### `exp2`
**Description:**
Computes \( 2^x \) for a number.
**Signature:**
```tomo
func exp2(x: Num -> Num)
```
**Parameters:**
- `x`: The exponent.
**Returns:**
The value of \( 2^x \).
**Example:**
```tomo
>> 3.0:exp2()
= 8
```
---
### `exp`
**Description:**
@ -546,6 +599,31 @@ The value of \( e^x \).
---
### `exp2`
**Description:**
Computes \( 2^x \) for a number.
**Signature:**
```tomo
func exp2(x: Num -> Num)
```
**Parameters:**
- `x`: The exponent.
**Returns:**
The value of \( 2^x \).
**Example:**
```tomo
>> 3.0:exp2()
= 8
```
---
### `expm1`
**Description:**
@ -650,34 +728,6 @@ A text representation of the number with the specified precision.
---
### `parse`
**Description:**
Converts a text representation of a number into a floating-point number.
**Signature:**
```tomo
func parse(text: Text -> Num?)
```
**Parameters:**
- `text`: The text containing the number.
**Returns:**
The number represented by the text or `none` if the entire text can't be parsed
as a number.
**Example:**
```tomo
>> Num.parse("3.14")
= 3.14
>> Num.parse("1e3")
= 1000
```
---
### `hypot`
**Description:**
@ -808,6 +858,31 @@ The Bessel function of the first kind of order 1 of `x`.
---
### `log`
**Description:**
Computes the natural logarithm (base \( e \)) of a number.
**Signature:**
```tomo
func log(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the natural logarithm is to be calculated.
**Returns:**
The natural logarithm of `x`.
**Example:**
```tomo
>> Num.E:log()
= 1
```
---
### `log10`
**Description:**
@ -883,31 +958,6 @@ The base-2 logarithm of `x`.
---
### `log`
**Description:**
Computes the natural logarithm (base \( e \)) of a number.
**Signature:**
```tomo
func log(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the natural logarithm is to be calculated.
**Returns:**
The natural logarithm of `x`.
**Example:**
```tomo
>> Num.E:log()
= 1
```
---
### `logb`
**Description:**
@ -1024,6 +1074,34 @@ The next representable value after `x` in the direction of `y`.
---
### `parse`
**Description:**
Converts a text representation of a number into a floating-point number.
**Signature:**
```tomo
func parse(text: Text -> Num?)
```
**Parameters:**
- `text`: The text containing the number.
**Returns:**
The number represented by the text or `none` if the entire text can't be parsed
as a number.
**Example:**
```tomo
>> Num.parse("3.14")
= 3.14
>> Num.parse("1e3")
= 1000
```
---
### `rint`
**Description:**
@ -1353,31 +1431,3 @@ The Bessel function of the second kind of order 1 of `x`.
>> 1.0:y1()
= 0.4401
```
---
### `clamped`
**Description:**
Returns the given number clamped between two values so that it is within
that range.
**Signature:**
```tomo
clamped(x, low, high: Num -> Num)
```
**Parameters:**
- `x`: The number 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.5:clamped(5.5, 10.5)
= 5.5
```

27
docs/paths.md
View File

@ -37,6 +37,33 @@ intended. Paths can be created from text with slashes using
## Path Methods
- [`func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)`](#`append)
- [`func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)`](#`append_bytes)
- [`func base_name(path: Path -> Text)`](#`base_name)
- [`func by_line(path: Path -> func(->Text?)?)`](#`by_line)
- [`func children(path: Path, include_hidden=no -> [Path])`](#`children)
- [`func create_directory(path: Path, permissions=0o755[32] -> Void)`](#`create_directory)
- [`func exists(path: Path -> Bool)`](#`exists)
- [`func extension(path: Path, full=yes -> Text)`](#`extension)
- [`func files(path: Path, include_hidden=no -> [Path])`](#`files)
- [`func glob(path: Path -> [Path])`](#`glob)
- [`func is_directory(path: Path, follow_symlinks=yes -> Bool)`](#`is_directory)
- [`func is_file(path: Path, follow_symlinks=yes -> Bool)`](#`is_file)
- [`func is_socket(path: Path, follow_symlinks=yes -> Bool)`](#`is_socket)
- [`func is_symlink(path: Path -> Bool)`](#`is_symlink)
- [`func parent(path: Path -> Path)`](#`parent)
- [`func read(path: Path -> Text?)`](#`read)
- [`func read_bytes(path: Path -> [Byte]?)`](#`read_bytes)
- [`func relative(path: Path, relative_to=(./) -> Path)`](#`relative)
- [`func remove(path: Path, ignore_missing=no -> Void)`](#`remove)
- [`func resolved(path: Path, relative_to=(./) -> Path)`](#`resolved)
- [`func subdirectories(path: Path, include_hidden=no -> [Path])`](#`subdirectories)
- [`func unique_directory(path: Path -> Path)`](#`unique_directory)
- [`func write(path: Path, text: Text, permissions=0o644[32] -> Void)`](#`write)
- [`func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)`](#`write_bytes)
- [`func write_unique(path: Path, text: Text -> Path)`](#`write_unique)
- [`func write_unique_bytes(path: Path, bytes: [Byte] -> Path)`](#`write_unique_bytes)
### `append`
**Description:**

1
docs/patterns.md
View File

@ -150,4 +150,3 @@ many repetitions you want by putting a number or range of numbers first using
{2+ space}
{0-1 question mark}
```

9
docs/rng.md
View File

@ -19,6 +19,15 @@ This documentation provides details on RNG functions available in the API.
[Arrays](arrays.md) also have some methods which use RNG values:
`array:shuffle()`, `array:shuffled()`, `array:random()`, and `array:sample()`.
- [`func bool(rng: RNG, p: Num = 0.5 -> Bool)`](#`bool)
- [`func byte(rng: RNG -> Byte)`](#`byte)
- [`func bytes(rng: RNG, count: Int -> [Byte])`](#`bytes)
- [`func copy(rng: RNG -> RNG)`](#`copy)
- [`func int(rng: RNG, min: Int, max: Int -> Int)`](#`int`, `int64`, `int32`, `int16`, `int8)
- [`func new(seed: [Byte] = (/dev/urandom):read_bytes(40)! -> RNG)`](#`new)
- [`func num(rng: RNG, min: Num = 0.0, max: Num = 1.0 -> Int)`](#`num`, `num32)
- [`func set_seed(rng: RNG, seed: [Byte])`](#`set_seed)
### `bool`
**Description:**

279
docs/sets.md
View File

@ -75,31 +75,17 @@ iterating over any of the new values.
## Set Methods
### `has`
**Description:**
Checks if the set contains a specified item.
**Signature:**
```tomo
func has(set:{T}, item:T -> Bool)
```
**Parameters:**
- `set`: The set to check.
- `item`: The item to check for presence.
**Returns:**
`yes` if the item is present, `no` otherwise.
**Example:**
```tomo
>> {10, 20}:has(20)
= yes
```
---
- [`func add(set:{T}, item: T -> Void)`](#`add)
- [`func add_all(set:@{T}, items: [T] -> Void)`](#`add_all)
- [`func clear(set:@{T} -> Void)`](#`clear)
- [`func has(set:{T}, item:T -> Bool)`](#`has)
- [`func (set: {T}, other: {T}, strict: Bool = no -> Bool)`](#`is_subset_of)
- [`func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)`](#`is_superset_of)
- [`func overlap(set:{T}, other: {T} -> {T})`](#`overlap)
- [`func remove(set:@{T}, item: T -> Void)`](#`remove)
- [`func remove_all(set:@{T}, items: [T] -> Void)`](#`remove_all)
- [`func with(set:{T}, other: {T} -> {T})`](#`with)
- [`func without(set:{T}, other: {T} -> {T})`](#`without)
### `add`
@ -151,56 +137,6 @@ Nothing.
---
### `remove`
**Description:**
Removes an item from the set.
**Signature:**
```tomo
func remove(set:@{T}, item: T -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `item`: The item to remove from the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:remove(42)
```
---
### `remove_all`
**Description:**
Removes multiple items from the set.
**Signature:**
```tomo
func remove_all(set:@{T}, items: [T] -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `items`: The array of items to remove from the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:remove_all([1, 2, 3])
```
---
### `clear`
**Description:**
@ -225,80 +161,28 @@ Nothing.
---
### `with`
### `has`
**Description:**
Creates a new set that is the union of the original set and another set.
Checks if the set contains a specified item.
**Signature:**
```tomo
func with(set:{T}, other: {T} -> {T})
func has(set:{T}, item:T -> Bool)
```
**Parameters:**
- `set`: The original set.
- `other`: The set to union with.
- `set`: The set to check.
- `item`: The item to check for presence.
**Returns:**
A new set containing all items from both sets.
`yes` if the item is present, `no` otherwise.
**Example:**
```tomo
>> {1, 2}:with({2, 3})
= {1, 2, 3}
```
---
### `overlap`
**Description:**
Creates a new set with items that are in both the original set and another set.
**Signature:**
```tomo
func overlap(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set to intersect with.
**Returns:**
A new set containing only items present in both sets.
**Example:**
```tomo
>> {1, 2}:overlap({2, 3})
= {2}
```
---
### `without`
**Description:**
Creates a new set with items from the original set but without items from another set.
**Signature:**
```tomo
func without(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set of items to remove from the original set.
**Returns:**
A new set containing items from the original set excluding those in the other set.
**Example:**
```tomo
>> {1, 2}:without({2, 3})
= {1}
>> {10, 20}:has(20)
= yes
```
---
@ -354,3 +238,128 @@ func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
>> {1, 2, 3}:is_superset_of({1, 2})
= yes
```
### `overlap`
**Description:**
Creates a new set with items that are in both the original set and another set.
**Signature:**
```tomo
func overlap(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set to intersect with.
**Returns:**
A new set containing only items present in both sets.
**Example:**
```tomo
>> {1, 2}:overlap({2, 3})
= {2}
```
---
### `remove`
**Description:**
Removes an item from the set.
**Signature:**
```tomo
func remove(set:@{T}, item: T -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `item`: The item to remove from the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:remove(42)
```
---
### `remove_all`
**Description:**
Removes multiple items from the set.
**Signature:**
```tomo
func remove_all(set:@{T}, items: [T] -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `items`: The array of items to remove from the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:remove_all([1, 2, 3])
```
---
### `with`
**Description:**
Creates a new set that is the union of the original set and another set.
**Signature:**
```tomo
func with(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set to union with.
**Returns:**
A new set containing all items from both sets.
**Example:**
```tomo
>> {1, 2}:with({2, 3})
= {1, 2, 3}
```
---
### `without`
**Description:**
Creates a new set with items from the original set but without items from another set.
**Signature:**
```tomo
func without(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set of items to remove from the original set.
**Returns:**
A new set containing items from the original set excluding those in the other set.
**Example:**
```tomo
>> {1, 2}:without({2, 3})
= {1}
```

5
docs/shell.md
View File

@ -13,6 +13,11 @@ user-controlled string is automatically escaped when performing interpolation.
## Shell Methods
- [`func by_line(command: Shell -> Void)`](#`by_line)
- [`func execute(command: Shell -> Int32?)`](#`execute)
- [`func run(command: Shell -> Text?)`](#`run)
- [`func run(command: Shell -> [Byte]?)`](#`run_bytes)
### `by_line`
**Description:**

7
docs/tables.md
View File

@ -133,6 +133,13 @@ iterating over any of the new values.
## Table Methods
- [`func bump(t:@{K,V}, key: K, amount: Int = 1 -> Void)`](#`bump)
- [`func clear(t:@{K,V})`](#`clear)
- [`func get(t:{K,V}, key: K -> V?)`](#`get)
- [`func has(t:{K,V}, key: K -> Bool)`](#`has)
- [`func remove(t:{K,V}, key: K -> Void)`](#`remove)
- [`func set(t:{K,V}, key: K, value: V -> Void)`](#`set)
### `bump`
**Description:**

374
docs/text.md
View File

@ -270,6 +270,42 @@ pattern documentation](patterns.md) for more details.
## Text Functions
- [`func as_c_string(text: Text -> CString)`](#`as_c_string)
- [`func at(text: Text, index: Int -> Text)`](#`at)
- [`func by_line(text: Text -> func(->Text?))`](#`by_line)
- [`func by_match(text: Text, pattern: Pattern -> func(->Match?))`](#`by_match)
- [`func by_split(text: Text, pattern: Pattern = $// -> func(->Text?))`](#`by_split)
- [`func bytes(text: Text -> [Byte])`](#`bytes)
- [`func codepoint_names(text: Text -> [Text])`](#`codepoint_names)
- [`func each(text: Text, pattern: Pattern, fn: func(m: Match), recursive: Bool = yes -> Int?)`](#`each)
- [`func ends_with(text: Text, suffix: Text -> Bool)`](#`ends_with)
- [`func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)`](#`find)
- [`func find_all(text: Text, pattern: Pattern -> [Match])`](#`find_all)
- [`func from(text: Text, first: Int -> Text)`](#`from)
- [`func from_codepoint_names(codepoints: [Int32] -> [Text])`](#`from_bytes)
- [`func from_c_string(str: CString -> Text)`](#`from_c_string)
- [`func from_codepoint_names(codepoint_names: [Text] -> [Text])`](#`from_codepoint_names)
- [`func from_codepoint_names(codepoints: [Int32] -> [Text])`](#`from_codepoints)
- [`func has(text: Text, pattern: Pattern -> Bool)`](#`has)
- [`func join(glue: Text, pieces: [Text] -> Text)`](#`join)
- [`func split(text: Text -> [Text])`](#`lines)
- [`func lower(text: Text -> Text)`](#`lower)
- [`func map(text: Text, pattern: Pattern, fn: func(text:Match)->Text -> Text, recursive: Bool = yes)`](#`map)
- [`func matches(text: Text, pattern: Pattern -> [Text])`](#`matches)
- [`func quoted(text: Text, color: Bool = no -> Text)`](#`quoted)
- [`func repeat(text: Text, count:Int -> Text)`](#`repeat)
- [`func replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)`](#`replace)
- [`func replace_all(replacements:{Pattern,Text}, backref: Pattern = $/\/, recursive: Bool = yes -> Text)`](#`replace_all)
- [`func reversed(text: Text -> Text)`](#`reversed)
- [`func slice(text: Text, from: Int = 1, to: Int = -1 -> Text)`](#`slice)
- [`func split(text: Text, pattern: Pattern = "" -> [Text])`](#`split)
- [`func starts_with(text: Text, prefix: Text -> Bool)`](#`starts_with)
- [`func title(text: Text -> Text)`](#`title)
- [`func to(text: Text, last: Int -> Text)`](#`to)
- [`func trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)`](#`trim)
- [`func upper(text: Text -> Text)`](#`upper)
- [`func utf32_codepoints(text: Text -> [Int32])`](#`utf32_codepoints)
### `as_c_string`
**Description:**
@ -470,31 +506,6 @@ An array of codepoint names (`[Text]`).
---
### `utf32_codepoints`
**Description:**
Returns an array of Unicode code points for UTF32 encoding of the text.
**Signature:**
```tomo
func utf32_codepoints(text: Text -> [Int32])
```
**Parameters:**
- `text`: The text from which to extract Unicode code points.
**Returns:**
An array of 32-bit integer Unicode code points (`[Int32]`).
**Example:**
```tomo
>> "Amélie":utf32_codepoints()
= [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32]
```
---
### `each`
**Description:**
@ -552,118 +563,6 @@ func ends_with(text: Text, suffix: Text -> Bool)
---
### `from_c_string`
**Description:**
Converts a C-style string to a `Text` value.
**Signature:**
```tomo
func from_c_string(str: CString -> Text)
```
**Parameters:**
- `str`: The C-style string to be converted.
**Returns:**
A `Text` value representing the C-style string.
**Example:**
```tomo
>> Text.from_c_string(CString("Hello"))
= "Hello"
```
---
### `from_codepoint_names`
**Description:**
Returns text that has the given codepoint names (according to the Unicode
specification) as its codepoints. Note: the text will be normalized, so the
resulting text's codepoints may not exactly match the input codepoints.
**Signature:**
```tomo
func from_codepoint_names(codepoint_names: [Text] -> [Text])
```
**Parameters:**
- `codepoint_names`: The names of each codepoint in the desired text. Names
are case-insentive.
**Returns:**
A new text with the specified codepoints after normalization has been applied.
Any invalid names are ignored.
**Example:**
```tomo
>> Text.from_codepoint_names([
"LATIN CAPITAL LETTER A WITH RING ABOVE",
"LATIN SMALL LETTER K",
"LATIN SMALL LETTER E",
]
= "Åke"
```
---
### `from_codepoints`
**Description:**
Returns text that has been constructed from the given UTF32 codepoints. Note:
the text will be normalized, so the resulting text's codepoints may not exactly
match the input codepoints.
**Signature:**
```tomo
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
A new text with the specified codepoints after normalization has been applied.
**Example:**
```tomo
>> Text.from_codepoints([197[32], 107[32], 101[32]])
= "Åke"
```
---
### `from_bytes`
**Description:**
Returns text that has been constructed from the given UTF8 bytes. Note: the
text will be normalized, so the resulting text's UTF8 bytes may not exactly
match the input.
**Signature:**
```tomo
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
A new text based on the input UTF8 bytes after normalization has been applied.
**Example:**
```tomo
>> Text.from_bytes([195[B], 133[B], 107[B], 101[B]])
= "Åke"
```
---
### `find`
**Description:**
@ -770,6 +669,118 @@ the length of the string.
---
### `from_bytes`
**Description:**
Returns text that has been constructed from the given UTF8 bytes. Note: the
text will be normalized, so the resulting text's UTF8 bytes may not exactly
match the input.
**Signature:**
```tomo
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
A new text based on the input UTF8 bytes after normalization has been applied.
**Example:**
```tomo
>> Text.from_bytes([195[B], 133[B], 107[B], 101[B]])
= "Åke"
```
---
### `from_c_string`
**Description:**
Converts a C-style string to a `Text` value.
**Signature:**
```tomo
func from_c_string(str: CString -> Text)
```
**Parameters:**
- `str`: The C-style string to be converted.
**Returns:**
A `Text` value representing the C-style string.
**Example:**
```tomo
>> Text.from_c_string(CString("Hello"))
= "Hello"
```
---
### `from_codepoint_names`
**Description:**
Returns text that has the given codepoint names (according to the Unicode
specification) as its codepoints. Note: the text will be normalized, so the
resulting text's codepoints may not exactly match the input codepoints.
**Signature:**
```tomo
func from_codepoint_names(codepoint_names: [Text] -> [Text])
```
**Parameters:**
- `codepoint_names`: The names of each codepoint in the desired text. Names
are case-insentive.
**Returns:**
A new text with the specified codepoints after normalization has been applied.
Any invalid names are ignored.
**Example:**
```tomo
>> Text.from_codepoint_names([
"LATIN CAPITAL LETTER A WITH RING ABOVE",
"LATIN SMALL LETTER K",
"LATIN SMALL LETTER E",
]
= "Åke"
```
---
### `from_codepoints`
**Description:**
Returns text that has been constructed from the given UTF32 codepoints. Note:
the text will be normalized, so the resulting text's codepoints may not exactly
match the input codepoints.
**Signature:**
```tomo
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
A new text with the specified codepoints after normalization has been applied.
**Example:**
```tomo
>> Text.from_codepoints([197[32], 107[32], 101[32]])
= "Åke"
```
---
### `has`
**Description:**
@ -887,38 +898,6 @@ The lowercase version of the text.
---
### `matches`
**Description:**
Checks if the `Text` matches target [pattern](patterns.md) and returns an array
of the matching text captures or a null value if the entire text doesn't match
the pattern.
**Signature:**
```tomo
func matches(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
**Returns:**
An array of the matching text captures if the entire text matches the pattern,
or a null value otherwise.
**Example:**
```tomo
>> "hello world":matches($/{id}/)
= none : [Text]?
>> "hello world":matches($/{id} {id}/)
= ["hello", "world"] : [Text]?
```
---
### `map`
**Description:**
@ -952,6 +931,38 @@ function to each.
---
### `matches`
**Description:**
Checks if the `Text` matches target [pattern](patterns.md) and returns an array
of the matching text captures or a null value if the entire text doesn't match
the pattern.
**Signature:**
```tomo
func matches(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
**Returns:**
An array of the matching text captures if the entire text matches the pattern,
or a null value otherwise.
**Example:**
```tomo
>> "hello world":matches($/{id}/)
= none : [Text]?
>> "hello world":matches($/{id} {id}/)
= ["hello", "world"] : [Text]?
```
---
### `quoted`
**Description:**
@ -1355,3 +1366,28 @@ The uppercase version of the text.
>> "amélie":upper()
= "AMÉLIE"
```
---
### `utf32_codepoints`
**Description:**
Returns an array of Unicode code points for UTF32 encoding of the text.
**Signature:**
```tomo
func utf32_codepoints(text: Text -> [Int32])
```
**Parameters:**
- `text`: The text from which to extract Unicode code points.
**Returns:**
An array of 32-bit integer Unicode code points (`[Int32]`).
**Example:**
```tomo
>> "Amélie":utf32_codepoints()
= [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32]
```

146
docs/threads.md
View File

@ -6,6 +6,80 @@ through [mutex-guarded datastructures](mutexed.md).
## Thread Methods
- [`func cancel(thread: Thread)`](#`cancel)
- [`func detach(thread: Thread)`](#`detach)
- [`func join(thread: Thread)`](#`join)
- [`func new(fn: func(->Void) -> Thread)`](#`new)
### `cancel`
**Description:**
Requests the cancellation of a specified thread.
**Signature:**
```tomo
func cancel(thread: Thread)
```
**Parameters:**
- `thread`: The thread to cancel.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:cancel()
```
---
### `detach`
**Description:**
Detaches a specified thread, allowing it to run independently.
**Signature:**
```tomo
func detach(thread: Thread)
```
**Parameters:**
- `thread`: The thread to detach.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:detach()
```
### `join`
**Description:**
Waits for a specified thread to terminate.
**Signature:**
```tomo
func join(thread: Thread)
```
**Parameters:**
- `thread`: The thread to join.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:join()
```
---
### `new`
**Description:**
@ -37,75 +111,3 @@ A new `Thread` object representing the created thread.
>> results:get()
= 11
```
---
### `cancel`
**Description:**
Requests the cancellation of a specified thread.
**Signature:**
```tomo
func cancel(thread: Thread)
```
**Parameters:**
- `thread`: The thread to cancel.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:cancel()
```
---
### `join`
**Description:**
Waits for a specified thread to terminate.
**Signature:**
```tomo
func join(thread: Thread)
```
**Parameters:**
- `thread`: The thread to join.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:join()
```
---
### `detach`
**Description:**
Detaches a specified thread, allowing it to run independently.
**Signature:**
```tomo
func detach(thread: Thread)
```
**Parameters:**
- `thread`: The thread to detach.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:detach()
```