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

API documentation

Browse Source
This commit is contained in:
Bruce Hill 2024-08-18 18:23:32 -04:00
parent a86eba55d7
commit 43b4af23f8
7 changed files with 1533 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

669
api/arrays.md Normal file
View File

@ -0,0 +1,669 @@
# Arrays
Tomo supports arrays as a container type that holds a list of elements of any
type in a compact format. Arrays are immutable by default, but use
copy-on-write semantics to efficiently mutate in place when possible. **Arrays
are 1-indexed**, which means the first item in the array has index `1`.
```tomo
nums := [10, 20, 30]
```
## Array Methods
### `binary_search`
**Description:**
Performs a binary search on a sorted array.
**Usage:**
```markdown
binary_search(arr: [T], by=T.compare) -> Int
```
**Parameters:**
- `arr`: The sorted array to search.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
Assuming the input array is sorted according to the given comparison function,
return the index where the given item would be inserted to maintain the sorted
order.
**Example:**
```markdown
>> [1, 3, 5, 7, 9]:binary_search(5)
= 3
>> [1, 3, 5, 7, 9]:binary_search(-999)
= 1
>> [1, 3, 5, 7, 9]:binary_search(999)
= 6
```
---
### `by`
**Description:**
Creates a new array with elements spaced by the specified step value.
**Usage:**
```markdown
by(arr: [T], step: Int) -> [T]
```
**Parameters:**
- `arr`: The original array.
- `step`: The step value for selecting elements.
**Returns:**
A new array with every `step`-th element from the original array.
**Example:**
```markdown
>> [1, 2, 3, 4, 5, 6]:by(2)
= [1, 3, 5]
```
---
### `clear`
**Description:**
Clears all elements from the array.
**Usage:**
```markdown
clear(arr: & [T]) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array to be cleared.
**Returns:**
Nothing.
**Example:**
```markdown
>> my_array:clear()
```
---
### `counts`
**Description:**
Counts the occurrences of each element in the array.
**Usage:**
```markdown
counts(arr: [T]) -> {T: Int}
```
**Parameters:**
- `arr`: The array to count elements in.
**Returns:**
A table mapping each element to its count.
**Example:**
```markdown
>> [10, 20, 30, 30, 30]:counts()
= {10: 1, 20: 1, 30: 3}
```
---
### `find`
**Description:**
Finds the index of the first occurrence of an element.
**Usage:**
```markdown
find(arr: [T]) -> Int
```
**Parameters:**
- `arr`: The array to search through.
**Returns:**
The index of the first occurrence or `-1` if not found.
**Example:**
```markdown
>> [10, 20, 30, 40, 50]:find(20)
= 2
>> [10, 20, 30, 40, 50]:find(9999)
= -1
```
---
### `from`
**Description:**
Returns a slice of the array starting from a specified index.
**Usage:**
```markdown
from(arr: [T], first: Int) -> [T]
```
**Parameters:**
- `arr`: The original array.
- `first`: The index to start from.
**Returns:**
A new array starting from the specified index.
**Example:**
```markdown
>> [10, 20, 30, 40, 50]:from(3)
= [30, 40, 50]
```
---
### `has`
**Description:**
Checks if the array has any elements.
**Usage:**
```markdown
has(arr: [T]) -> Bool
```
**Parameters:**
- `arr`: The array to check.
**Returns:**
`yes` if the array has elements, `no` otherwise.
**Example:**
```markdown
>> [10, 20, 30]:has(20)
= yes
```
---
### `heap_pop`
**Description:**
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
```
**Parameters:**
- `arr`: The mutable reference to the heap.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
The removed top element of the heap.
**Example:**
```markdown
>> my_heap := [30, 10, 20]
>> my_heap:heapify()
>> my_heap:heap_pop()
= 10
```
---
### `heap_push`
**Description:**
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
```
**Parameters:**
- `arr`: The mutable reference to the heap.
- `item`: The item to be added.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
Nothing.
**Example:**
```markdown
>> my_heap:heap_push(10)
```
---
### `heapify`
**Description:**
Converts an array into a heap.
**Usage:**
```markdown
heapify(arr: & [T], by=T.compare) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array to be heapified.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
Nothing.
**Example:**
```markdown
>> my_heap := [30, 10, 20]
>> my_heap:heapify()
```
---
### `insert`
**Description:**
Inserts an element at a specified position in the array.
**Usage:**
```markdown
insert(arr: & [T], item: T, at: Int = 0) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array.
- `item`: The item to be inserted.
- `at`: The index at which to insert the item (default is `0`). Since indices
are 1-indexed and negative indices mean "starting from the back", an index of
`0` means "after the last item".
**Returns:**
Nothing.
**Example:**
```markdown
>> arr := [10, 20]
>> arr:insert(30)
>> arr
= [10, 20, 30]
>> arr:insert(999, at=2)
>> arr
= [10, 999, 20, 30]
```
---
### `insert_all`
**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
```
**Parameters:**
- `arr`: The mutable reference to the array.
- `items`: The items to be inserted.
- `at`: The index at which to insert the item (default is `0`). Since indices
are 1-indexed and negative indices mean "starting from the back", an index of
`0` means "after the last item".
**Returns:**
Nothing.
**Example:**
```markdown
arr := [10, 20]
arr:insert_all([30, 40])
>> arr
= [10, 20, 30, 40]
arr:insert_all([99, 100], at=2)
>> arr
= [10, 99, 100, 20, 30, 40]
```
---
### `random`
**Description:**
Selects a random element from the array.
**Usage:**
```markdown
random(arr: [T]) -> T
```
**Parameters:**
- `arr`: The array from which to select a random element.
**Returns:**
A random element from the array.
**Example:**
```markdown
>> [10, 20, 30]:random()
= 20
```
---
### `remove_at`
**Description:**
Removes elements from the array starting at a specified index.
**Usage:**
```markdown
remove_at(arr: & [T], at: Int = -1, count: Int = 1) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array.
- `at`: The index at which to start removing elements (default is `-1`, which means the end of the array).
- `count`: The number of elements to remove (default is `1`).
**Returns:**
Nothing.
**Example:**
```markdown
arr := [10, 20, 30, 40, 50]
arr:remove_at(2)
>> arr
= [10, 30, 40, 50]
arr:remove_at(2, count=2)
>> arr
= [10, 50]
```
---
### `remove_item`
**Description:**
Removes all occurrences of a specified item from the array.
**Usage:**
```markdown
remove_item(arr: & [T], item: T, max_count: Int = -1) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array.
- `item`: The item to be removed.
- `max_count`: The maximum number of occurrences to remove (default is `-1`, meaning all occurrences).
**Returns:**
Nothing.
**Example:**
```markdown
arr := [10, 20, 10, 20, 30]
arr:remove_item(10)
>> arr
= [20, 20, 30]
arr:remove_item(20, max_count=1)
>> arr
= [20, 30]
```
---
### `reversed`
**Description:**
Returns a reversed slice of the array.
**Usage:**
```markdown
reversed(arr: [T]) -> [T]
```
**Parameters:**
- `arr`: The array to be reversed.
**Returns:**
A slice of the array with elements in reverse order.
**Example:**
```markdown
>> [10, 20, 30]:reversed()
= [30, 20, 10]
```
---
### `sample`
**Description:**
Selects a sample of elements from the array, optionally with weighted
probabilities.
**Usage:**
```markdown
sample(arr: [T], count: Int, weights: [Num]) -> [T]
```
**Parameters:**
- `arr`: The array to sample from.
- `count`: The number of elements to sample.
- `weights`: The probability weights for each element in the array. These
values do not need to add up to any particular number, they are relative
weights. If no weights are provided, the default is equal probabilities.
Negative, infinite, or NaN weights will cause a runtime error. If the number of
weights given is less than the length of the array, elements from the rest of
the array are considered to have zero weight.
**Returns:**
A list of sampled elements from the array.
**Example:**
```markdown
>> [10, 20, 30]:sample(2, weights=[90%, 5%, 5%])
= [10, 10]
```
---
### `shuffle`
**Description:**
Shuffles the elements of the array in place.
**Usage:**
```markdown
shuffle(arr: & [T]) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array to be shuffled.
**Returns:**
Nothing.
**Example:**
```markdown
>> arr:shuffle()
```
---
### `shuffled`
**Description:**
Creates a new array with elements shuffled.
**Usage:**
```markdown
shuffled(arr: [T]) -> [T]
```
**Parameters:**
- `arr`: The array to be shuffled.
**Returns:**
A new array with shuffled elements.
**Example:**
```markdown
>> [10, 20, 30, 40]:shuffled()
= [40, 10, 30, 20]
```
---
### `sort`
**Description:**
Sorts the elements of the array in place in ascending order (small to large).
**Usage:**
```markdown
sort(arr: & [T], by=T.compare) -> Void
```
**Parameters:**
- `arr`: The mutable reference to the array to be sorted.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
Nothing.
**Example:**
```markdown
arr := [40, 10, -30, 20]
arr:sort()
>> arr
= [-30, 10, 20, 40]
arr:sort(func(a,b:&Int): a:abs() <> b:abs())
>> arr
= [10, 20, -30, 40]
```
---
### `sorted`
**Description:**
Creates a new array with elements sorted.
**Usage:**
```markdown
sorted(arr: [T], by=T.compare) -> [T]
```
**Parameters:**
- `arr`: The array to be sorted.
- `by`: The comparison function used to determine order. If not specified, the
default comparison function for the item type will be used.
**Returns:**
A new array with sorted elements.
**Example:**
```markdown
>> [40, 10, -30, 20]:sorted()
= [-30, 10, 20, 40]
>> [40, 10, -30, 20]:sorted(func(a,b:&Int): a:abs() <> b:abs())
= [10, 20, -30, 40]
```
---
### `to`
**Description:**
Returns a slice of the array from the start of the original array up to a specified index (inclusive).
**Usage:**
```markdown
to(arr: [T], last: Int) -> [T]
```
**Parameters:**
- `arr`: The original array.
- `last`: The index up to which elements should be included.
**Returns:**
A new array containing elements from the start up to the specified index.
**Example:**
```markdown
>> [10, 20, 30, 40, 50]:to(3)
= [10, 20, 30]
>> [10, 20, 30, 40, 50]:to(-2)
= [10, 20, 30, 40]
```
---
### `unique`
**Description:**
Returns a Set that contains the unique elements of the array.
**Usage:**
```markdown
unique(arr: [T]) -> {T}
```
**Parameters:**
- `arr`: The array to process.
**Returns:**
A set containing only unique elements from the array.
**Example:**
```markdown
>> [10, 20, 10, 10, 30]:unique()
= {10, 20, 30}
```

138
api/channels.md Normal file
View File

@ -0,0 +1,138 @@
# Channels
Channels are a thread-safe message queue for communicating between threads,
although they can also be used as a general-purpose queue.
```tomo
channel := |Int|
channel:push(10)
channel:push(20)
>> channel:pop()
= 10
>> channel:pop()
= 20
```
## Channel Methods
### `push`
**Description:**
Adds an item to the channel.
**Usage:**
```markdown
push(channel:|T|, item: T) -> Void
```
**Parameters:**
- `channel`: The channel to which the item will be added.
- `item`: The item to add to the channel.
**Returns:**
Nothing.
**Example:**
```markdown
>> channel:push("Hello")
```
---
### `push_all`
**Description:**
Adds multiple items to the channel.
**Usage:**
```markdown
push_all(channel:|T|, items: [T]) -> Void
```
**Parameters:**
- `channel`: The channel to which the items will be added.
- `items`: The array of items to add to the channel.
**Returns:**
Nothing.
**Example:**
```markdown
>> channel:push_all([1, 2, 3])
```
---
### `pop`
**Description:**
Removes and returns an item from the channel. If the channel is empty, it waits until an item is available.
**Usage:**
```markdown
pop(channel:|T|) -> T
```
**Parameters:**
- `channel`: The channel from which to remove an item.
**Returns:**
The item removed from the channel.
**Example:**
```markdown
>> channel:pop()
= "Hello"
```
---
### `clear`
**Description:**
Removes all items from the channel.
**Usage:**
```markdown
clear(channel:|T|) -> Void
```
**Parameters:**
- `channel`: The mutable reference to the channel.
**Returns:**
Nothing.
**Example:**
```markdown
>> channel:clear()
```
---
### `view`
**Description:**
Returns a list of all items currently in the channel without removing them.
**Usage:**
```markdown
channel:view() -> [T]
```
**Parameters:**
- `channel`: The channel to view.
**Returns:**
An array of items currently in the channel.
**Example:**
```markdown
>> channel:view()
= [1, 2, 3]
```

65
api/ranges.md Normal file
View File

@ -0,0 +1,65 @@
# Ranges
Ranges are Tomo's way to do iteration over numeric ranges. Ranges are typically
created using the `Int.to()` method like so: `5:to(10)`. Ranges are
*inclusive*.
```tomo
>> [i for i in 3:to(5)]
= [3, 4, 5]
```
---
## Range Methods
### `reversed`
**Description:**
Returns a reversed copy of the range.
**Usage:**
```tomo
reversed(range: Range) -> Range
```
**Parameters:**
- `range`: The range to be reversed.
**Returns:**
A new `Range` with the order of elements reversed.
**Example:**
```tomo
>> 1:to(5):reversed()
= Range(first=5, last=1, step=-1)
```
---
### `by`
**Description:**
Creates a new range with a specified step value.
**Usage:**
```tomo
by(range: Range, step: Int) -> Range
```
**Parameters:**
- `range`: The original range.
- `step`: The step value to be used in the new range.
**Returns:**
A new `Range` that increments by the specified step value.
**Example:**
```tomo
>> 1:to(5):by(2)
= Range(first=1, last=5, step=2)
```
---

297
api/sets.md Normal file
View File

@ -0,0 +1,297 @@
# Sets
Sets represent an unordered collection of unique elements. These are
implemented using hash tables.
```tomo
a := {10, 20, 30}
b := {20, 30}
>> a:overlap(b)
= {20}
```
Here’s the Markdown documentation for set functions:
---
## Set Functions
### `has`
**Description:**
Checks if the set contains a specified item.
**Usage:**
```tomo
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
```
---
### `add`
**Description:**
Adds an item to the set.
**Usage:**
```tomo
add(set:{T}, item: T) -> Void
```
**Parameters:**
- `set`: The mutable reference to the set.
- `item`: The item to add to the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:add(42)
```
---
### `add_all`
**Description:**
Adds multiple items to the set.
**Usage:**
```tomo
add_all(set:&{T}, items: [T]) -> Void
```
**Parameters:**
- `set`: The mutable reference to the set.
- `items`: The array of items to add to the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:add_all([1, 2, 3])
```
---
### `remove`
**Description:**
Removes an item from the set.
**Usage:**
```tomo
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.
**Usage:**
```tomo
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:**
Removes all items from the set.
**Usage:**
```tomo
clear(set:&{T}) -> Void
```
**Parameters:**
- `set`: The mutable reference to the set.
**Returns:**
Nothing.
**Example:**
```tomo
>> nums:clear()
```
---
### `with`
**Description:**
Creates a new set that is the union of the original set and another set.
**Usage:**
```tomo
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}
```
---
### `overlap`
**Description:**
Creates a new set with items that are in both the original set and another set.
**Usage:**
```tomo
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.
**Usage:**
```tomo
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}
```
---
### `is_subset_of`
**Description:**
Checks if the set is a subset of another set.
**Usage:**
```tomo
set:is_subset_of(other: {T}, strict: Bool = no) -> Bool
```
**Parameters:**
- `set`: The set to check.
- `other`: The set to compare against.
- `strict`: If `yes`, checks if the set is a strict subset (does not equal the other set).
**Returns:**
`yes` if the set is a subset of the other set (strictly or not), `no` otherwise.
**Example:**
```tomo
>> {1, 2}:is_subset_of({1, 2, 3})
= yes
```
---
### `is_superset_of`
**Description:**
Checks if the set is a superset of another set.
**Usage:**
```tomo
is_superset_of(set:{T}, other: {T}, strict: Bool = no) -> Bool
```
**Parameters:**
- `set`: The set to check.
- `other`: The set to compare against.
- `strict`: If `yes`, checks if the set is a strict superset (does not equal the other set).
**Returns:**
`yes` if the set is a superset of the other set (strictly or not), `no` otherwise.
**Example:**
```tomo
>> {1, 2, 3}:is_superset_of({1, 2})
= yes
```

215
api/tables.md Normal file
View File

@ -0,0 +1,215 @@
# Tables
Tables are Tomo's associative mapping structure, also known as a Dictionary or
Map. Tables are efficiently implemented as a hash table that preserves
insertion order and has fast access to keys and values as array slices. Tables
support *all* types as both keys and values.
Tables do not support square bracket indexing (`t[key]`), but instead rely on
the methods `:get(key)` and `:set(key, value)`. This is explicit to avoid
hiding the fact that table lookups and table insertion are performing function
calls and have edge conditions like a failure to find an entry.
---
## Table Methods
### `bump`
**Description:**
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
```
**Parameters:**
- `t`: The mutable reference to the table.
- `key`: The key whose value is to be incremented.
- `amount`: The amount to increment the value by (default: 1).
**Returns:**
Nothing.
**Example:**
```markdown
>> t := {"A":1}
t:bump("A")
t:bump("B", 10)
>> t
= {"A": 2, "B": 10}
```
---
### `clear`
**Description:**
Removes all key-value pairs from the table.
**Usage:**
```markdown
t:clear() -> Void
```
**Parameters:**
- `t`: The mutable reference to the table.
**Returns:**
Nothing.
**Example:**
```markdown
>> t:clear()
```
---
### `get`
**Description:**
Retrieves the value associated with a key, or returns a default value if the key is not present.
**Usage:**
```markdown
t:get(key: K, default: V) -> V
```
**Parameters:**
- `t`: The table.
- `key`: The key whose associated value is to be retrieved.
- `default`: The value to return if the key is not present. If this argument is
not provided, a runtime error will be created if the key is not present.
**Returns:**
The value associated with the key or the default value if the key is not found.
**Example:**
```markdown
>> t := {"A":1, "B":2}
>> t:get("A")
= 1
>> t:get("xxx", 0)
= 0
```
---
### `get_or_null`
**Description:**
Retrieves the value associated with a key, or returns `null` if the key is not present.
This method is only available on tables whose values are pointers.
**Usage:**
```markdown
t:get_or_null(key: K) -> @V?
```
**Parameters:**
- `t`: The table.
- `key`: The key whose associated value is to be retrieved.
**Returns:**
A mutable reference to the value associated with the key or `null` if the key is not found.
**Example:**
```markdown
>> t := {"A": @[10]}
>> t:get_or_null("A")
= @[10]?
>> t:get_or_null("xxx")
= !@[Int]
```
---
### `has`
**Description:**
Checks if the table contains a specified key.
**Usage:**
```markdown
has(t:{K:V}, key: K) -> Bool
```
**Parameters:**
- `t`: The table.
- `key`: The key to check for presence.
**Returns:**
`yes` if the key is present, `no` otherwise.
**Example:**
```markdown
>> {"A":1, "B":2}:has("A")
= yes
>> {"A":1, "B":2}:has("xxx")
= no
```
---
### `remove`
**Description:**
Removes the key-value pair associated with a specified key.
**Usage:**
```markdown
remove(t:{K:V}, key: K) -> Void
```
**Parameters:**
- `t`: The mutable reference to the table.
- `key`: The key of the key-value pair to remove.
**Returns:**
Nothing.
**Example:**
```markdown
t := {"A":1, "B":2}
t:remove("A")
>> t
= {"B": 2}
```
---
### `set`
**Description:**
Sets or updates the value associated with a specified key.
**Usage:**
```markdown
set(t:{K:V}, key: K, value: V) -> Void
```
**Parameters:**
- `t`: The mutable reference to the table.
- `key`: The key to set or update.
- `value`: The value to associate with the key.
**Returns:**
Nothing.
**Example:**
```markdown
t := {"A": 1, "B": 2}
t:set("C", 3)
>> t
= {"A": 1, "B": 2, "C": 3}
```

76
api/text.md
View File

@ -282,7 +282,7 @@ finding the value because the two texts are equivalent under normalization.
Converts a `Text` value to a C-style string.
**Usage:**
```markdown
```tomo
as_c_string(text: Text) -> CString
```
@ -294,7 +294,7 @@ as_c_string(text: Text) -> CString
A C-style string (`CString`) representing the text.
**Example:**
```markdown
```tomo
>> "Hello":as_c_string()
= CString("Hello")
```
@ -307,7 +307,7 @@ A C-style string (`CString`) representing the text.
Converts a `Text` value to an array of bytes.
**Usage:**
```markdown
```tomo
bytes(text: Text) -> [Int8]
```
@ -319,7 +319,7 @@ bytes(text: Text) -> [Int8]
An array of bytes (`[Int8]`) representing the text.
**Example:**
```markdown
```tomo
>> "Amélie":bytes()
= [65_i8, 109_i8, 101_i8, -52_i8, -127_i8, 108_i8, 105_i8, 101_i8]
```
@ -332,7 +332,7 @@ An array of bytes (`[Int8]`) representing the text.
Returns a list of character names from the text.
**Usage:**
```markdown
```tomo
character_names(text: Text) -> [Text]
```
@ -344,7 +344,7 @@ character_names(text: Text) -> [Text]
A list of character names (`[Text]`).
**Example:**
```markdown
```tomo
>> "Amélie":character_names()
= ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E", "COMBINING ACUTE ACCENT", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"]
```
@ -360,7 +360,7 @@ in a text editor and you hit the left or right arrow key, it will move the
cursor by one graphical cluster.
**Usage:**
```markdown
```tomo
clusters(text: Text) -> [Text]
```
@ -372,7 +372,7 @@ clusters(text: Text) -> [Text]
A list of graphical clusters (`[Text]`) within the text.
**Example:**
```markdown
```tomo
>> "Amélie":clusters()
= ["A", "m", "é", "l", "i", "e"] : [Text]
```
@ -385,7 +385,7 @@ A list of graphical clusters (`[Text]`) within the text.
Returns a list of Unicode code points for the text.
**Usage:**
```markdown
```tomo
codepoints(text: Text) -> [Int32]
```
@ -397,7 +397,7 @@ codepoints(text: Text) -> [Int32]
A list of Unicode code points (`[Int32]`).
**Example:**
```markdown
```tomo
>> "Amélie":codepoints()
= [65_i32, 109_i32, 101_i32, 769_i32, 108_i32, 105_i32, 101_i32] : [Int32]
```
@ -410,7 +410,7 @@ A list of Unicode code points (`[Int32]`).
Converts a C-style string to a `Text` value.
**Usage:**
```markdown
```tomo
from_c_string(str: CString) -> Text
```
@ -422,7 +422,7 @@ from_c_string(str: CString) -> Text
A `Text` value representing the C-style string.
**Example:**
```markdown
```tomo
from_c_string(CString("Hello")) // "Hello"
```
@ -434,7 +434,7 @@ from_c_string(CString("Hello")) // "Hello"
Checks if the `Text` contains a target substring.
**Usage:**
```markdown
```tomo
has(text: Text, target: Text, where: Where = Where.Anywhere) -> Bool
```
@ -448,7 +448,7 @@ has(text: Text, target: Text, where: Where = Where.Anywhere) -> Bool
`yes` if the target substring is found, `no` otherwise.
**Example:**
```markdown
```tomo
has("Hello, world!", "world") // yes
```
@ -460,7 +460,7 @@ has("Hello, world!", "world") // yes
Joins a list of text pieces with a specified glue.
**Usage:**
```markdown
```tomo
join(glue: Text, pieces: [Text]) -> Text
```
@ -473,7 +473,7 @@ join(glue: Text, pieces: [Text]) -> Text
A single `Text` value with the pieces joined by the glue.
**Example:**
```markdown
```tomo
join(", ", ["apple", "banana", "cherry"]) // "apple, banana, cherry"
```
@ -485,7 +485,7 @@ join(", ", ["apple", "banana", "cherry"]) // "apple, banana, cherry"
Converts all characters in the text to lowercase.
**Usage:**
```markdown
```tomo
lower(text: Text) -> Text
```
@ -497,7 +497,7 @@ lower(text: Text) -> Text
The lowercase version of the text.
**Example:**
```markdown
```tomo
lower("HELLO") // "hello"
```
@ -509,7 +509,7 @@ lower("HELLO") // "hello"
Returns the number of bytes used by the text.
**Usage:**
```markdown
```tomo
num_bytes(text: Text) -> Int
```
@ -521,7 +521,7 @@ num_bytes(text: Text) -> Int
The number of bytes used by the text.
**Example:**
```markdown
```tomo
num_bytes("Hello") // 5
```
@ -533,7 +533,7 @@ num_bytes("Hello") // 5
Returns the number of clusters in the text.
**Usage:**
```markdown
```tomo
num_clusters(text: Text) -> Int
```
@ -545,7 +545,7 @@ num_clusters(text: Text) -> Int
The number of clusters in the text.
**Example:**
```markdown
```tomo
num_clusters("Hello") // 5
```
@ -557,7 +557,7 @@ num_clusters("Hello") // 5
Returns the number of Unicode code points in the text.
**Usage:**
```markdown
```tomo
num_codepoints(text: Text) -> Int
```
@ -569,7 +569,7 @@ num_codepoints(text: Text) -> Int
The number of Unicode code points in the text.
**Example:**
```markdown
```tomo
num_codepoints("Hello") // 5
```
@ -581,7 +581,7 @@ num_codepoints("Hello") // 5
Formats the text as a quoted string.
**Usage:**
```markdown
```tomo
quoted(text: Text, color: Bool = no) -> Text
```
@ -594,7 +594,7 @@ quoted(text: Text, color: Bool = no) -> Text
The text formatted as a quoted string.
**Example:**
```markdown
```tomo
quoted("Hello") // "\"Hello\""
```
@ -606,7 +606,7 @@ quoted("Hello") // "\"Hello\""
Replaces occurrences of a pattern in the text with a replacement string.
**Usage:**
```markdown
```tomo
replace(text: Text, pattern: Text, replacement: Text, limit: Int = -1) -> Text
```
@ -621,7 +621,7 @@ replace(text: Text, pattern: Text, replacement: Text, limit: Int = -1) -> Text
The text with occurrences of the pattern replaced.
**Example:**
```markdown
```tomo
replace("Hello world", "world", "there") // "Hello there"
```
@ -633,7 +633,7 @@ replace("Hello world", "world", "there") // "Hello there"
Splits the text into a list of substrings based on a delimiter.
**Usage:**
```markdown
```tomo
split(text: Text, split: Text) -> [Text]
```
@ -646,7 +646,7 @@ split(text: Text, split: Text) -> [Text]
A list of substrings resulting from the split.
**Example:**
```markdown
```tomo
split("apple,banana,cherry", ",") // ["apple", "banana", "cherry"]
```
@ -658,7 +658,7 @@ split("apple,banana,cherry", ",") // ["apple", "banana", "cherry"]
Converts the text to title case (capitalizing the first letter of each word).
**Usage:**
```markdown
```tomo
title(text: Text) -> Text
```
@ -670,7 +670,7 @@ title(text: Text) -> Text
The text in title case.
**Example:**
```markdown
```tomo
title("hello world") // "Hello World"
```
@ -682,7 +682,7 @@ title("hello world") // "Hello World"
Trims characters from the beginning and end of the text.
**Usage:**
```markdown
```tomo
trimmed(text: Text, trim: Text = " {\n\r\t}", where: Where = Where.Anywhere) -> Text
```
@ -696,7 +696,7 @@ trimmed(text: Text, trim: Text = " {\n\r\t}", where: Where = Where.Anywhere) ->
The trimmed text.
**Example:**
```markdown
```tomo
trimmed(" Hello ") // "Hello"
```
@ -708,7 +708,7 @@ trimmed(" Hello ") // "Hello"
Converts all characters in the text to uppercase.
**Usage:**
```markdown
```tomo
upper(text: Text) -> Text
```
@ -720,7 +720,7 @@ upper(text: Text) -> Text
The uppercase version of the text.
**Example:**
```markdown
```tomo
upper("hello") // "HELLO"
```
@ -732,7 +732,7 @@ upper("hello") // "HELLO"
Removes all occurrences of a target substring from the text.
**Usage:**
```markdown
```tomo
without(text: Text, target: Text, where: Where = Where.Anywhere) -> Text
```
@ -746,7 +746,7 @@ without(text: Text, target: Text, where: Where = Where.Anywhere) -> Text
The text with occurrences of the target removed.
**Example:**
```markdown
```tomo
without("Hello world", "world") // "Hello "
```

111
api/threads.md Normal file
View File

@ -0,0 +1,111 @@
# Threads
Tomo supports POSIX threads (pthreads) through the `Thread` type. The
recommended practice is to have each thread interact with other threads only
through thread-safe Channels with no other shared data.
## Thread Methods
### `new`
**Description:**
Creates a new thread to execute a specified function.
**Usage:**
```tomo
Thread.new(fn: func() -> Void) -> Thread
```
**Parameters:**
- `fn`: The function to be executed by the new thread.
**Returns:**
A new `Thread` object representing the created thread.
**Example:**
```tomo
>> jobs := |Int|
>> results := |Int|
>> thread := Thread.new(func():
while yes:
input := jobs:pop()
results:push(input + 10
)
= Thread<0x12345678>
>> jobs:push(10)
>> results:pop()
= 11
```
---
### `cancel`
**Description:**
Requests the cancellation of a specified thread.
**Usage:**
```tomo
cancel(thread: Thread) -> Void
```
**Parameters:**
- `thread`: The thread to cancel.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:cancel()
```
---
### `join`
**Description:**
Waits for a specified thread to terminate.
**Usage:**
```tomo
join(thread: Thread) -> Void
```
**Parameters:**
- `thread`: The thread to join.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:join()
```
---
### `detach`
**Description:**
Detaches a specified thread, allowing it to run independently.
**Usage:**
```tomo
detach(thread: Thread) -> Void
```
**Parameters:**
- `thread`: The thread to detach.
**Returns:**
Nothing.
**Example:**
```tomo
>> thread:detach()
```