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

Update docs to standardize function signature formatting

Browse Source
This commit is contained in:
Bruce Hill 2024-10-09 13:48:45 -04:00
parent 63d48e9feb
commit 5a80ff0db3
15 changed files with 566 additions and 557 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/README.md
View File

@ -42,9 +42,9 @@ Information about Tomo's built-in types can be found here:
**Description:**
Gets a line of user input text with a prompt.
**Usage:**
```markdown
ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Void)
**Signature:**
```tomo
func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Void)
```
**Parameters:**
@ -65,7 +65,7 @@ A line of user input text without a trailing newline, or empty text if
something went wrong (e.g. the user hit `Ctrl-D`).
**Example:**
```markdown
```tomo
>> ask("What's your name? ")
= "Arthur Dent"
```
@ -77,9 +77,9 @@ something went wrong (e.g. the user hit `Ctrl-D`).
**Description:**
Exits the program with a given status and optionally prints a message.
**Usage:**
```markdown
ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
**Signature:**
```tomo
func ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
```
**Parameters:**
@ -93,7 +93,7 @@ ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
This function never returns.
**Example:**
```markdown
```tomo
exit(status=1, "Goodbye forever!")
```
@ -104,9 +104,9 @@ exit(status=1, "Goodbye forever!")
**Description:**
Prints a message to the console.
**Usage:**
```markdown
say(text:Text, newline:Bool = yes -> Void)
**Signature:**
```tomo
func say(text:Text, newline:Bool = yes -> Void)
```
**Parameters:**
@ -118,7 +118,7 @@ say(text:Text, newline:Bool = yes -> Void)
Nothing.
**Example:**
```markdown
```tomo
say("Hello ", newline=no)
say("world!")
```
@ -130,9 +130,9 @@ say("world!")
**Description:**
Pause execution for a given number of seconds.
**Usage:**
```markdown
sleep(seconds: Num -> Void)
**Signature:**
```tomo
func sleep(seconds: Num -> Void)
```
**Parameters:**
@ -143,7 +143,7 @@ sleep(seconds: Num -> Void)
Nothing.
**Example:**
```markdown
```tomo
sleep(1.5)
```
@ -154,9 +154,9 @@ sleep(1.5)
**Description:**
Prints a message to the console, aborts the program, and prints a stack trace.
**Usage:**
```markdown
fail(message:Text -> Abort)
**Signature:**
```tomo
func fail(message:Text -> Abort)
```
**Parameters:**
@ -167,7 +167,7 @@ fail(message:Text -> Abort)
Nothing, aborts the program.
**Example:**
```markdown
```tomo
fail("Oh no!")
```
@ -178,9 +178,9 @@ fail("Oh no!")
**Description:**
Gets the current time. This is an alias for `DateTime.now()`.
**Usage:**
```markdown
now(->DateTime)
**Signature:**
```tomo
func now(->DateTime)
```
**Parameters:**
@ -191,7 +191,7 @@ None.
The current moment as a DateTime.
**Example:**
```markdown
```tomo
>> now()
= Sun Sep 29 20:12:33 2024
```

186
docs/arrays.md
View File

@ -237,9 +237,9 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
**Description:**
Performs a binary search on a sorted array.
**Usage:**
```markdown
binary_search(arr: [T], by=T.compare -> Int)
**Signature:**
```tomo
func binary_search(arr: [T], by: func(x,y:&T->Int32) = T.compare -> Int)
```
**Parameters:**
@ -255,7 +255,7 @@ order. That is, if the item is found, return its index, otherwise return the
place where it would be found if it were inserted and the array were sorted.
**Example:**
```markdown
```tomo
>> [1, 3, 5, 7, 9]:binary_search(5)
= 3
@ -273,9 +273,9 @@ place where it would be found if it were inserted and the array were sorted.
**Description:**
Creates a new array with elements spaced by the specified step value.
**Usage:**
```markdown
by(arr: [T], step: Int -> [T])
**Signature:**
```tomo
func by(arr: [T], step: Int -> [T])
```
**Parameters:**
@ -287,7 +287,7 @@ by(arr: [T], step: Int -> [T])
A new array with every `step`-th element from the original array.
**Example:**
```markdown
```tomo
>> [1, 2, 3, 4, 5, 6]:by(2)
= [1, 3, 5]
```
@ -299,9 +299,9 @@ A new array with every `step`-th element from the original array.
**Description:**
Clears all elements from the array.
**Usage:**
```markdown
clear(arr: & [T] -> Void)
**Signature:**
```tomo
func clear(arr: &[T] -> Void)
```
**Parameters:**
@ -312,7 +312,7 @@ clear(arr: & [T] -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> my_array:clear()
```
@ -323,9 +323,9 @@ Nothing.
**Description:**
Counts the occurrences of each element in the array.
**Usage:**
```markdown
counts(arr: [T] -> {T: Int})
**Signature:**
```tomo
func counts(arr: [T] -> {T: Int})
```
**Parameters:**
@ -336,7 +336,7 @@ counts(arr: [T] -> {T: Int})
A table mapping each element to its count.
**Example:**
```markdown
```tomo
>> [10, 20, 30, 30, 30]:counts()
= {10: 1, 20: 1, 30: 3}
```
@ -348,9 +348,9 @@ A table mapping each element to its count.
**Description:**
Finds the index of the first occurrence of an element (if any).
**Usage:**
```markdown
find(arr: [T] -> Int?)
**Signature:**
```tomo
func find(arr: [T] -> Int?)
```
**Parameters:**
@ -361,7 +361,7 @@ find(arr: [T] -> Int?)
The index of the first occurrence or `!Int` if not found.
**Example:**
```markdown
```tomo
>> [10, 20, 30, 40, 50]:find(20)
= 2?
@ -376,9 +376,9 @@ The index of the first occurrence or `!Int` if not found.
**Description:**
Find the index of the first item that matches a predicate function (if any).
**Usage:**
```markdown
first(arr: [T], predicate: func(item:&T)->Bool -> Int)
**Signature:**
```tomo
func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)
```
**Parameters:**
@ -392,7 +392,7 @@ Returns the index of the first item where the predicate is true or `!Int` if no
item matches.
**Example:**
```markdown
```tomo
>> [4, 5, 6]:find(func(i:&Int): i:is_prime())
= 5?
>> [4, 6, 8]:find(func(i:&Int): i:is_prime())
@ -406,9 +406,9 @@ item matches.
**Description:**
Returns a slice of the array starting from a specified index.
**Usage:**
```markdown
from(arr: [T], first: Int -> [T])
**Signature:**
```tomo
func from(arr: [T], first: Int -> [T])
```
**Parameters:**
@ -420,7 +420,7 @@ from(arr: [T], first: Int -> [T])
A new array starting from the specified index.
**Example:**
```markdown
```tomo
>> [10, 20, 30, 40, 50]:from(3)
= [30, 40, 50]
```
@ -432,9 +432,9 @@ A new array starting from the specified index.
**Description:**
Checks if the array has any elements.
**Usage:**
```markdown
has(arr: [T] -> Bool)
**Signature:**
```tomo
func has(arr: [T] -> Bool)
```
**Parameters:**
@ -445,7 +445,7 @@ has(arr: [T] -> Bool)
`yes` if the array has elements, `no` otherwise.
**Example:**
```markdown
```tomo
>> [10, 20, 30]:has(20)
= yes
```
@ -458,9 +458,9 @@ has(arr: [T] -> Bool)
Removes and returns the top element of a heap. By default, this is the
*minimum* value in the heap.
**Usage:**
```markdown
heap_pop(arr: & [T], by=T.compare -> T)
**Signature:**
```tomo
func heap_pop(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> T)
```
**Parameters:**
@ -473,7 +473,7 @@ heap_pop(arr: & [T], by=T.compare -> T)
The removed top element of the heap.
**Example:**
```markdown
```tomo
>> my_heap := [30, 10, 20]
>> my_heap:heapify()
>> my_heap:heap_pop()
@ -488,9 +488,9 @@ The removed top element of the heap.
Adds an element to the heap and maintains the heap property. By default, this
is a *minimum* heap.
**Usage:**
```markdown
heap_push(arr: & [T], item: T, by=T.compare -> Void)
**Signature:**
```tomo
func heap_push(arr: &[T], item: T, by=T.compare -> Void)
```
**Parameters:**
@ -504,7 +504,7 @@ heap_push(arr: & [T], item: T, by=T.compare -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> my_heap:heap_push(10)
```
@ -515,9 +515,9 @@ Nothing.
**Description:**
Converts an array into a heap.
**Usage:**
```markdown
heapify(arr: & [T], by=T.compare -> Void)
**Signature:**
```tomo
func heapify(arr: &[T], by: func(x,y:&T->Int32) = T.compare -> Void)
```
**Parameters:**
@ -530,7 +530,7 @@ heapify(arr: & [T], by=T.compare -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> my_heap := [30, 10, 20]
>> my_heap:heapify()
```
@ -542,9 +542,9 @@ Nothing.
**Description:**
Inserts an element at a specified position in the array.
**Usage:**
```markdown
insert(arr: & [T], item: T, at: Int = 0 -> Void)
**Signature:**
```tomo
func insert(arr: &[T], item: T, at: Int = 0 -> Void)
```
**Parameters:**
@ -559,7 +559,7 @@ insert(arr: & [T], item: T, at: Int = 0 -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> arr := [10, 20]
>> arr:insert(30)
>> arr
@ -577,9 +577,9 @@ Nothing.
**Description:**
Inserts an array of items at a specified position in the array.
**Usage:**
```markdown
insert_all(arr: & [T], items: [T], at: Int = 0 -> Void)
**Signature:**
```tomo
func insert_all(arr: &[T], items: [T], at: Int = 0 -> Void)
```
**Parameters:**
@ -594,7 +594,7 @@ insert_all(arr: & [T], items: [T], at: Int = 0 -> Void)
Nothing.
**Example:**
```markdown
```tomo
arr := [10, 20]
arr:insert_all([30, 40])
>> arr
@ -612,9 +612,9 @@ arr:insert_all([99, 100], at=2)
**Description:**
Selects a random element from the array.
**Usage:**
```markdown
random(arr: [T] -> T)
**Signature:**
```tomo
func random(arr: [T] -> T)
```
**Parameters:**
@ -625,7 +625,7 @@ random(arr: [T] -> T)
A random element from the array.
**Example:**
```markdown
```tomo
>> [10, 20, 30]:random()
= 20
```
@ -637,9 +637,9 @@ A random element from the array.
**Description:**
Removes elements from the array starting at a specified index.
**Usage:**
```markdown
remove_at(arr: & [T], at: Int = -1, count: Int = 1 -> Void)
**Signature:**
```tomo
func remove_at(arr: &[T], at: Int = -1, count: Int = 1 -> Void)
```
**Parameters:**
@ -652,7 +652,7 @@ remove_at(arr: & [T], at: Int = -1, count: Int = 1 -> Void)
Nothing.
**Example:**
```markdown
```tomo
arr := [10, 20, 30, 40, 50]
arr:remove_at(2)
>> arr
@ -670,9 +670,9 @@ arr:remove_at(2, count=2)
**Description:**
Removes all occurrences of a specified item from the array.
**Usage:**
```markdown
remove_item(arr: & [T], item: T, max_count: Int = -1 -> Void)
**Signature:**
```tomo
func remove_item(arr: &[T], item: T, max_count: Int = -1 -> Void)
```
**Parameters:**
@ -685,7 +685,7 @@ remove_item(arr: & [T], item: T, max_count: Int = -1 -> Void)
Nothing.
**Example:**
```markdown
```tomo
arr := [10, 20, 10, 20, 30]
arr:remove_item(10)
>> arr
@ -703,9 +703,9 @@ arr:remove_item(20, max_count=1)
**Description:**
Returns a reversed slice of the array.
**Usage:**
```markdown
reversed(arr: [T] -> [T])
**Signature:**
```tomo
func reversed(arr: [T] -> [T])
```
**Parameters:**
@ -716,7 +716,7 @@ reversed(arr: [T] -> [T])
A slice of the array with elements in reverse order.
**Example:**
```markdown
```tomo
>> [10, 20, 30]:reversed()
= [30, 20, 10]
```
@ -729,9 +729,9 @@ A slice of the array with elements in reverse order.
Selects a sample of elements from the array, optionally with weighted
probabilities.
**Usage:**
```markdown
sample(arr: [T], count: Int, weights: [Num]? = ![Num] -> [T])
**Signature:**
```tomo
func sample(arr: [T], count: Int, weights: [Num]? = ![Num] -> [T])
```
**Parameters:**
@ -755,7 +755,7 @@ Errors will be raised if any of the following conditions occurs:
A list of sampled elements from the array.
**Example:**
```markdown
```tomo
>> [10, 20, 30]:sample(2, weights=[90%, 5%, 5%])
= [10, 10]
```
@ -767,9 +767,9 @@ A list of sampled elements from the array.
**Description:**
Shuffles the elements of the array in place.
**Usage:**
```markdown
shuffle(arr: & [T] -> Void)
**Signature:**
```tomo
func shuffle(arr: &[T] -> Void)
```
**Parameters:**
@ -780,7 +780,7 @@ shuffle(arr: & [T] -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> arr:shuffle()
```
@ -791,9 +791,9 @@ Nothing.
**Description:**
Creates a new array with elements shuffled.
**Usage:**
```markdown
shuffled(arr: [T] -> [T])
**Signature:**
```tomo
func shuffled(arr: [T] -> [T])
```
**Parameters:**
@ -804,7 +804,7 @@ shuffled(arr: [T] -> [T])
A new array with shuffled elements.
**Example:**
```markdown
```tomo
>> [10, 20, 30, 40]:shuffled()
= [40, 10, 30, 20]
```
@ -816,9 +816,9 @@ A new array with shuffled elements.
**Description:**
Sorts the elements of the array in place in ascending order (small to large).
**Usage:**
```markdown
sort(arr: & [T], by=T.compare -> Void)
**Signature:**
```tomo
func sort(arr: &[T], by=T.compare -> Void)
```
**Parameters:**
@ -831,7 +831,7 @@ sort(arr: & [T], by=T.compare -> Void)
Nothing.
**Example:**
```markdown
```tomo
arr := [40, 10, -30, 20]
arr:sort()
>> arr
@ -849,8 +849,8 @@ arr:sort(func(a,b:&Int): a:abs() <> b:abs())
**Description:**
Creates a new array with elements sorted.
**Usage:**
```markdown
**Signature:**
```tomo
sorted(arr: [T], by=T.compare -> [T])
```
@ -864,7 +864,7 @@ sorted(arr: [T], by=T.compare -> [T])
A new array with sorted elements.
**Example:**
```markdown
```tomo
>> [40, 10, -30, 20]:sorted()
= [-30, 10, 20, 40]
@ -879,8 +879,8 @@ A new array with sorted elements.
**Description:**
Returns a slice of the array from the start of the original array up to a specified index (inclusive).
**Usage:**
```markdown
**Signature:**
```tomo
to(arr: [T], last: Int -> [T])
```
@ -893,7 +893,7 @@ to(arr: [T], last: Int -> [T])
A new array containing elements from the start up to the specified index.
**Example:**
```markdown
```tomo
>> [10, 20, 30, 40, 50]:to(3)
= [10, 20, 30]
@ -908,8 +908,8 @@ A new array containing elements from the start up to the specified index.
**Description:**
Returns a Set that contains the unique elements of the array.
**Usage:**
```markdown
**Signature:**
```tomo
unique(arr: [T] -> {T})
```
@ -921,7 +921,7 @@ unique(arr: [T] -> {T})
A set containing only unique elements from the array.
**Example:**
```markdown
```tomo
>> [10, 20, 10, 10, 30]:unique()
= {10, 20, 30}
```

8
docs/booleans.md
View File

@ -14,9 +14,9 @@ Converts a string representation of a boolean value into a boolean. Acceptable
boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`,
`true`/`false`, `on`/`off`.
**Usage:**
**Signature:**
```tomo
from_text(text: Text, success: Bool = !&Bool -> Bool)
func from_text(text: Text, success: Bool = !&Bool -> Bool)
```
**Parameters:**
@ -47,9 +47,9 @@ from_text(text: Text, success: Bool = !&Bool -> Bool)
**Description:**
Generates a random boolean value based on a specified probability.
**Usage:**
**Signature:**
```tomo
random(p: Float = 0.5 -> Bool)
func random(p: Float = 0.5 -> Bool)
```
**Parameters:**

4
docs/bytes.md
View File

@ -14,9 +14,9 @@ integer with a `[B]` suffix, e.g. `255[B]`.
**Description:**
Generates a random byte value in the specified range.
**Usage:**
**Signature:**
```tomo
random(min: Byte = Byte.min, max: Byte = Byte.max -> Byte)
func random(min: Byte = Byte.min, max: Byte = Byte.max -> Byte)
```
**Parameters:**

48
docs/channels.md
View File

@ -29,9 +29,9 @@ small_channel := |:Int; max_size=5|
**Description:**
Adds an item to the channel.
**Usage:**
```markdown
give(channel:|T|, item: T, front: Bool = no -> Void)
**Signature:**
```tomo
func give(channel:|T|, item: T, front: Bool = no -> Void)
```
**Parameters:**
@ -44,7 +44,7 @@ give(channel:|T|, item: T, front: Bool = no -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> channel:give("Hello")
```
@ -55,9 +55,9 @@ Nothing.
**Description:**
Adds multiple items to the channel.
**Usage:**
```markdown
give_all(channel:|T|, items: [T], front: Bool = no -> Void)
**Signature:**
```tomo
func give_all(channel:|T|, items: [T], front: Bool = no -> Void)
```
**Parameters:**
@ -70,7 +70,7 @@ give_all(channel:|T|, items: [T], front: Bool = no -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> channel:give_all([1, 2, 3])
```
@ -81,9 +81,9 @@ Nothing.
**Description:**
Removes and returns an item from the channel. If the channel is empty, it waits until an item is available.
**Usage:**
```markdown
get(channel:|T|, front: Bool = yes -> T)
**Signature:**
```tomo
func get(channel:|T|, front: Bool = yes -> T)
```
**Parameters:**
@ -95,7 +95,7 @@ get(channel:|T|, front: Bool = yes -> T)
The item removed from the channel.
**Example:**
```markdown
```tomo
>> channel:peek()
= "Hello"
```
@ -108,9 +108,9 @@ The item removed from the channel.
Returns the next item that will come out of the channel, but without removing
it. If the channel is empty, it waits until an item is available.
**Usage:**
```markdown
peek(channel:|T|, front: Bool = yes -> T)
**Signature:**
```tomo
func peek(channel:|T|, front: Bool = yes -> T)
```
**Parameters:**
@ -122,7 +122,7 @@ peek(channel:|T|, front: Bool = yes -> T)
The item removed from the channel.
**Example:**
```markdown
```tomo
>> channel:get()
= "Hello"
```
@ -134,9 +134,9 @@ The item removed from the channel.
**Description:**
Removes all items from the channel.
**Usage:**
```markdown
clear(channel:|T| -> Void)
**Signature:**
```tomo
func clear(channel:|T| -> Void)
```
**Parameters:**
@ -147,7 +147,7 @@ clear(channel:|T| -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> channel:clear()
```
@ -158,9 +158,9 @@ Nothing.
**Description:**
Returns a list of all items currently in the channel without removing them.
**Usage:**
```markdown
channel:view(->[T])
**Signature:**
```tomo
func channel:view(->[T])
```
**Parameters:**
@ -171,7 +171,7 @@ channel:view(->[T])
An array of items currently in the channel.
**Example:**
```markdown
```tomo
>> channel:view()
= [1, 2, 3]
```

10
docs/command-line-parsing.md
View File

@ -18,10 +18,10 @@ for the arguments to `main()`:
```bash
$ tomo greet.tm
greet: Required argument 'name' was not provided!
Usage: greet [--help] <name> [--be-excited]
Signature: greet [--help] <name> [--be-excited]
$ tomo greet.tm --help
Usage: greet [--help] <name> [--be-excited]
Signature: greet [--help] <name> [--be-excited]
$ tomo greet.tm "Zaphod"
Hi Zaphod.
@ -34,7 +34,7 @@ Hi Zaphod.
$ tomo greet.tm --not-a-real-argument "Bob"
greet: Unrecognized argument: --not-a-real-argument
Usage: greet [--help] <name> [--be-excited]
Signature: greet [--help] <name> [--be-excited]
```
Underscores in argument names are converted to dashes when parsing command line
@ -88,13 +88,13 @@ enum Foo(One, Two, Three)
func main(foo:Foo):
>> foo
# Usage:
# Signature:
$ tomo foo.tm one
>> Foo.One
$ tomo foo.tm xxx
foo: Invalid value provided for --foo; valid values are: One Two
Usage: foo [--help] <foo>
Signature: foo [--help] <foo>
```
### Arrays of Text

139
docs/datetime.md
View File

@ -77,13 +77,14 @@ affected by leap seconds. For this reason, `after()` takes an argument,
`timezone` which is used to determine in which timezone the offsets should be
calculated.
**Usage:**
```markdown
datetime:after(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 -> DateTime)
**Signature:**
```tomo
func after(datetime: DateTime, 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 -> DateTime)
```
**Parameters:**
- `datetime`: The datetime used as a starting point.
- `seconds` (optional): An amount of seconds to offset the datetime (default: 0).
- `minutes` (optional): An amount of minutes to offset the datetime (default: 0).
- `hours` (optional): An amount of hours to offset the datetime (default: 0).
@ -98,7 +99,7 @@ datetime:after(seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days
A new `DateTime` offset by the given amount.
**Example:**
```markdown
```tomo
>> DateTime(2024, 9, 29, hour=19):after(days=1, minutes=30)
= Mon Sep 30 19:30:00 2024 EDT
```
@ -111,20 +112,21 @@ A new `DateTime` offset by the given amount.
Return a text representation of the datetime using the `"%F"` format
specifier, which gives the date in `YYYY-MM-DD` form.
**Usage:**
```markdown
datetime:date(timezone : Text? = !Text -> Text)
**Signature:**
```tomo
func date(datetime: DateTime, timezone : Text? = !Text -> Text)
```
**Parameters:**
- `datetime`: The datetime to get the date from.
- `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone).
**Returns:**
The date in `YYYY-MM-DD` format.
**Example:**
```markdown
```tomo
>> DateTime(2024, 9, 29):date()
= "2024-09-29"
```
@ -139,13 +141,14 @@ options, return a text representation of the given date in the given format. If
`timezone` is specified, use that timezone instead of the current local
timezone.
**Usage:**
```markdown
datetime:format(format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)
**Signature:**
```tomo
func format(datetime: DateTime, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)
```
**Parameters:**
- `datetime`: The datetime to format.
- `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`).
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -153,7 +156,7 @@ datetime:format(format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -
Nothing.
**Example:**
```markdown
```tomo
>> DateTime(2024, 9, 29):format("%A")
= "Sunday"
```
@ -166,9 +169,9 @@ Nothing.
Return a datetime object that represents the same moment in time as
the given UNIX epoch timestamp (seconds since January 1, 1970 UTC).
**Usage:**
```markdown
DateTime.from_unix_timestamp(timestamp: Int64 -> DateTime)
**Signature:**
```tomo
func from_unix_timestamp(timestamp: Int64 -> DateTime)
```
**Parameters:**
@ -179,7 +182,7 @@ DateTime.from_unix_timestamp(timestamp: Int64 -> DateTime)
A `DateTime` object representing the same moment as the given UNIX timestamp.
**Example:**
```markdown
```tomo
# In the New York timezone:
>> DateTime.from_unix_timestamp(0)
= Wed Dec 31 19:00:00 1969
@ -193,13 +196,14 @@ A `DateTime` object representing the same moment as the given UNIX timestamp.
Get various components of the given datetime object and store them in the
provided optional fields.
**Usage:**
```markdown
datetime:get(year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, hour : &Int? = !&Int, minute : &Int? = !&Int, second : &Int? = !&Int, nanosecond : &Int? = !&Int, weekday : &Int? = !&Int, timezone : Text? = !Text -> Void)
**Signature:**
```tomo
func get(datetime: DateTime, year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, hour : &Int? = !&Int, minute : &Int? = !&Int, second : &Int? = !&Int, nanosecond : &Int? = !&Int, weekday : &Int? = !&Int, timezone : Text? = !Text -> Void)
```
**Parameters:**
- `datetime`: The datetime from which to extract information.
- `year`: If non-null, store the year here.
- `month`: If non-null, store the month here (1-12).
- `day`: If non-null, store the day of the month here (1-31).
@ -214,7 +218,7 @@ datetime:get(year : &Int? = !&Int, month : &Int? = !&Int, day : &Int? = !&Int, h
Nothing.
**Example:**
```markdown
```tomo
dt := DateTime(2024, 9, 29)
month := 0
dt:get(month=&month)
@ -231,9 +235,9 @@ Get the local timezone's name (e.g. `America/New_York` or `UTC`. By default,
this value is read from `/etc/localtime`, however, this can be overridden by
calling `DateTime.set_local_timezone(...)`.
**Usage:**
```markdown
DateTime.get_local_timezone(->Text)
**Signature:**
```tomo
func get_local_timezone(->Text)
```
**Parameters:**
@ -244,7 +248,7 @@ None.
The name of the current local timezone.
**Example:**
```markdown
```tomo
>> DateTime.get_local_timezone()
= "America/New_York"
```
@ -256,20 +260,21 @@ The name of the current local timezone.
**Description:**
Return the number of hours until a given datetime.
**Usage:**
```markdown
datetime:hours_till(then:DateTime -> Num)
**Signature:**
```tomo
func hours_till(datetime: DateTime, then:DateTime -> Num)
```
**Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in hours).
**Returns:**
The number of hours (possibly fractional, possibly negative) until the given time.
**Example:**
```markdown
```tomo
the_future := now():after(hours=1, minutes=30)
>> now():hours_till(the_future)
= 1.5
@ -282,20 +287,21 @@ the_future := now():after(hours=1, minutes=30)
**Description:**
Return the number of minutes until a given datetime.
**Usage:**
```markdown
datetime:minutes_till(then:DateTime -> Num)
**Signature:**
```tomo
func minutes_till(datetime: DateTime, then:DateTime -> Num)
```
**Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in minutes).
**Returns:**
The number of minutes (possibly fractional, possibly negative) until the given time.
**Example:**
```markdown
```tomo
the_future := now():after(minutes=1, seconds=30)
>> now():minutes_till(the_future)
= 1.5
@ -310,9 +316,9 @@ Return a new `DateTime` object representing the given time parameters expressed
in local time. This function is the same as calling `DateTime` directly as a
constructor.
**Usage:**
```markdown
DateTime.new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> DateTime)
**Signature:**
```tomo
func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> DateTime)
```
**Parameters:**
@ -332,7 +338,7 @@ example, `DateTime.new(..., hour=3, minute=65)` is the same as
integer, an error will be raised.
**Example:**
```markdown
```tomo
>> DateTime.new(2024, 9, 29)
= Mon Sep 30 00:00:00 2024 EDT
@ -349,9 +355,9 @@ integer, an error will be raised.
Get a `DateTime` object representing the current date and time. This function
is the same as the global function `now()`.
**Usage:**
```markdown
DateTime.now(->DateTime)
**Signature:**
```tomo
func now(->DateTime)
```
**Parameters:**
@ -362,7 +368,7 @@ None.
Returns a `DateTime` object representing the current date and time.
**Example:**
```markdown
```tomo
>> DateTime.now()
= Sun Sep 29 20:22:48 2024 EDT
```
@ -375,9 +381,9 @@ Returns a `DateTime` object representing the current date and time.
Return a new `DateTime` object parsed from the given string in the given format,
or a null value if the value could not be successfully parsed.
**Usage:**
```markdown
DateTime.parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> DateTime?)
**Signature:**
```tomo
func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> DateTime?)
```
**Parameters:**
@ -392,7 +398,7 @@ If the text was successfully parsed according to the given format, return a
`DateTime` representing that information. Otherwise, return a null value.
**Example:**
```markdown
```tomo
>> DateTime.parse("2024-09-29", "%Y-%m-%d")!
= Sun Sep 29 00:00:00 2024 EDT
@ -408,13 +414,14 @@ If the text was successfully parsed according to the given format, return a
Return a plain English textual representation of the approximate time difference
between two `DateTime`s. For example: `5 minutes ago` or `1 day later`
**Usage:**
```markdown
datetime:relative(relative_to : DateTime = DateTime.now(), timezone : Text? = !Text -> Text)
**Signature:**
```tomo
func relative(datetime: DateTime, relative_to : DateTime = DateTime.now(), timezone : Text? = !Text -> Text)
```
**Parameters:**
- `datetime`: The datetime whose relative time you're getting.
- `relative_to` (optional): The time against which the relative time is calculated (default: `DateTime.now()`).
- `timezone` (optional): If specified, perform calculations in the given
timezone (otherwise, use the current local timezone).
@ -428,7 +435,7 @@ represented as `2 days later`. Datetimes in the past will have the suffix `"
ago"`, while datetimes in the future will have the suffix `" later"`.
**Example:**
```markdown
```tomo
>> now():after(days=2):relative()
= "2 days later"
@ -443,20 +450,21 @@ ago"`, while datetimes in the future will have the suffix `" later"`.
**Description:**
Return the number of seconds until a given datetime.
**Usage:**
```markdown
datetime:seconds_till(then:DateTime -> Num)
**Signature:**
```tomo
func seconds_till(datetime: DateTime, then:DateTime -> Num)
```
**Parameters:**
- `datetime`: The starting point datetime.
- `then`: Another datetime that we want to calculate the time offset from (in seconds).
**Returns:**
The number of seconds (possibly fractional, possibly negative) until the given time.
**Example:**
```markdown
```tomo
the_future := now():after(seconds=1)
>> now():seconds_till(the_future)
= 1
@ -473,9 +481,9 @@ timezone for performing calculations and constructing `DateTime` objects from
component parts. It's also used as the default way that `DateTime` objects are
converted to text.
**Usage:**
```markdown
DateTime.set_local_timezone(timezone : Text? = !Text -> Void)
**Signature:**
```tomo
func set_local_timezone(timezone : Text? = !Text -> Void)
```
**Parameters:**
@ -488,7 +496,7 @@ DateTime.set_local_timezone(timezone : Text? = !Text -> Void)
Nothing.
**Example:**
```markdown
```tomo
DateTime.set_local_timezone("America/Los_Angeles")
```
@ -499,13 +507,14 @@ DateTime.set_local_timezone("America/Los_Angeles")
**Description:**
Return a text representation of the time component of the given datetime.
**Usage:**
```markdown
datetime:time(seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)
**Signature:**
```tomo
func time(datetime: DateTime, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)
```
**Parameters:**
- `datetime`: The datetime whose time value you want to get.
- `seconds`: Whether to include seconds in the time (default: `no`).
- `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`).
- `timezone` (optional): If specified, give the time in the given timezone (otherwise, use the current local timezone).
@ -514,7 +523,7 @@ datetime:time(seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text
A text representation of the time component of the datetime.
**Example:**
```markdown
```tomo
dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30)
>> dt:time()
@ -535,20 +544,20 @@ dt := DateTime(2024, 9, 29, hours=13, minutes=59, seconds=30)
Get the UNIX timestamp of the given datetime (seconds since the UNIX epoch:
January 1, 1970 UTC).
**Usage:**
```markdown
datetime:unix_timestamp(->Int64)
**Signature:**
```tomo
func unix_timestamp(datetime:DateTime->Int64)
```
**Parameters:**
None.
`datetime`: The datetime whose UNIX timestamp you want to get.
**Returns:**
A 64-bit integer representation of the UNIX timestamp.
**Example:**
```markdown
```tomo
>> now():unix_timestamp()
= 1727654730[64]
```

48
docs/integers.md
View File

@ -35,9 +35,9 @@ can be called either on the type itself: `Int.sqrt(x)` or as a method call:
**Description:**
Formats an integer as a string with a specified number of digits.
**Usage:**
**Signature:**
```tomo
format(i: Int, digits: Int = 0 -> Text)
func format(i: Int, digits: Int = 0 -> Text)
```
**Parameters:**
@ -61,9 +61,9 @@ A string representation of the integer, padded to the specified number of digits
**Description:**
Converts an integer to its hexadecimal representation.
**Usage:**
**Signature:**
```tomo
hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)
func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)
```
**Parameters:**
@ -89,9 +89,9 @@ The hexadecimal string representation of the integer.
**Description:**
Converts an integer to its octal representation.
**Usage:**
**Signature:**
```tomo
octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)
func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)
```
**Parameters:**
@ -116,9 +116,9 @@ The octal string representation of the integer.
**Description:**
Generates a random integer between the specified minimum and maximum values.
**Usage:**
**Signature:**
```tomo
random(min: Int, max: Int -> Int)
func random(min: Int, max: Int -> Int)
```
**Parameters:**
@ -142,9 +142,9 @@ A random integer between `min` and `max` (inclusive).
**Description:**
Converts a text representation of an integer into an integer.
**Usage:**
**Signature:**
```tomo
from_text(text: Text, success: Bool = !&Bool? -> Int)
func from_text(text: Text, success: Bool = !&Bool? -> Int)
```
**Parameters:**
@ -186,9 +186,9 @@ success := no
**Description:**
Creates an inclusive range of integers between the specified start and end values.
**Usage:**
**Signature:**
```tomo
to(from: Int, to: Int -> Range)
func to(from: Int, to: Int -> Range)
```
**Parameters:**
@ -212,9 +212,9 @@ A range object representing all integers from `from` to `to` (inclusive).
**Description:**
Calculates the absolute value of an integer.
**Usage:**
**Signature:**
```tomo
abs(x: Int -> Int)
func abs(x: Int -> Int)
```
**Parameters:**
@ -237,9 +237,9 @@ The absolute value of `x`.
**Description:**
Calculates the square root of an integer.
**Usage:**
**Signature:**
```tomo
sqrt(x: Int -> Int)
func sqrt(x: Int -> Int)
```
**Parameters:**
@ -270,9 +270,9 @@ 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:**
**Signature:**
```tomo
is_prime(x: Int, reps: Int = 50 -> Bool)
func is_prime(x: Int, reps: Int = 50 -> Bool)
```
**Parameters:**
@ -304,9 +304,9 @@ 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:**
**Signature:**
```tomo
next_prime(x: Int -> Int)
func next_prime(x: Int -> Int)
```
**Parameters:**
@ -337,9 +337,9 @@ 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:**
**Signature:**
```tomo
prev_prime(x: Int -> Int)
func prev_prime(x: Int -> Int)
```
**Parameters:**
@ -363,9 +363,9 @@ The previous prime number less than `x`.
Returns the given number clamped between two values so that it is within
that range.
**Usage:**
**Signature:**
```tomo
clamped(x, low, high: Int -> Int)
func clamped(x, low, high: Int -> Int)
```
**Parameters:**

206
docs/nums.md
View File

@ -40,9 +40,9 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
**Description:**
Calculates the absolute value of a number.
**Usage:**
**Signature:**
```tomo
abs(n: Num -> Num)
func abs(n: Num -> Num)
```
**Parameters:**
@ -65,9 +65,9 @@ The absolute value of `n`.
**Description:**
Computes the arc cosine of a number.
**Usage:**
**Signature:**
```tomo
acos(x: Num -> Num)
func acos(x: Num -> Num)
```
**Parameters:**
@ -90,9 +90,9 @@ The arc cosine of `x` in radians.
**Description:**
Computes the inverse hyperbolic cosine of a number.
**Usage:**
**Signature:**
```tomo
acosh(x: Num -> Num)
func acosh(x: Num -> Num)
```
**Parameters:**
@ -115,9 +115,9 @@ The inverse hyperbolic cosine of `x`.
**Description:**
Computes the arc sine of a number.
**Usage:**
**Signature:**
```tomo
asin(x: Num -> Num)
func asin(x: Num -> Num)
```
**Parameters:**
@ -140,9 +140,9 @@ The arc sine of `x` in radians.
**Description:**
Computes the inverse hyperbolic sine of a number.
**Usage:**
**Signature:**
```tomo
asinh(x: Num -> Num)
func asinh(x: Num -> Num)
```
**Parameters:**
@ -165,9 +165,9 @@ The inverse hyperbolic sine of `x`.
**Description:**
Computes the arc tangent of the quotient of two numbers.
**Usage:**
**Signature:**
```tomo
atan2(x: Num, y: Num -> Num)
func atan2(x: Num, y: Num -> Num)
```
**Parameters:**
@ -191,9 +191,9 @@ The arc tangent of `x/y` in radians.
**Description:**
Computes the arc tangent of a number.
**Usage:**
**Signature:**
```tomo
atan(x: Num -> Num)
func atan(x: Num -> Num)
```
**Parameters:**
@ -216,9 +216,9 @@ The arc tangent of `x` in radians.
**Description:**
Computes the inverse hyperbolic tangent of a number.
**Usage:**
**Signature:**
```tomo
atanh(x: Num -> Num)
func atanh(x: Num -> Num)
```
**Parameters:**
@ -241,9 +241,9 @@ The inverse hyperbolic tangent of `x`.
**Description:**
Computes the cube root of a number.
**Usage:**
**Signature:**
```tomo
cbrt(x: Num -> Num)
func cbrt(x: Num -> Num)
```
**Parameters:**
@ -266,9 +266,9 @@ The cube root of `x`.
**Description:**
Rounds a number up to the nearest integer.
**Usage:**
**Signature:**
```tomo
ceil(x: Num -> Num)
func ceil(x: Num -> Num)
```
**Parameters:**
@ -291,9 +291,9 @@ The smallest integer greater than or equal to `x`.
**Description:**
Copies the sign of one number to another.
**Usage:**
**Signature:**
```tomo
copysign(x: Num, y: Num -> Num)
func copysign(x: Num, y: Num -> Num)
```
**Parameters:**
@ -317,9 +317,9 @@ A number with the magnitude of `x` and the sign of `y`.
**Description:**
Computes the cosine of a number (angle in radians).
**Usage:**
**Signature:**
```tomo
cos(x: Num -> Num)
func cos(x: Num -> Num)
```
**Parameters:**
@ -342,9 +342,9 @@ The cosine of `x`.
**Description:**
Computes the hyperbolic cosine of a number.
**Usage:**
**Signature:**
```tomo
cosh(x: Num -> Num)
func cosh(x: Num -> Num)
```
**Parameters:**
@ -367,9 +367,9 @@ The hyperbolic cosine of `x`.
**Description:**
Computes the error function of a number.
**Usage:**
**Signature:**
```tomo
erf(x: Num -> Num)
func erf(x: Num -> Num)
```
**Parameters:**
@ -392,9 +392,9 @@ The error function of `x`.
**Description:**
Computes the complementary error function of a number.
**Usage:**
**Signature:**
```tomo
erfc(x: Num -> Num)
func erfc(x: Num -> Num)
```
**Parameters:**
@ -417,9 +417,9 @@ The complementary error function of `x`.
**Description:**
Computes \( 2^x \) for a number.
**Usage:**
**Signature:**
```tomo
exp2(x: Num -> Num)
func exp2(x: Num -> Num)
```
**Parameters:**
@ -442,9 +442,9 @@ The value of \( 2^x \).
**Description:**
Computes the exponential function \( e^x \) for a number.
**Usage:**
**Signature:**
```tomo
exp(x: Num -> Num)
func exp(x: Num -> Num)
```
**Parameters:**
@ -467,9 +467,9 @@ The value of \( e^x \).
**Description:**
Computes \( e^x - 1 \) for a number.
**Usage:**
**Signature:**
```tomo
expm1(x: Num -> Num)
func expm1(x: Num -> Num)
```
**Parameters:**
@ -492,9 +492,9 @@ The value of \( e^x - 1 \).
**Description:**
Computes the positive difference between two numbers.
**Usage:**
**Signature:**
```tomo
fdim(x: Num, y: Num -> Num)
func fdim(x: Num, y: Num -> Num)
```
**Parameters:**
@ -520,9 +520,9 @@ fd
**Description:**
Rounds a number down to the nearest integer.
**Usage:**
**Signature:**
```tomo
floor(x: Num -> Num)
func floor(x: Num -> Num)
```
**Parameters:**
@ -545,9 +545,9 @@ The largest integer less than or equal to `x`.
**Description:**
Formats a number as a string with a specified precision.
**Usage:**
**Signature:**
```tomo
format(n: Num, precision: Int = 0 -> Text)
func format(n: Num, precision: Int = 0 -> Text)
```
**Parameters:**
@ -571,9 +571,9 @@ A string representation of the number with the specified precision.
**Description:**
Converts a string representation of a number into a floating-point number.
**Usage:**
**Signature:**
```tomo
from_text(text: Text, the_rest: Text = "!&Text" -> Num)
func from_text(text: Text, the_rest: Text = "!&Text" -> Num)
```
**Parameters:**
@ -599,9 +599,9 @@ The number represented by the string.
**Description:**
Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
**Usage:**
**Signature:**
```tomo
hypot(x: Num, y: Num -> Num)
func hypot(x: Num, y: Num -> Num)
```
**Parameters:**
@ -625,9 +625,9 @@ The Euclidean norm of `x` and `y`.
**Description:**
Checks if a number is finite.
**Usage:**
**Signature:**
```tomo
isfinite(n: Num -> Bool)
func isfinite(n: Num -> Bool)
```
**Parameters:**
@ -652,9 +652,9 @@ isfinite(n: Num -> Bool)
**Description:**
Checks if a number is infinite.
**Usage:**
**Signature:**
```tomo
isinf(n: Num -> Bool)
func isinf(n: Num -> Bool)
```
**Parameters:**
@ -679,9 +679,9 @@ isinf(n: Num -> Bool)
**Description:**
Checks if a number is NaN (Not a Number).
**Usage:**
**Signature:**
```tomo
isnan(n: Num -> Bool)
func isnan(n: Num -> Bool)
```
**Parameters:**
@ -706,9 +706,9 @@ isnan(n: Num -> Bool)
**Description:**
Computes the Bessel function of the first kind of order 0.
**Usage:**
**Signature:**
```tomo
j0(x: Num -> Num)
func j0(x: Num -> Num)
```
**Parameters:**
@ -731,9 +731,9 @@ The Bessel function of the first kind of order 0 of `x`.
**Description:**
Computes the Bessel function of the first kind of order 1.
**Usage:**
**Signature:**
```tomo
j1(x: Num -> Num)
func j1(x: Num -> Num)
```
**Parameters:**
@ -756,9 +756,9 @@ The Bessel function of the first kind of order 1 of `x`.
**Description:**
Computes the base-10 logarithm of a number.
**Usage:**
**Signature:**
```tomo
log10(x: Num -> Num)
func log10(x: Num -> Num)
```
**Parameters:**
@ -781,9 +781,9 @@ The base-10 logarithm of `x`.
**Description:**
Computes \( \log(1 + x) \) for a number.
**Usage:**
**Signature:**
```tomo
log1p(x: Num -> Num)
func log1p(x: Num -> Num)
```
**Parameters:**
@ -806,9 +806,9 @@ The value of \( \log(1 + x) \).
**Description:**
Computes the base-2 logarithm of a number.
**Usage:**
**Signature:**
```tomo
log2(x: Num -> Num)
func log2(x: Num -> Num)
```
**Parameters:**
@ -831,9 +831,9 @@ The base-2 logarithm of `x`.
**Description:**
Computes the natural logarithm (base \( e \)) of a number.
**Usage:**
**Signature:**
```tomo
log(x: Num -> Num)
func log(x: Num -> Num)
```
**Parameters:**
@ -856,9 +856,9 @@ The natural logarithm of `x`.
**Description:**
Computes the binary exponent (base-2 logarithm) of a number.
**Usage:**
**Signature:**
```tomo
logb(x: Num -> Num)
func logb(x: Num -> Num)
```
**Parameters:**
@ -881,9 +881,9 @@ The binary exponent of `x`.
**Description:**
Interpolates between two numbers based on a given amount.
**Usage:**
**Signature:**
```tomo
mix(amount: Num, x: Num, y: Num -> Num)
func mix(amount: Num, x: Num, y: Num -> Num)
```
**Parameters:**
@ -910,9 +910,9 @@ The interpolated number between `x` and `y` based on `amount`.
**Description:**
Generates a NaN (Not a Number) value.
**Usage:**
**Signature:**
```tomo
nan(tag: Text = "" -> Num)
func nan(tag: Text = "" -> Num)
```
**Parameters:**
@ -937,9 +937,9 @@ Checks if two numbers are approximately equal within specified tolerances. If
two numbers are within an absolute difference or the ratio between the two is
small enough, they are considered near each other.
**Usage:**
**Signature:**
```tomo
near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
```
**Parameters:**
@ -971,9 +971,9 @@ near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
**Description:**
Computes the next representable value after a given number towards a specified direction.
**Usage:**
**Signature:**
```tomo
nextafter(x: Num, y: Num -> Num)
func nextafter(x: Num, y: Num -> Num)
```
**Parameters:**
@ -997,9 +997,9 @@ The next representable value after `x` in the direction of `y`.
**Description:**
Generates a random floating-point number.
**Usage:**
**Signature:**
```tomo
random(->Num)
func random(->Num)
```
**Parameters:**
@ -1021,9 +1021,9 @@ A random floating-point number between 0 and 1.
**Description:**
Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
**Usage:**
**Signature:**
```tomo
rint(x: Num -> Num)
func rint(x: Num -> Num)
```
**Parameters:**
@ -1048,9 +1048,9 @@ The nearest integer value of `x`.
**Description:**
Rounds a number to the nearest whole number integer.
**Usage:**
**Signature:**
```tomo
round(x: Num -> Num)
func round(x: Num -> Num)
```
**Parameters:**
@ -1075,9 +1075,9 @@ The nearest integer value of `x`.
**Description:**
Formats a number in scientific notation with a specified precision.
**Usage:**
**Signature:**
```tomo
scientific(n: Num, precision: Int = 0 -> Text)
func scientific(n: Num, precision: Int = 0 -> Text)
```
**Parameters:**
@ -1101,9 +1101,9 @@ A string representation of the number in scientific notation with the specified
**Description:**
Extracts the significand (or mantissa) of a number.
**Usage:**
**Signature:**
```tomo
significand(x: Num -> Num)
func significand(x: Num -> Num)
```
**Parameters:**
@ -1126,9 +1126,9 @@ The significand of `x`.
**Description:**
Computes the sine of a number (angle in radians).
**Usage:**
**Signature:**
```tomo
sin(x: Num -> Num)
func sin(x: Num -> Num)
```
**Parameters:**
@ -1151,9 +1151,9 @@ The sine of `x`.
**Description:**
Computes the hyperbolic sine of a number.
**Usage:**
**Signature:**
```tomo
sinh(x: Num -> Num)
func sinh(x: Num -> Num)
```
**Parameters:**
@ -1176,9 +1176,9 @@ The hyperbolic sine of `x`.
**Description:**
Computes the square root of a number.
**Usage:**
**Signature:**
```tomo
sqrt(x: Num -> Num)
func sqrt(x: Num -> Num)
```
**Parameters:**
@ -1201,9 +1201,9 @@ The square root of `x`.
**Description:**
Computes the tangent of a number (angle in radians).
**Usage:**
**Signature:**
```tomo
tan(x: Num -> Num)
func tan(x: Num -> Num)
```
**Parameters:**
@ -1226,9 +1226,9 @@ The tangent of `x`.
**Description:**
Computes the hyperbolic tangent of a number.
**Usage:**
**Signature:**
```tomo
tanh(x: Num -> Num)
func tanh(x: Num -> Num)
```
**Parameters:**
@ -1251,9 +1251,9 @@ The hyperbolic tangent of `x`.
**Description:**
Computes the gamma function of a number.
**Usage:**
**Signature:**
```tomo
tgamma(x: Num -> Num)
func tgamma(x: Num -> Num)
```
**Parameters:**
@ -1276,9 +1276,9 @@ The gamma function of `x`.
**Description:**
Truncates a number to the nearest integer towards zero.
**Usage:**
**Signature:**
```tomo
trunc(x: Num -> Num)
func trunc(x: Num -> Num)
```
**Parameters:**
@ -1303,9 +1303,9 @@ The integer part of `x` towards zero.
**Description:**
Computes the Bessel function of the second kind of order 0.
**Usage:**
**Signature:**
```tomo
y0(x: Num -> Num)
func y0(x: Num -> Num)
```
**Parameters:**
@ -1328,9 +1328,9 @@ The Bessel function of the second kind of order 0 of `x`.
**Description:**
Computes the Bessel function of the second kind of order 1.
**Usage:**
**Signature:**
```tomo
y1(x: Num -> Num)
func y1(x: Num -> Num)
```
**Parameters:**
@ -1354,7 +1354,7 @@ The Bessel function of the second kind of order 1 of `x`.
Returns the given number clamped between two values so that it is within
that range.
**Usage:**
**Signature:**
```tomo
clamped(x, low, high: Num -> Num)
```

198
docs/paths.md
View File

@ -43,9 +43,9 @@ intended. Paths can be created from text with slashes using
Appends the given text to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
**Usage:**
```markdown
append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
**Signature:**
```tomo
func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
```
**Parameters:**
@ -58,7 +58,7 @@ append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./log.txt):append("extra line$(\n)")
```
@ -70,9 +70,9 @@ Nothing.
Appends the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
**Usage:**
```markdown
append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
**Signature:**
```tomo
func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
```
**Parameters:**
@ -85,7 +85,7 @@ append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./log.txt):append_bytes([104[B], 105[B]])
```
@ -96,9 +96,9 @@ Nothing.
**Description:**
Returns the base name of the file or directory at the specified path.
**Usage:**
```markdown
base_name(path: Path -> Text)
**Signature:**
```tomo
func base_name(path: Path -> Text)
```
**Parameters:**
@ -109,7 +109,7 @@ base_name(path: Path -> Text)
The base name of the file or directory.
**Example:**
```markdown
```tomo
>> (./path/to/file.txt):base_name()
= "file.txt"
```
@ -122,9 +122,9 @@ The base name of the file or directory.
Returns an iterator that can be used to iterate over a file one line at a time,
or returns a null value if the file could not be opened.
**Usage:**
```markdown
by_line(path: Path -> func(->Text?)?)
**Signature:**
```tomo
func by_line(path: Path -> func(->Text?)?)
```
**Parameters:**
@ -136,7 +136,7 @@ An iterator that can be used to get lines from a file one at a time or a null
value if the file couldn't be read.
**Example:**
```markdown
```tomo
# Safely handle file not being readable:
if lines := (./file.txt):by_line():
for line in lines:
@ -156,9 +156,9 @@ for line in (/dev/stdin):by_line()!:
**Description:**
Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files.
**Usage:**
```markdown
children(path: Path, include_hidden=no -> [Path])
**Signature:**
```tomo
func children(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
@ -170,7 +170,7 @@ children(path: Path, include_hidden=no -> [Path])
A list of paths for the children.
**Example:**
```markdown
```tomo
>> (./directory):children(include_hidden=yes)
= [".git", "foo.txt"]
```
@ -183,9 +183,9 @@ A list of paths for the children.
Creates a new directory at the specified path with the given permissions. If
any of the parent directories do not exist, they will be created as needed.
**Usage:**
```markdown
create_directory(path: Path, permissions=0o755[32] -> Void)
**Signature:**
```tomo
func create_directory(path: Path, permissions=0o755[32] -> Void)
```
**Parameters:**
@ -197,7 +197,7 @@ create_directory(path: Path, permissions=0o755[32] -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./new_directory):create_directory()
```
@ -208,9 +208,9 @@ Nothing.
**Description:**
Checks if a file or directory exists at the specified path.
**Usage:**
```markdown
exists(path: Path -> Bool)
**Signature:**
```tomo
func exists(path: Path -> Bool)
```
**Parameters:**
@ -221,7 +221,7 @@ exists(path: Path -> Bool)
`True` if the file or directory exists, `False` otherwise.
**Example:**
```markdown
```tomo
>> (/):exists()
= yes
```
@ -233,9 +233,9 @@ exists(path: Path -> Bool)
**Description:**
Returns the file extension of the file at the specified path. Optionally returns the full extension.
**Usage:**
```markdown
extension(path: Path, full=yes -> Text)
**Signature:**
```tomo
func extension(path: Path, full=yes -> Text)
```
**Parameters:**
@ -249,7 +249,7 @@ The file extension (not including the leading `.`) or an empty text if there is
no file extension.
**Example:**
```markdown
```tomo
>> (./file.tar.gz):extension()
= "tar.gz"
>> (./file.tar.gz):extension(full=no)
@ -267,9 +267,9 @@ no file extension.
**Description:**
Returns a list of files within the directory at the specified path. Optionally includes hidden files.
**Usage:**
```markdown
files(path: Path, include_hidden=no -> [Path])
**Signature:**
```tomo
func files(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
@ -281,7 +281,7 @@ files(path: Path, include_hidden=no -> [Path])
A list of file paths.
**Example:**
```markdown
```tomo
>> (./directory):files(include_hidden=yes)
= [(./directory/file1.txt), (./directory/file2.txt)]
```
@ -293,9 +293,9 @@ A list of file paths.
**Description:**
Checks if the path represents a directory. Optionally follows symbolic links.
**Usage:**
```markdown
is_directory(path: Path, follow_symlinks=yes -> Bool)
**Signature:**
```tomo
func is_directory(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
@ -307,7 +307,7 @@ is_directory(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a directory, `False` otherwise.
**Example:**
```markdown
```tomo
>> (./directory/):is_directory()
= yes
@ -322,9 +322,9 @@ is_directory(path: Path, follow_symlinks=yes -> Bool)
**Description:**
Checks if the path represents a file. Optionally follows symbolic links.
**Usage:**
```markdown
is_file(path: Path, follow_symlinks=yes -> Bool)
**Signature:**
```tomo
func is_file(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
@ -336,7 +336,7 @@ is_file(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a file, `False` otherwise.
**Example:**
```markdown
```tomo
>> (./file.txt):is_file()
= yes
@ -351,9 +351,9 @@ is_file(path: Path, follow_symlinks=yes -> Bool)
**Description:**
Checks if the path represents a socket. Optionally follows symbolic links.
**Usage:**
```markdown
is_socket(path: Path, follow_symlinks=yes -> Bool)
**Signature:**
```tomo
func is_socket(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
@ -365,7 +365,7 @@ is_socket(path: Path, follow_symlinks=yes -> Bool)
`True` if the path is a socket, `False` otherwise.
**Example:**
```markdown
```tomo
>> (./socket):is_socket()
= yes
```
@ -377,9 +377,9 @@ is_socket(path: Path, follow_symlinks=yes -> Bool)
**Description:**
Checks if the path represents a symbolic link.
**Usage:**
```markdown
is_symlink(path: Path -> Bool)
**Signature:**
```tomo
func is_symlink(path: Path -> Bool)
```
**Parameters:**
@ -390,7 +390,7 @@ is_symlink(path: Path -> Bool)
`True` if the path is a symbolic link, `False` otherwise.
**Example:**
```markdown
```tomo
>> (./link):is_symlink()
= yes
```
@ -402,9 +402,9 @@ is_symlink(path: Path -> Bool)
**Description:**
Returns the parent directory of the file or directory at the specified path.
**Usage:**
```markdown
parent(path: Path -> Path)
**Signature:**
```tomo
func parent(path: Path -> Path)
```
**Parameters:**
@ -415,7 +415,7 @@ parent(path: Path -> Path)
The path of the parent directory.
**Example:**
```markdown
```tomo
>> (./path/to/file.txt):parent()
= (./path/to/)
```
@ -428,9 +428,9 @@ The path of the parent directory.
Reads the contents of the file at the specified path or a null value if the
file could not be read.
**Usage:**
```markdown
read(path: Path -> Text?)
**Signature:**
```tomo
func read(path: Path -> Text?)
```
**Parameters:**
@ -443,7 +443,7 @@ returned. If the file can be read, but is not valid UTF8 data, an error will be
raised.
**Example:**
```markdown
```tomo
>> (./hello.txt):read()
= "Hello"?
@ -458,9 +458,9 @@ raised.
Reads the contents of the file at the specified path or a null value if the
file could not be read.
**Usage:**
```markdown
read_bytes(path: Path -> [Byte]?)
**Signature:**
```tomo
func read_bytes(path: Path -> [Byte]?)
```
**Parameters:**
@ -472,7 +472,7 @@ The byte contents of the file. If the file cannot be read, a null value will be
returned.
**Example:**
```markdown
```tomo
>> (./hello.txt):read()
= [72[B], 101[B], 108[B], 108[B], 111[B]]?
@ -487,9 +487,9 @@ returned.
**Description:**
Returns the path relative to a given base path. By default, the base path is the current directory.
**Usage:**
```markdown
relative(path: Path, relative_to=(./) -> Path)
**Signature:**
```tomo
func relative(path: Path, relative_to=(./) -> Path)
```
**Parameters:**
@ -501,7 +501,7 @@ relative(path: Path, relative_to=(./) -> Path)
The relative path.
**Example:**
```markdown
```tomo
>> (./path/to/file.txt):relative(relative_to=(./path))
= (./to/file.txt)
```
@ -513,9 +513,9 @@ The relative path.
**Description:**
Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
**Usage:**
```markdown
remove(path: Path, ignore_missing=no -> Void)
**Signature:**
```tomo
func remove(path: Path, ignore_missing=no -> Void)
```
**Parameters:**
@ -527,7 +527,7 @@ remove(path: Path, ignore_missing=no -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./file.txt):remove()
```
@ -538,9 +538,9 @@ Nothing.
**Description:**
Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
**Usage:**
```markdown
resolved(path: Path, relative_to=(./) -> Path)
**Signature:**
```tomo
func resolved(path: Path, relative_to=(./) -> Path)
```
**Parameters:**
@ -552,7 +552,7 @@ resolved(path: Path, relative_to=(./) -> Path)
The resolved absolute path.
**Example:**
```markdown
```tomo
>> (~/foo):resolved()
= (/home/user/foo)
@ -567,9 +567,9 @@ The resolved absolute path.
**Description:**
Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
**Usage:**
```markdown
subdirectories(path: Path, include_hidden=no -> [Path])
**Signature:**
```tomo
func subdirectories(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
@ -581,7 +581,7 @@ subdirectories(path: Path, include_hidden=no -> [Path])
A list of subdirectory paths.
**Example:**
```markdown
```tomo
>> (./directory):subdirectories()
= [(./directory/subdir1), (./directory/subdir2)]
@ -596,9 +596,9 @@ A list of subdirectory paths.
**Description:**
Generates a unique directory path based on the given path. Useful for creating temporary directories.
**Usage:**
```markdown
unique_directory(path: Path -> Path)
**Signature:**
```tomo
func unique_directory(path: Path -> Path)
```
**Parameters:**
@ -627,9 +627,9 @@ Writes the given text to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
**Usage:**
```markdown
write(path: Path, text: Text, permissions=0o644[32] -> Void)
**Signature:**
```tomo
func write(path: Path, text: Text, permissions=0o644[32] -> Void)
```
**Parameters:**
@ -642,7 +642,7 @@ write(path: Path, text: Text, permissions=0o644[32] -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./file.txt):write("Hello, world!")
```
@ -655,9 +655,9 @@ Writes the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
**Usage:**
```markdown
write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
**Signature:**
```tomo
func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
```
**Parameters:**
@ -670,7 +670,7 @@ write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
Nothing.
**Example:**
```markdown
```tomo
(./file.txt):write_bytes([104[B], 105[B]])
```
@ -683,9 +683,9 @@ Writes the given text to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
**Usage:**
```markdown
write_unique(path: Path, text: Text -> Path)
**Signature:**
```tomo
func write_unique(path: Path, text: Text -> Path)
```
**Parameters:**
@ -698,7 +698,7 @@ write_unique(path: Path, text: Text -> Path)
The path of the newly created unique file.
**Example:**
```markdown
```tomo
>> created := (./file-XXXXXX.txt):write_unique("Hello, world!")
= (./file-27QHtq.txt)
>> created:read()
@ -715,9 +715,9 @@ Writes the given bytes to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
**Usage:**
```markdown
write_unique_bytes(path: Path, bytes: [Byte] -> Path)
**Signature:**
```tomo
func write_unique_bytes(path: Path, bytes: [Byte] -> Path)
```
**Parameters:**
@ -730,7 +730,7 @@ write_unique_bytes(path: Path, bytes: [Byte] -> Path)
The path of the newly created unique file.
**Example:**
```markdown
```tomo
>> created := (./file-XXXXXX.txt):write_unique_bytes([1[B], 2[B], 3[B]])
= (./file-27QHtq.txt)
>> created:read()

8
docs/ranges.md
View File

@ -18,9 +18,9 @@ created using the `Int.to()` method like so: `5:to(10)`. Ranges are
**Description:**
Returns a reversed copy of the range.
**Usage:**
**Signature:**
```tomo
reversed(range: Range -> Range)
func reversed(range: Range -> Range)
```
**Parameters:**
@ -43,9 +43,9 @@ A new `Range` with the order of elements reversed.
**Description:**
Creates a new range with a specified step value.
**Usage:**
**Signature:**
```tomo
by(range: Range, step: Int -> Range)
func by(range: Range, step: Int -> Range)
```
**Parameters:**

44
docs/sets.md
View File

@ -80,9 +80,9 @@ iterating over any of the new values.
**Description:**
Checks if the set contains a specified item.
**Usage:**
**Signature:**
```tomo
has(set:{T}, item:T -> Bool)
func has(set:{T}, item:T -> Bool)
```
**Parameters:**
@ -106,9 +106,9 @@ has(set:{T}, item:T -> Bool)
**Description:**
Adds an item to the set.
**Usage:**
**Signature:**
```tomo
add(set:{T}, item: T -> Void)
func add(set:{T}, item: T -> Void)
```
**Parameters:**
@ -131,9 +131,9 @@ Nothing.
**Description:**
Adds multiple items to the set.
**Usage:**
**Signature:**
```tomo
add_all(set:&{T}, items: [T] -> Void)
func add_all(set:&{T}, items: [T] -> Void)
```
**Parameters:**
@ -156,9 +156,9 @@ Nothing.
**Description:**
Removes an item from the set.
**Usage:**
**Signature:**
```tomo
remove(set:&{T}, item: T -> Void)
func remove(set:&{T}, item: T -> Void)
```
**Parameters:**
@ -181,9 +181,9 @@ Nothing.
**Description:**
Removes multiple items from the set.
**Usage:**
**Signature:**
```tomo
remove_all(set:&{T}, items: [T] -> Void)
func remove_all(set:&{T}, items: [T] -> Void)
```
**Parameters:**
@ -206,9 +206,9 @@ Nothing.
**Description:**
Removes all items from the set.
**Usage:**
**Signature:**
```tomo
clear(set:&{T} -> Void)
func clear(set:&{T} -> Void)
```
**Parameters:**
@ -230,9 +230,9 @@ Nothing.
**Description:**
Creates a new set that is the union of the original set and another set.
**Usage:**
**Signature:**
```tomo
with(set:{T}, other: {T} -> {T})
func with(set:{T}, other: {T} -> {T})
```
**Parameters:**
@ -256,9 +256,9 @@ A new set containing all items from both sets.
**Description:**
Creates a new set with items that are in both the original set and another set.
**Usage:**
**Signature:**
```tomo
overlap(set:{T}, other: {T} -> {T})
func overlap(set:{T}, other: {T} -> {T})
```
**Parameters:**
@ -282,9 +282,9 @@ A new set containing only items present in both sets.
**Description:**
Creates a new set with items from the original set but without items from another set.
**Usage:**
**Signature:**
```tomo
without(set:{T}, other: {T} -> {T})
func without(set:{T}, other: {T} -> {T})
```
**Parameters:**
@ -308,9 +308,9 @@ A new set containing items from the original set excluding those in the other se
**Description:**
Checks if the set is a subset of another set.
**Usage:**
**Signature:**
```tomo
set:is_subset_of(other: {T}, strict: Bool = no -> Bool)
func (set: {T}, other: {T}, strict: Bool = no -> Bool)
```
**Parameters:**
@ -335,9 +335,9 @@ set:is_subset_of(other: {T}, strict: Bool = no -> Bool)
**Description:**
Checks if the set is a superset of another set.
**Usage:**
**Signature:**
```tomo
is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
```
**Parameters:**

56
docs/tables.md
View File

@ -116,14 +116,14 @@ iterating over any of the new values.
Increments the value associated with a key by a specified amount. If the key is
not already in the table, its value will be assumed to be zero.
**Usage:**
```markdown
bump(t:{K:V}, key: K, amount: Int = 1 -> Void)
**Signature:**
```tomo
func bump(t:&{K:V}, key: K, amount: Int = 1 -> Void)
```
**Parameters:**
- `t`: The mutable reference to the table.
- `t`: The reference to the table.
- `key`: The key whose value is to be incremented.
- `amount`: The amount to increment the value by (default: 1).
@ -131,7 +131,7 @@ bump(t:{K:V}, key: K, amount: Int = 1 -> Void)
Nothing.
**Example:**
```markdown
```tomo
>> t := {"A":1}
t:bump("A")
t:bump("B", 10)
@ -146,20 +146,20 @@ t:bump("B", 10)
**Description:**
Removes all key-value pairs from the table.
**Usage:**
```markdown
t:clear()
**Signature:**
```tomo
func clear(t:&{K:V})
```
**Parameters:**
- `t`: The mutable reference to the table.
- `t`: The reference to the table.
**Returns:**
Nothing.
**Example:**
```markdown
```tomo
>> t:clear()
```
@ -170,9 +170,9 @@ Nothing.
**Description:**
Retrieves the value associated with a key, or returns null if the key is not present.
**Usage:**
```markdown
t:get(key: K -> V?)
**Signature:**
```tomo
func get(t:{K:V}, key: K -> V?)
```
**Parameters:**
@ -184,7 +184,7 @@ t:get(key: K -> V?)
The value associated with the key or null if the key is not found.
**Example:**
```markdown
```tomo
>> t := {"A":1, "B":2}
>> t:get("A")
= 1? : Int?
@ -206,9 +206,9 @@ The value associated with the key or null if the key is not found.
**Description:**
Checks if the table contains a specified key.
**Usage:**
```markdown
has(t:{K:V}, key: K -> Bool)
**Signature:**
```tomo
func has(t:{K:V}, key: K -> Bool)
```
**Parameters:**
@ -220,7 +220,7 @@ has(t:{K:V}, key: K -> Bool)
`yes` if the key is present, `no` otherwise.
**Example:**
```markdown
```tomo
>> {"A":1, "B":2}:has("A")
= yes
>> {"A":1, "B":2}:has("xxx")
@ -234,21 +234,21 @@ has(t:{K:V}, key: K -> Bool)
**Description:**
Removes the key-value pair associated with a specified key.
**Usage:**
```markdown
remove(t:{K:V}, key: K -> Void)
**Signature:**
```tomo
func remove(t:{K:V}, key: K -> Void)
```
**Parameters:**
- `t`: The mutable reference to the table.
- `t`: The reference to the table.
- `key`: The key of the key-value pair to remove.
**Returns:**
Nothing.
**Example:**
```markdown
```tomo
t := {"A":1, "B":2}
t:remove("A")
>> t
@ -262,14 +262,14 @@ t:remove("A")
**Description:**
Sets or updates the value associated with a specified key.
**Usage:**
```markdown
set(t:{K:V}, key: K, value: V -> Void)
**Signature:**
```tomo
func set(t:{K:V}, key: K, value: V -> Void)
```
**Parameters:**
- `t`: The mutable reference to the table.
- `t`: The reference to the table.
- `key`: The key to set or update.
- `value`: The value to associate with the key.
@ -277,7 +277,7 @@ set(t:{K:V}, key: K, value: V -> Void)
Nothing.
**Example:**
```markdown
```tomo
t := {"A": 1, "B": 2}
t:set("C", 3)
>> t

104
docs/text.md
View File

@ -400,9 +400,9 @@ many repetitions you want by putting a number or range of numbers first using
**Description:**
Converts a `Text` value to a C-style string.
**Usage:**
**Signature:**
```tomo
as_c_string(text: Text -> CString)
func as_c_string(text: Text -> CString)
```
**Parameters:**
@ -426,9 +426,9 @@ A C-style string (`CString`) representing the text.
Converts a `Text` value to an array of bytes representing a UTF8 encoding of
the text.
**Usage:**
**Signature:**
```tomo
utf8_bytes(text: Text -> [Byte])
func utf8_bytes(text: Text -> [Byte])
```
**Parameters:**
@ -451,9 +451,9 @@ An array of bytes (`[Byte]`) representing the text in UTF8 encoding.
**Description:**
Returns an array of the names of each codepoint in the text.
**Usage:**
**Signature:**
```tomo
codepoint_names(text: Text -> [Text])
func codepoint_names(text: Text -> [Text])
```
**Parameters:**
@ -476,9 +476,9 @@ An array of codepoint names (`[Text]`).
**Description:**
Returns an array of Unicode code points for UTF32 encoding of the text.
**Usage:**
**Signature:**
```tomo
utf32_codepoints(text: Text -> [Int32])
func utf32_codepoints(text: Text -> [Int32])
```
**Parameters:**
@ -501,9 +501,9 @@ An array of 32-bit integer Unicode code points (`[Int32]`).
**Description:**
Checks if the `Text` ends with a literal suffix text.
**Usage:**
**Signature:**
```tomo
ends_with(text: Text, suffix: Text -> Bool)
func ends_with(text: Text, suffix: Text -> Bool)
```
**Parameters:**
@ -527,9 +527,9 @@ ends_with(text: Text, suffix: Text -> Bool)
**Description:**
Converts a C-style string to a `Text` value.
**Usage:**
**Signature:**
```tomo
from_c_string(str: CString -> Text)
func from_c_string(str: CString -> Text)
```
**Parameters:**
@ -554,9 +554,9 @@ 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.
**Usage:**
**Signature:**
```tomo
from_codepoint_names(codepoint_names: [Text] -> [Text])
func from_codepoint_names(codepoint_names: [Text] -> [Text])
```
**Parameters:**
@ -587,9 +587,9 @@ 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.
**Usage:**
**Signature:**
```tomo
from_codepoint_names(codepoints: [Int32] -> [Text])
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
@ -614,9 +614,9 @@ 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.
**Usage:**
**Signature:**
```tomo
from_codepoint_names(codepoints: [Int32] -> [Text])
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
@ -640,9 +640,9 @@ A new text based on the input UTF8 bytes after normalization has been applied.
Finds the first occurrence of a pattern in the given text (if any).
See: [Patterns](#Patterns) for more information on patterns.
**Usage:**
**Signature:**
```tomo
find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int64 -> Int)
func find(text: Text, pattern: Pattern, start: Int = 1, length: &Int64? = !&Int64 -> Int)
```
**Parameters:**
@ -683,9 +683,9 @@ found.
Finds all occurrences of a pattern in the given text.
See: [Patterns](#Patterns) for more information on patterns.
**Usage:**
**Signature:**
```tomo
find_all(text: Text, pattern: Pattern -> [Text])
func find_all(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
@ -725,9 +725,9 @@ Note: if `text` or `pattern` is empty, an empty array will be returned.
**Description:**
Checks if the `Text` contains a target pattern (see: [Patterns](#Patterns)).
**Usage:**
**Signature:**
```tomo
has(text: Text, pattern: Pattern -> Bool)
func has(text: Text, pattern: Pattern -> Bool)
```
**Parameters:**
@ -757,9 +757,9 @@ has(text: Text, pattern: Pattern -> Bool)
**Description:**
Joins an array of text pieces with a specified glue.
**Usage:**
**Signature:**
```tomo
join(glue: Text, pieces: [Text] -> Text)
func join(glue: Text, pieces: [Text] -> Text)
```
**Parameters:**
@ -784,9 +784,9 @@ A single `Text` value with the pieces joined by the glue.
Splits the text into an array of lines of text, preserving blank lines,
ignoring trailing newlines, and handling `\r\n` the same as `\n`.
**Usage:**
**Signature:**
```tomo
split(text: Text -> [Text])
func split(text: Text -> [Text])
```
**Parameters:**
@ -817,9 +817,9 @@ An array of substrings resulting from the split.
**Description:**
Converts all characters in the text to lowercase.
**Usage:**
**Signature:**
```tomo
lower(text: Text -> Text)
func lower(text: Text -> Text)
```
**Parameters:**
@ -844,9 +844,9 @@ Checks if the `Text` matches target pattern (see: [Patterns](#Patterns)) and
returns an array of the matching texts or a null value if the entire text
doesn't match the pattern.
**Usage:**
**Signature:**
```tomo
matches(text: Text, pattern: Pattern -> [Text])
func matches(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
@ -875,9 +875,9 @@ a null value otherwise.
For each occurrence of the given pattern, replace the text with the result of
calling the given function on that text.
**Usage:**
**Signature:**
```tomo
map(text: Text, pattern: Pattern, fn: func(text:Text)->Text -> Text)
func map(text: Text, pattern: Pattern, fn: func(text:Text)->Text -> Text)
```
**Parameters:**
@ -905,9 +905,9 @@ function to each.
**Description:**
Formats the text as a quoted string.
**Usage:**
**Signature:**
```tomo
quoted(text: Text, color: Bool = no -> Text)
func quoted(text: Text, color: Bool = no -> Text)
```
**Parameters:**
@ -931,9 +931,9 @@ The text formatted as a quoted string.
**Description:**
Repeat some text multiple times.
**Usage:**
**Signature:**
```tomo
repeat(text: Text, count:Int -> Text)
func repeat(text: Text, count:Int -> Text)
```
**Parameters:**
@ -959,9 +959,9 @@ Replaces occurrences of a pattern in the text with a replacement string.
See [Patterns](#patterns) for more information about patterns.
**Usage:**
**Signature:**
```tomo
replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)
func replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)
```
**Parameters:**
@ -1028,9 +1028,9 @@ matching pattern's replacement is applied and the pattern matching moves on to
*after* the replacement text, so replacement text is not recursively modified.
See [`replace()`](#replace) for more information about replacement behavior.
**Usage:**
**Signature:**
```tomo
replace_all(replacements:{Pattern:Text}, backref: Pattern = $/\/ -> Text)
func replace_all(replacements:{Pattern:Text}, backref: Pattern = $/\/ -> Text)
```
**Parameters:**
@ -1073,9 +1073,9 @@ replacement text.
Splits the text into an array of substrings based on a pattern.
See [Patterns](#patterns) for more information about patterns.
**Usage:**
**Signature:**
```tomo
split(text: Text, pattern: Pattern = "" -> [Text])
func split(text: Text, pattern: Pattern = "" -> [Text])
```
**Parameters:**
@ -1109,9 +1109,9 @@ An array of substrings resulting from the split.
**Description:**
Checks if the `Text` starts with a literal prefix text.
**Usage:**
**Signature:**
```tomo
starts_with(text: Text, prefix: Text -> Bool)
func starts_with(text: Text, prefix: Text -> Bool)
```
**Parameters:**
@ -1135,9 +1135,9 @@ starts_with(text: Text, prefix: Text -> Bool)
**Description:**
Converts the text to title case (capitalizing the first letter of each word).
**Usage:**
**Signature:**
```tomo
title(text: Text -> Text)
func title(text: Text -> Text)
```
**Parameters:**
@ -1161,9 +1161,9 @@ The text in title case.
Trims the matching pattern from the left and/or right side of the text
See [Patterns](#patterns) for more information about patterns.
**Usage:**
**Signature:**
```tomo
trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)
func trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)
```
**Parameters:**
@ -1195,9 +1195,9 @@ The text without the trim pattern at either end.
**Description:**
Converts all characters in the text to uppercase.
**Usage:**
**Signature:**
```tomo
upper(text: Text -> Text)
func upper(text: Text -> Text)
```
**Parameters:**

16
docs/threads.md
View File

@ -11,9 +11,9 @@ through thread-safe Channels with no other shared data.
**Description:**
Creates a new thread to execute a specified function.
**Usage:**
**Signature:**
```tomo
Thread.new(fn: func(->Void) -> Thread)
func new(fn: func(->Void) -> Thread)
```
**Parameters:**
@ -45,9 +45,9 @@ A new `Thread` object representing the created thread.
**Description:**
Requests the cancellation of a specified thread.
**Usage:**
**Signature:**
```tomo
cancel(thread: Thread)
func cancel(thread: Thread)
```
**Parameters:**
@ -69,9 +69,9 @@ Nothing.
**Description:**
Waits for a specified thread to terminate.
**Usage:**
**Signature:**
```tomo
join(thread: Thread)
func join(thread: Thread)
```
**Parameters:**
@ -93,9 +93,9 @@ Nothing.
**Description:**
Detaches a specified thread, allowing it to run independently.
**Usage:**
**Signature:**
```tomo
detach(thread: Thread)
func detach(thread: Thread)
```
**Parameters:**