From 43b4af23f84c27dada7a3515a7661f6311e4b3ba Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sun, 18 Aug 2024 18:23:32 -0400 Subject: [PATCH] API documentation --- api/arrays.md | 669 ++++++++++++++++++++++++++++++++++++++++++++++++ api/channels.md | 138 ++++++++++ api/ranges.md | 65 +++++ api/sets.md | 297 +++++++++++++++++++++ api/tables.md | 215 ++++++++++++++++ api/text.md | 76 +++--- api/threads.md | 111 ++++++++ 7 files changed, 1533 insertions(+), 38 deletions(-) create mode 100644 api/arrays.md create mode 100644 api/channels.md create mode 100644 api/ranges.md create mode 100644 api/sets.md create mode 100644 api/tables.md create mode 100644 api/threads.md diff --git a/api/arrays.md b/api/arrays.md new file mode 100644 index 0000000..2721406 --- /dev/null +++ b/api/arrays.md @@ -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} +``` diff --git a/api/channels.md b/api/channels.md new file mode 100644 index 0000000..880825c --- /dev/null +++ b/api/channels.md @@ -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] +``` diff --git a/api/ranges.md b/api/ranges.md new file mode 100644 index 0000000..4771bd5 --- /dev/null +++ b/api/ranges.md @@ -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) +``` + +--- diff --git a/api/sets.md b/api/sets.md new file mode 100644 index 0000000..7bcd480 --- /dev/null +++ b/api/sets.md @@ -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 +``` diff --git a/api/tables.md b/api/tables.md new file mode 100644 index 0000000..bdf1ef1 --- /dev/null +++ b/api/tables.md @@ -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} +``` diff --git a/api/text.md b/api/text.md index 4aeafc5..47d9d12 100644 --- a/api/text.md +++ b/api/text.md @@ -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 " ``` diff --git a/api/threads.md b/api/threads.md new file mode 100644 index 0000000..b6ae513 --- /dev/null +++ b/api/threads.md @@ -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() +```