aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/arrays.md27
-rw-r--r--docs/booleans.md2
-rw-r--r--docs/integers.md311
-rw-r--r--docs/moments.md24
-rw-r--r--docs/nums.md262
-rw-r--r--docs/paths.md27
-rw-r--r--docs/patterns.md1
-rw-r--r--docs/rng.md9
-rw-r--r--docs/sets.md169
-rw-r--r--docs/shell.md5
-rw-r--r--docs/tables.md7
-rw-r--r--docs/text.md302
-rw-r--r--docs/threads.md62
13 files changed, 710 insertions, 498 deletions
diff --git a/docs/arrays.md b/docs/arrays.md
index 29965fb4..4d9c1175 100644
--- a/docs/arrays.md
+++ b/docs/arrays.md
@@ -232,6 +232,33 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
## Array Methods
+- [`func binary_search(arr: [T], by: func(x,y:&T->Int32) = T.compare -> Int)`](#`binary_search)
+- [`func by(arr: [T], step: Int -> [T])`](#`by)
+- [`func clear(arr: @[T] -> Void)`](#`clear)
+- [`func counts(arr: [T] -> {T,Int})`](#`counts)
+- [`func find(arr: [T], target: T -> Int?)`](#`find)
+- [`func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)`](#`first)
+- [`func from(arr: [T], first: Int -> [T])`](#`from)
+- [`func has(arr: [T] -> Bool)`](#`has)
+- [`func heap_pop(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)`](#`heap_pop)
+- [`func heap_push(arr: @[T], item: T, by=T.compare -> Void)`](#`heap_push)
+- [`func heapify(arr: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)`](#`heapify)
+- [`func insert(arr: @[T], item: T, at: Int = 0 -> Void)`](#`insert)
+- [`func insert_all(arr: @[T], items: [T], at: Int = 0 -> Void)`](#`insert_all)
+- [`func pop(arr: &[T], index: Int = -1 -> T?)`](#`pop)
+- [`func random(arr: [T], rng: RNG = random -> T)`](#`random)
+- [`func remove_at(arr: @[T], at: Int = -1, count: Int = 1 -> Void)`](#`remove_at)
+- [`func remove_item(arr: @[T], item: T, max_count: Int = -1 -> Void)`](#`remove_item)
+- [`func reversed(arr: [T] -> [T])`](#`reversed)
+- [`func sample(arr: [T], count: Int, weights: [Num]? = ![Num], rng: RNG = random -> [T])`](#`sample)
+- [`func shuffle(arr: @[T], rng: RNG = random -> Void)`](#`shuffle)
+- [`func shuffled(arr: [T], rng: RNG = random -> [T])`](#`shuffled)
+- [`func slice(arr: [T], from: Int, to: Int -> [T])`](#`slice)
+- [`func sort(arr: @[T], by=T.compare -> Void)`](#`sort)
+- [`sorted(arr: [T], by=T.compare -> [T])`](#`sorted)
+- [`to(arr: [T], last: Int -> [T])`](#`to)
+- [`unique(arr: [T] -> {T})`](#`unique)
+
### `binary_search`
**Description:**
diff --git a/docs/booleans.md b/docs/booleans.md
index b5169158..300a3a64 100644
--- a/docs/booleans.md
+++ b/docs/booleans.md
@@ -7,6 +7,8 @@ Boolean values have the type `Bool` and can be either `yes` ("true") or `no`
This documentation provides details on boolean functions available in the API.
+- [`func parse(text: Text -> Bool?)`](#`parse)
+
### `parse`
**Description:**
diff --git a/docs/integers.md b/docs/integers.md
index 84f33414..e1c3a1ec 100644
--- a/docs/integers.md
+++ b/docs/integers.md
@@ -122,6 +122,46 @@ Each integer type has its own version of the following functions. Functions
can be called either on the type itself: `Int.sqrt(x)` or as a method call:
`x:sqrt()`. Method call syntax is preferred.
+- [`func abs(x: Int -> Int)`](#`abs)
+- [`func choose(n: Int, k: Int -> Int)`](#`choose)
+- [`func clamped(x, low, high: Int -> Int)`](#`clamped)
+- [`func factorial(n: Int -> Text)`](#`factorial)
+- [`func format(i: Int, digits: Int = 0 -> Text)`](#`format)
+- [`func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)`](#`hex)
+- [`func is_prime(x: Int, reps: Int = 50 -> Bool)`](#`is_prime)
+- [`func next_prime(x: Int -> Int)`](#`next_prime)
+- [`func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)`](#`octal)
+- [`func onward(first: Int, step: Int = 1 -> Text)`](#`onward)
+- [`func parse(text: Text -> Int?)`](#`parse)
+- [`func prev_prime(x: Int -> Int)`](#`prev_prime)
+- [`func sqrt(x: Int -> Int)`](#`sqrt)
+- [`func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))`](#`to)
+
+### `abs`
+
+**Description:**
+Calculates the absolute value of an integer.
+
+**Signature:**
+```tomo
+func abs(x: Int -> Int)
+```
+
+**Parameters:**
+
+- `x`: The integer whose absolute value is to be calculated.
+
+**Returns:**
+The absolute value of `x`.
+
+**Example:**
+```tomo
+>> -10:abs()
+= 10
+```
+
+---
+
### `choose`
**Description:**
@@ -151,6 +191,34 @@ The binomial coefficient, equivalent to the number of ways to uniquely choose
---
+### `clamped`
+
+**Description:**
+Returns the given number clamped between two values so that it is within
+that range.
+
+**Signature:**
+```tomo
+func clamped(x, low, high: Int -> Int)
+```
+
+**Parameters:**
+
+- `x`: The integer to clamp.
+- `low`: The lowest value the result can take.
+- `high`: The highest value the result can take.
+
+**Returns:**
+The first argument clamped between the other two arguments.
+
+**Example:**
+```tomo
+>> 2:clamped(5, 10)
+= 5
+```
+
+---
+
### `factorial`
**Description:**
@@ -230,6 +298,71 @@ The hexadecimal string representation of the integer.
---
+### `is_prime`
+
+**Description:**
+Determines if an integer is a prime number.
+
+**Note:**
+This function is _probabilistic_. With the default arguments, the chances of
+getting an incorrect answer are astronomically small (on the order of 10^(-30)).
+See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
+for more details.
+
+**Signature:**
+```tomo
+func is_prime(x: Int, reps: Int = 50 -> Bool)
+```
+
+**Parameters:**
+
+- `x`: The integer to be checked.
+- `reps`: The number of repetitions for primality tests. Default is `50`.
+
+**Returns:**
+`yes` if `x` is a prime number, `no` otherwise.
+
+**Example:**
+```tomo
+>> 7:is_prime()
+= yes
+>> 6:is_prime()
+= no
+```
+
+---
+
+### `next_prime`
+
+**Description:**
+Finds the next prime number greater than the given integer.
+
+**Note:**
+This function is _probabilistic_, but the chances of getting an incorrect
+answer are astronomically small (on the order of 10^(-30)).
+See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
+for more details.
+
+**Signature:**
+```tomo
+func next_prime(x: Int -> Int)
+```
+
+**Parameters:**
+
+- `x`: The integer after which to find the next prime.
+
+**Returns:**
+The next prime number greater than `x`.
+
+**Example:**
+```tomo
+>> 11:next_prime()
+= 13
+```
+
+---
+
### `octal`
**Description:**
@@ -325,62 +458,35 @@ of the representable range or if the entire text can't be parsed as an integer,
---
-### `to`
+### `prev_prime`
**Description:**
-Returns an iterator function that iterates over the range of numbers specified.
-Iteration is assumed to be nonempty and
-
-**Signature:**
-```tomo
-func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))
-```
-
-**Parameters:**
-
-- `first`: The starting value of the range.
-- `last`: The ending value of the range.
-- `step`: An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.
-
-**Returns:**
-An iterator function that returns each integer in the given range (inclusive).
-
-**Example:**
-```tomo
->> 2:to(5)
-= func(->Int?)
->> [x for x in 2:to(5)]
-= [2, 3, 4, 5]
->> [x for x in 5:to(2)]
-= [5, 4, 3, 2]
-
->> [x for x in 2:to(5, step=2)]
-= [2, 4]
-```
-
----
-
-### `abs`
+Finds the previous prime number less than the given integer.
+If there is no previous prime number (i.e. if a number less than `2` is
+provided), then the function will create a runtime error.
-**Description:**
-Calculates the absolute value of an integer.
+**Note:**
+This function is _probabilistic_, but the chances of getting an incorrect
+answer are astronomically small (on the order of 10^(-30)).
+See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
+for more details.
**Signature:**
```tomo
-func abs(x: Int -> Int)
+func prev_prime(x: Int -> Int)
```
**Parameters:**
-- `x`: The integer whose absolute value is to be calculated.
+- `x`: The integer before which to find the previous prime.
**Returns:**
-The absolute value of `x`.
+The previous prime number less than `x`.
**Example:**
```tomo
->> -10:abs()
-= 10
+>> 11:prev_prime()
+= 7
```
---
@@ -412,126 +518,35 @@ The integer part of the square root of `x`.
---
-### `is_prime`
-
-**Description:**
-Determines if an integer is a prime number.
-
-**Note:**
-This function is _probabilistic_. With the default arguments, the chances of
-getting an incorrect answer are astronomically small (on the order of 10^(-30)).
-See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
-for more details.
-
-**Signature:**
-```tomo
-func is_prime(x: Int, reps: Int = 50 -> Bool)
-```
-
-**Parameters:**
-
-- `x`: The integer to be checked.
-- `reps`: The number of repetitions for primality tests. Default is `50`.
-
-**Returns:**
-`yes` if `x` is a prime number, `no` otherwise.
-
-**Example:**
-```tomo
->> 7:is_prime()
-= yes
->> 6:is_prime()
-= no
-```
-
----
-
-### `next_prime`
-
-**Description:**
-Finds the next prime number greater than the given integer.
-
-**Note:**
-This function is _probabilistic_, but the chances of getting an incorrect
-answer are astronomically small (on the order of 10^(-30)).
-See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
-for more details.
-
-**Signature:**
-```tomo
-func next_prime(x: Int -> Int)
-```
-
-**Parameters:**
-
-- `x`: The integer after which to find the next prime.
-
-**Returns:**
-The next prime number greater than `x`.
-
-**Example:**
-```tomo
->> 11:next_prime()
-= 13
-```
-
----
-
-### `prev_prime`
+### `to`
**Description:**
-Finds the previous prime number less than the given integer.
-If there is no previous prime number (i.e. if a number less than `2` is
-provided), then the function will create a runtime error.
-
-**Note:**
-This function is _probabilistic_, but the chances of getting an incorrect
-answer are astronomically small (on the order of 10^(-30)).
-See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp)
-for more details.
+Returns an iterator function that iterates over the range of numbers specified.
+Iteration is assumed to be nonempty and
**Signature:**
```tomo
-func prev_prime(x: Int -> Int)
+func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))
```
**Parameters:**
-- `x`: The integer before which to find the previous prime.
+- `first`: The starting value of the range.
+- `last`: The ending value of the range.
+- `step`: An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`.
**Returns:**
-The previous prime number less than `x`.
+An iterator function that returns each integer in the given range (inclusive).
**Example:**
```tomo
->> 11:prev_prime()
-= 7
-```
-
----
-
-### `clamped`
-
-**Description:**
-Returns the given number clamped between two values so that it is within
-that range.
-
-**Signature:**
-```tomo
-func clamped(x, low, high: Int -> Int)
-```
-
-**Parameters:**
-
-- `x`: The integer to clamp.
-- `low`: The lowest value the result can take.
-- `high`: The highest value the result can take.
-
-**Returns:**
-The first argument clamped between the other two arguments.
+>> 2:to(5)
+= func(->Int?)
+>> [x for x in 2:to(5)]
+= [2, 3, 4, 5]
+>> [x for x in 5:to(2)]
+= [5, 4, 3, 2]
-**Example:**
-```tomo
->> 2:clamped(5, 10)
-= 5
+>> [x for x in 2:to(5, step=2)]
+= [2, 4]
```
diff --git a/docs/moments.md b/docs/moments.md
index 1cd26edb..cee53bde 100644
--- a/docs/moments.md
+++ b/docs/moments.md
@@ -63,6 +63,30 @@ Time zones are specified by name, such as `America/New_York` or `UTC`.
## Moment Methods
+- [`func after(moment: Moment, seconds : Num = 0.0, minutes : Num = 0.0, hours : Num = 0.0, days : Int = 0, weeks : Int = 0, months : Int = 0, years : Int = 0, timezone : Text? = !Text -> Moment)`](#`after)
+- [`func date(moment: Moment, timezone : Text? = !Text -> Text)`](#`date)
+- [`func day_of_month(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_month)
+- [`func day_of_week(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_week)
+- [`func day_of_year(moment: Moment, timezone : Text? = !Text -> Int)`](#`day_of_year)
+- [`func format(moment: Moment, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)`](#`format)
+- [`func from_unix_timestamp(timestamp: Int64 -> Moment)`](#`from_unix_timestamp)
+- [`func get_local_timezone(->Text)`](#`get_local_timezone)
+- [`func hour(moment: Moment, timezone : Text? = !Text -> Int)`](#`hour)
+- [`func hours_till(moment: Moment, then:Moment -> Num)`](#`hours_till)
+- [`func minute(moment: Moment, timezone : Text? = !Text -> Int)`](#`minute)
+- [`func minutes_till(moment: Moment, then:Moment -> Num)`](#`minutes_till)
+- [`func month(moment: Moment, timezone : Text? = !Text -> Int)`](#`month)
+- [`func nanosecond(moment: Moment, timezone : Text? = !Text -> Int)`](#`nanosecond)
+- [`func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> Moment)`](#`new)
+- [`func now(->Moment)`](#`now)
+- [`func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> Moment?)`](#`parse)
+- [`func relative(moment: Moment, relative_to : Moment = Moment.now(), timezone : Text? = !Text -> Text)`](#`relative)
+- [`func second(moment: Moment, timezone : Text? = !Text -> Int)`](#`second)
+- [`func seconds_till(moment: Moment, then:Moment -> Num)`](#`seconds_till)
+- [`func set_local_timezone(timezone : Text? = !Text -> Void)`](#`set_local_timezone)
+- [`func time(moment: Moment, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)`](#`time)
+- [`func unix_timestamp(moment:Moment->Int64)`](#`unix_timestamp)
+
### `after`
**Description:**
diff --git a/docs/nums.md b/docs/nums.md
index aae6a48c..5589de57 100644
--- a/docs/nums.md
+++ b/docs/nums.md
@@ -119,6 +119,56 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
---
+- [`func abs(n: Num -> Num)`](#`abs)
+- [`func acos(x: Num -> Num)`](#`acos)
+- [`func acosh(x: Num -> Num)`](#`acosh)
+- [`func asin(x: Num -> Num)`](#`asin)
+- [`func asinh(x: Num -> Num)`](#`asinh)
+- [`func atan(x: Num -> Num)`](#`atan)
+- [`func atan2(x: Num, y: Num -> Num)`](#`atan2)
+- [`func atanh(x: Num -> Num)`](#`atanh)
+- [`func cbrt(x: Num -> Num)`](#`cbrt)
+- [`func ceil(x: Num -> Num)`](#`ceil)
+- [`clamped(x, low, high: Num -> Num)`](#`clamped)
+- [`func copysign(x: Num, y: Num -> Num)`](#`copysign)
+- [`func cos(x: Num -> Num)`](#`cos)
+- [`func cosh(x: Num -> Num)`](#`cosh)
+- [`func erf(x: Num -> Num)`](#`erf)
+- [`func erfc(x: Num -> Num)`](#`erfc)
+- [`func exp(x: Num -> Num)`](#`exp)
+- [`func exp2(x: Num -> Num)`](#`exp2)
+- [`func expm1(x: Num -> Num)`](#`expm1)
+- [`func fdim(x: Num, y: Num -> Num)`](#`fdim)
+- [`func floor(x: Num -> Num)`](#`floor)
+- [`func format(n: Num, precision: Int = 0 -> Text)`](#`format)
+- [`func hypot(x: Num, y: Num -> Num)`](#`hypot)
+- [`func isfinite(n: Num -> Bool)`](#`isfinite)
+- [`func isinf(n: Num -> Bool)`](#`isinf)
+- [`func j0(x: Num -> Num)`](#`j0)
+- [`func j1(x: Num -> Num)`](#`j1)
+- [`func log(x: Num -> Num)`](#`log)
+- [`func log10(x: Num -> Num)`](#`log10)
+- [`func log1p(x: Num -> Num)`](#`log1p)
+- [`func log2(x: Num -> Num)`](#`log2)
+- [`func logb(x: Num -> Num)`](#`logb)
+- [`func mix(amount: Num, x: Num, y: Num -> Num)`](#`mix)
+- [`func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)`](#`near)
+- [`func nextafter(x: Num, y: Num -> Num)`](#`nextafter)
+- [`func parse(text: Text -> Num?)`](#`parse)
+- [`func rint(x: Num -> Num)`](#`rint)
+- [`func round(x: Num -> Num)`](#`round)
+- [`func scientific(n: Num, precision: Int = 0 -> Text)`](#`scientific)
+- [`func significand(x: Num -> Num)`](#`significand)
+- [`func sin(x: Num -> Num)`](#`sin)
+- [`func sinh(x: Num -> Num)`](#`sinh)
+- [`func sqrt(x: Num -> Num)`](#`sqrt)
+- [`func tan(x: Num -> Num)`](#`tan)
+- [`func tanh(x: Num -> Num)`](#`tanh)
+- [`func tgamma(x: Num -> Num)`](#`tgamma)
+- [`func trunc(x: Num -> Num)`](#`trunc)
+- [`func y0(x: Num -> Num)`](#`y0)
+- [`func y1(x: Num -> Num)`](#`y1)
+
### `abs`
**Description:**
@@ -244,52 +294,52 @@ The inverse hyperbolic sine of `x`.
---
-### `atan2`
+### `atan`
**Description:**
-Computes the arc tangent of the quotient of two numbers.
+Computes the arc tangent of a number.
**Signature:**
```tomo
-func atan2(x: Num, y: Num -> Num)
+func atan(x: Num -> Num)
```
**Parameters:**
-- `x`: The numerator.
-- `y`: The denominator.
+- `x`: The number for which the arc tangent is to be calculated.
**Returns:**
-The arc tangent of `x/y` in radians.
+The arc tangent of `x` in radians.
**Example:**
```tomo
->> Num.atan2(1, 1) // -> (π/4)
+>> 1.0:atan() // -> (π/4)
= 0.7854
```
---
-### `atan`
+### `atan2`
**Description:**
-Computes the arc tangent of a number.
+Computes the arc tangent of the quotient of two numbers.
**Signature:**
```tomo
-func atan(x: Num -> Num)
+func atan2(x: Num, y: Num -> Num)
```
**Parameters:**
-- `x`: The number for which the arc tangent is to be calculated.
+- `x`: The numerator.
+- `y`: The denominator.
**Returns:**
-The arc tangent of `x` in radians.
+The arc tangent of `x/y` in radians.
**Example:**
```tomo
->> 1.0:atan() // -> (π/4)
+>> Num.atan2(1, 1) // -> (π/4)
= 0.7854
```
@@ -370,6 +420,34 @@ The smallest integer greater than or equal to `x`.
---
+### `clamped`
+
+**Description:**
+Returns the given number clamped between two values so that it is within
+that range.
+
+**Signature:**
+```tomo
+clamped(x, low, high: Num -> Num)
+```
+
+**Parameters:**
+
+- `x`: The number to clamp.
+- `low`: The lowest value the result can take.
+- `high`: The highest value the result can take.
+
+**Returns:**
+The first argument clamped between the other two arguments.
+
+**Example:**
+```tomo
+>> 2.5:clamped(5.5, 10.5)
+= 5.5
+```
+
+---
+
### `copysign`
**Description:**
@@ -496,14 +574,14 @@ The complementary error function of `x`.
---
-### `exp2`
+### `exp`
**Description:**
-Computes \( 2^x \) for a number.
+Computes the exponential function \( e^x \) for a number.
**Signature:**
```tomo
-func exp2(x: Num -> Num)
+func exp(x: Num -> Num)
```
**Parameters:**
@@ -511,24 +589,24 @@ func exp2(x: Num -> Num)
- `x`: The exponent.
**Returns:**
-The value of \( 2^x \).
+The value of \( e^x \).
**Example:**
```tomo
->> 3.0:exp2()
-= 8
+>> 1.0:exp()
+= 2.7183
```
---
-### `exp`
+### `exp2`
**Description:**
-Computes the exponential function \( e^x \) for a number.
+Computes \( 2^x \) for a number.
**Signature:**
```tomo
-func exp(x: Num -> Num)
+func exp2(x: Num -> Num)
```
**Parameters:**
@@ -536,12 +614,12 @@ func exp(x: Num -> Num)
- `x`: The exponent.
**Returns:**
-The value of \( e^x \).
+The value of \( 2^x \).
**Example:**
```tomo
->> 1.0:exp()
-= 2.7183
+>> 3.0:exp2()
+= 8
```
---
@@ -650,34 +728,6 @@ A text representation of the number with the specified precision.
---
-### `parse`
-
-**Description:**
-Converts a text representation of a number into a floating-point number.
-
-**Signature:**
-```tomo
-func parse(text: Text -> Num?)
-```
-
-**Parameters:**
-
-- `text`: The text containing the number.
-
-**Returns:**
-The number represented by the text or `none` if the entire text can't be parsed
-as a number.
-
-**Example:**
-```tomo
->> Num.parse("3.14")
-= 3.14
->> Num.parse("1e3")
-= 1000
-```
-
----
-
### `hypot`
**Description:**
@@ -808,6 +858,31 @@ The Bessel function of the first kind of order 1 of `x`.
---
+### `log`
+
+**Description:**
+Computes the natural logarithm (base \( e \)) of a number.
+
+**Signature:**
+```tomo
+func log(x: Num -> Num)
+```
+
+**Parameters:**
+
+- `x`: The number for which the natural logarithm is to be calculated.
+
+**Returns:**
+The natural logarithm of `x`.
+
+**Example:**
+```tomo
+>> Num.E:log()
+= 1
+```
+
+---
+
### `log10`
**Description:**
@@ -883,31 +958,6 @@ The base-2 logarithm of `x`.
---
-### `log`
-
-**Description:**
-Computes the natural logarithm (base \( e \)) of a number.
-
-**Signature:**
-```tomo
-func log(x: Num -> Num)
-```
-
-**Parameters:**
-
-- `x`: The number for which the natural logarithm is to be calculated.
-
-**Returns:**
-The natural logarithm of `x`.
-
-**Example:**
-```tomo
->> Num.E:log()
-= 1
-```
-
----
-
### `logb`
**Description:**
@@ -1024,6 +1074,34 @@ The next representable value after `x` in the direction of `y`.
---
+### `parse`
+
+**Description:**
+Converts a text representation of a number into a floating-point number.
+
+**Signature:**
+```tomo
+func parse(text: Text -> Num?)
+```
+
+**Parameters:**
+
+- `text`: The text containing the number.
+
+**Returns:**
+The number represented by the text or `none` if the entire text can't be parsed
+as a number.
+
+**Example:**
+```tomo
+>> Num.parse("3.14")
+= 3.14
+>> Num.parse("1e3")
+= 1000
+```
+
+---
+
### `rint`
**Description:**
@@ -1353,31 +1431,3 @@ The Bessel function of the second kind of order 1 of `x`.
>> 1.0:y1()
= 0.4401
```
-
----
-
-### `clamped`
-
-**Description:**
-Returns the given number clamped between two values so that it is within
-that range.
-
-**Signature:**
-```tomo
-clamped(x, low, high: Num -> Num)
-```
-
-**Parameters:**
-
-- `x`: The number to clamp.
-- `low`: The lowest value the result can take.
-- `high`: The highest value the result can take.
-
-**Returns:**
-The first argument clamped between the other two arguments.
-
-**Example:**
-```tomo
->> 2.5:clamped(5.5, 10.5)
-= 5.5
-```
diff --git a/docs/paths.md b/docs/paths.md
index b6d62b61..d361b832 100644
--- a/docs/paths.md
+++ b/docs/paths.md
@@ -37,6 +37,33 @@ intended. Paths can be created from text with slashes using
## Path Methods
+- [`func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)`](#`append)
+- [`func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)`](#`append_bytes)
+- [`func base_name(path: Path -> Text)`](#`base_name)
+- [`func by_line(path: Path -> func(->Text?)?)`](#`by_line)
+- [`func children(path: Path, include_hidden=no -> [Path])`](#`children)
+- [`func create_directory(path: Path, permissions=0o755[32] -> Void)`](#`create_directory)
+- [`func exists(path: Path -> Bool)`](#`exists)
+- [`func extension(path: Path, full=yes -> Text)`](#`extension)
+- [`func files(path: Path, include_hidden=no -> [Path])`](#`files)
+- [`func glob(path: Path -> [Path])`](#`glob)
+- [`func is_directory(path: Path, follow_symlinks=yes -> Bool)`](#`is_directory)
+- [`func is_file(path: Path, follow_symlinks=yes -> Bool)`](#`is_file)
+- [`func is_socket(path: Path, follow_symlinks=yes -> Bool)`](#`is_socket)
+- [`func is_symlink(path: Path -> Bool)`](#`is_symlink)
+- [`func parent(path: Path -> Path)`](#`parent)
+- [`func read(path: Path -> Text?)`](#`read)
+- [`func read_bytes(path: Path -> [Byte]?)`](#`read_bytes)
+- [`func relative(path: Path, relative_to=(./) -> Path)`](#`relative)
+- [`func remove(path: Path, ignore_missing=no -> Void)`](#`remove)
+- [`func resolved(path: Path, relative_to=(./) -> Path)`](#`resolved)
+- [`func subdirectories(path: Path, include_hidden=no -> [Path])`](#`subdirectories)
+- [`func unique_directory(path: Path -> Path)`](#`unique_directory)
+- [`func write(path: Path, text: Text, permissions=0o644[32] -> Void)`](#`write)
+- [`func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)`](#`write_bytes)
+- [`func write_unique(path: Path, text: Text -> Path)`](#`write_unique)
+- [`func write_unique_bytes(path: Path, bytes: [Byte] -> Path)`](#`write_unique_bytes)
+
### `append`
**Description:**
diff --git a/docs/patterns.md b/docs/patterns.md
index dd57ada9..728b978e 100644
--- a/docs/patterns.md
+++ b/docs/patterns.md
@@ -150,4 +150,3 @@ many repetitions you want by putting a number or range of numbers first using
{2+ space}
{0-1 question mark}
```
-
diff --git a/docs/rng.md b/docs/rng.md
index 2663197e..306f2015 100644
--- a/docs/rng.md
+++ b/docs/rng.md
@@ -19,6 +19,15 @@ This documentation provides details on RNG functions available in the API.
[Arrays](arrays.md) also have some methods which use RNG values:
`array:shuffle()`, `array:shuffled()`, `array:random()`, and `array:sample()`.
+- [`func bool(rng: RNG, p: Num = 0.5 -> Bool)`](#`bool)
+- [`func byte(rng: RNG -> Byte)`](#`byte)
+- [`func bytes(rng: RNG, count: Int -> [Byte])`](#`bytes)
+- [`func copy(rng: RNG -> RNG)`](#`copy)
+- [`func int(rng: RNG, min: Int, max: Int -> Int)`](#`int`, `int64`, `int32`, `int16`, `int8)
+- [`func new(seed: [Byte] = (/dev/urandom):read_bytes(40)! -> RNG)`](#`new)
+- [`func num(rng: RNG, min: Num = 0.0, max: Num = 1.0 -> Int)`](#`num`, `num32)
+- [`func set_seed(rng: RNG, seed: [Byte])`](#`set_seed)
+
### `bool`
**Description:**
diff --git a/docs/sets.md b/docs/sets.md
index e9c44b29..83e5cd92 100644
--- a/docs/sets.md
+++ b/docs/sets.md
@@ -75,31 +75,17 @@ iterating over any of the new values.
## Set Methods
-### `has`
-
-**Description:**
-Checks if the set contains a specified item.
-
-**Signature:**
-```tomo
-func has(set:{T}, item:T -> Bool)
-```
-
-**Parameters:**
-
-- `set`: The set to check.
-- `item`: The item to check for presence.
-
-**Returns:**
-`yes` if the item is present, `no` otherwise.
-
-**Example:**
-```tomo
->> {10, 20}:has(20)
-= yes
-```
-
----
+- [`func add(set:{T}, item: T -> Void)`](#`add)
+- [`func add_all(set:@{T}, items: [T] -> Void)`](#`add_all)
+- [`func clear(set:@{T} -> Void)`](#`clear)
+- [`func has(set:{T}, item:T -> Bool)`](#`has)
+- [`func (set: {T}, other: {T}, strict: Bool = no -> Bool)`](#`is_subset_of)
+- [`func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)`](#`is_superset_of)
+- [`func overlap(set:{T}, other: {T} -> {T})`](#`overlap)
+- [`func remove(set:@{T}, item: T -> Void)`](#`remove)
+- [`func remove_all(set:@{T}, items: [T] -> Void)`](#`remove_all)
+- [`func with(set:{T}, other: {T} -> {T})`](#`with)
+- [`func without(set:{T}, other: {T} -> {T})`](#`without)
### `add`
@@ -151,106 +137,107 @@ Nothing.
---
-### `remove`
+### `clear`
**Description:**
-Removes an item from the set.
+Removes all items from the set.
**Signature:**
```tomo
-func remove(set:@{T}, item: T -> Void)
+func clear(set:@{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)
+>> nums:clear()
```
---
-### `remove_all`
+### `has`
**Description:**
-Removes multiple items from the set.
+Checks if the set contains a specified item.
**Signature:**
```tomo
-func remove_all(set:@{T}, items: [T] -> Void)
+func has(set:{T}, item:T -> Bool)
```
**Parameters:**
-- `set`: The mutable reference to the set.
-- `items`: The array of items to remove from the set.
+- `set`: The set to check.
+- `item`: The item to check for presence.
**Returns:**
-Nothing.
+`yes` if the item is present, `no` otherwise.
**Example:**
```tomo
->> nums:remove_all([1, 2, 3])
+>> {10, 20}:has(20)
+= yes
```
---
-### `clear`
+### `is_subset_of`
**Description:**
-Removes all items from the set.
+Checks if the set is a subset of another set.
**Signature:**
```tomo
-func clear(set:@{T} -> Void)
+func (set: {T}, other: {T}, strict: Bool = no -> Bool)
```
**Parameters:**
-- `set`: The mutable reference to the set.
+- `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:**
-Nothing.
+`yes` if the set is a subset of the other set (strictly or not), `no` otherwise.
**Example:**
```tomo
->> nums:clear()
+>> {1, 2}:is_subset_of({1, 2, 3})
+= yes
```
---
-### `with`
+### `is_superset_of`
**Description:**
-Creates a new set that is the union of the original set and another set.
+Checks if the set is a superset of another set.
**Signature:**
```tomo
-func with(set:{T}, other: {T} -> {T})
+func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
```
**Parameters:**
-- `set`: The original set.
-- `other`: The set to union with.
+- `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:**
-A new set containing all items from both sets.
+`yes` if the set is a superset of the other set (strictly or not), `no` otherwise.
**Example:**
```tomo
->> {1, 2}:with({2, 3})
-= {1, 2, 3}
+>> {1, 2, 3}:is_superset_of({1, 2})
+= yes
```
-
----
-
### `overlap`
**Description:**
@@ -277,80 +264,102 @@ A new set containing only items present in both sets.
---
-### `without`
+### `remove`
**Description:**
-Creates a new set with items from the original set but without items from another set.
+Removes an item from the set.
**Signature:**
```tomo
-func without(set:{T}, other: {T} -> {T})
+func remove(set:@{T}, item: T -> Void)
```
**Parameters:**
-- `set`: The original set.
-- `other`: The set of items to remove from the original set.
+- `set`: The mutable reference to the set.
+- `item`: The item to remove from the set.
**Returns:**
-A new set containing items from the original set excluding those in the other set.
+Nothing.
**Example:**
```tomo
->> {1, 2}:without({2, 3})
-= {1}
+>> nums:remove(42)
```
---
-### `is_subset_of`
+### `remove_all`
**Description:**
-Checks if the set is a subset of another set.
+Removes multiple items from the set.
**Signature:**
```tomo
-func (set: {T}, other: {T}, strict: Bool = no -> Bool)
+func remove_all(set:@{T}, items: [T] -> Void)
```
**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).
+- `set`: The mutable reference to the set.
+- `items`: The array of items to remove from the set.
**Returns:**
-`yes` if the set is a subset of the other set (strictly or not), `no` otherwise.
+Nothing.
**Example:**
```tomo
->> {1, 2}:is_subset_of({1, 2, 3})
-= yes
+>> nums:remove_all([1, 2, 3])
```
---
-### `is_superset_of`
+### `with`
**Description:**
-Checks if the set is a superset of another set.
+Creates a new set that is the union of the original set and another set.
**Signature:**
```tomo
-func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
+func with(set:{T}, other: {T} -> {T})
```
**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).
+- `set`: The original set.
+- `other`: The set to union with.
**Returns:**
-`yes` if the set is a superset of the other set (strictly or not), `no` otherwise.
+A new set containing all items from both sets.
**Example:**
```tomo
->> {1, 2, 3}:is_superset_of({1, 2})
-= yes
+>> {1, 2}:with({2, 3})
+= {1, 2, 3}
+```
+
+---
+
+### `without`
+
+**Description:**
+Creates a new set with items from the original set but without items from another set.
+
+**Signature:**
+```tomo
+func without(set:{T}, other: {T} -> {T})
+```
+
+**Parameters:**
+
+- `set`: The original set.
+- `other`: The set of items to remove from the original set.
+
+**Returns:**
+A new set containing items from the original set excluding those in the other set.
+
+**Example:**
+```tomo
+>> {1, 2}:without({2, 3})
+= {1}
```
diff --git a/docs/shell.md b/docs/shell.md
index f453a1d0..8ca8fa2d 100644
--- a/docs/shell.md
+++ b/docs/shell.md
@@ -13,6 +13,11 @@ user-controlled string is automatically escaped when performing interpolation.
## Shell Methods
+- [`func by_line(command: Shell -> Void)`](#`by_line)
+- [`func execute(command: Shell -> Int32?)`](#`execute)
+- [`func run(command: Shell -> Text?)`](#`run)
+- [`func run(command: Shell -> [Byte]?)`](#`run_bytes)
+
### `by_line`
**Description:**
diff --git a/docs/tables.md b/docs/tables.md
index 5af26396..bb57a972 100644
--- a/docs/tables.md
+++ b/docs/tables.md
@@ -133,6 +133,13 @@ iterating over any of the new values.
## Table Methods
+- [`func bump(t:@{K,V}, key: K, amount: Int = 1 -> Void)`](#`bump)
+- [`func clear(t:@{K,V})`](#`clear)
+- [`func get(t:{K,V}, key: K -> V?)`](#`get)
+- [`func has(t:{K,V}, key: K -> Bool)`](#`has)
+- [`func remove(t:{K,V}, key: K -> Void)`](#`remove)
+- [`func set(t:{K,V}, key: K, value: V -> Void)`](#`set)
+
### `bump`
**Description:**
diff --git a/docs/text.md b/docs/text.md
index 960aa07d..67f65f91 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -270,6 +270,42 @@ pattern documentation](patterns.md) for more details.
## Text Functions
+- [`func as_c_string(text: Text -> CString)`](#`as_c_string)
+- [`func at(text: Text, index: Int -> Text)`](#`at)
+- [`func by_line(text: Text -> func(->Text?))`](#`by_line)
+- [`func by_match(text: Text, pattern: Pattern -> func(->Match?))`](#`by_match)
+- [`func by_split(text: Text, pattern: Pattern = $// -> func(->Text?))`](#`by_split)
+- [`func bytes(text: Text -> [Byte])`](#`bytes)
+- [`func codepoint_names(text: Text -> [Text])`](#`codepoint_names)
+- [`func each(text: Text, pattern: Pattern, fn: func(m: Match), recursive: Bool = yes -> Int?)`](#`each)
+- [`func ends_with(text: Text, suffix: Text -> Bool)`](#`ends_with)
+- [`func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)`](#`find)
+- [`func find_all(text: Text, pattern: Pattern -> [Match])`](#`find_all)
+- [`func from(text: Text, first: Int -> Text)`](#`from)
+- [`func from_codepoint_names(codepoints: [Int32] -> [Text])`](#`from_bytes)
+- [`func from_c_string(str: CString -> Text)`](#`from_c_string)
+- [`func from_codepoint_names(codepoint_names: [Text] -> [Text])`](#`from_codepoint_names)
+- [`func from_codepoint_names(codepoints: [Int32] -> [Text])`](#`from_codepoints)
+- [`func has(text: Text, pattern: Pattern -> Bool)`](#`has)
+- [`func join(glue: Text, pieces: [Text] -> Text)`](#`join)
+- [`func split(text: Text -> [Text])`](#`lines)
+- [`func lower(text: Text -> Text)`](#`lower)
+- [`func map(text: Text, pattern: Pattern, fn: func(text:Match)->Text -> Text, recursive: Bool = yes)`](#`map)
+- [`func matches(text: Text, pattern: Pattern -> [Text])`](#`matches)
+- [`func quoted(text: Text, color: Bool = no -> Text)`](#`quoted)
+- [`func repeat(text: Text, count:Int -> Text)`](#`repeat)
+- [`func replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)`](#`replace)
+- [`func replace_all(replacements:{Pattern,Text}, backref: Pattern = $/\/, recursive: Bool = yes -> Text)`](#`replace_all)
+- [`func reversed(text: Text -> Text)`](#`reversed)
+- [`func slice(text: Text, from: Int = 1, to: Int = -1 -> Text)`](#`slice)
+- [`func split(text: Text, pattern: Pattern = "" -> [Text])`](#`split)
+- [`func starts_with(text: Text, prefix: Text -> Bool)`](#`starts_with)
+- [`func title(text: Text -> Text)`](#`title)
+- [`func to(text: Text, last: Int -> Text)`](#`to)
+- [`func trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)`](#`trim)
+- [`func upper(text: Text -> Text)`](#`upper)
+- [`func utf32_codepoints(text: Text -> [Int32])`](#`utf32_codepoints)
+
### `as_c_string`
**Description:**
@@ -470,31 +506,6 @@ An array of codepoint names (`[Text]`).
---
-### `utf32_codepoints`
-
-**Description:**
-Returns an array of Unicode code points for UTF32 encoding of the text.
-
-**Signature:**
-```tomo
-func utf32_codepoints(text: Text -> [Int32])
-```
-
-**Parameters:**
-
-- `text`: The text from which to extract Unicode code points.
-
-**Returns:**
-An array of 32-bit integer Unicode code points (`[Int32]`).
-
-**Example:**
-```tomo
->> "Amélie":utf32_codepoints()
-= [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32]
-```
-
----
-
### `each`
**Description:**
@@ -552,87 +563,108 @@ func ends_with(text: Text, suffix: Text -> Bool)
---
-### `from_c_string`
+### `find`
**Description:**
-Converts a C-style string to a `Text` value.
+Finds the first occurrence of a [pattern](patterns.md) in the given text (if
+any).
**Signature:**
```tomo
-func from_c_string(str: CString -> Text)
+func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)
```
**Parameters:**
-- `str`: The C-style string to be converted.
+- `text`: The text to be searched.
+- `pattern`: The [pattern](patterns.md) to search for.
+- `start`: The index to start the search.
**Returns:**
-A `Text` value representing the C-style string.
+`!Match` if the target [pattern](patterns.md) is not found, otherwise a `Match`
+struct containing information about the match.
**Example:**
```tomo
->> Text.from_c_string(CString("Hello"))
-= "Hello"
+>> " #one #two #three ":find($/#{id}/, start=-999)
+= none : Match?
+>> " #one #two #three ":find($/#{id}/, start=999)
+= none : Match?
+>> " #one #two #three ":find($/#{id}/)
+= Match(text="#one", index=2, captures=["one"]) : Match?
+>> " #one #two #three ":find("{id}", start=6)
+= Match(text="#two", index=9, captures=["two"]) : Match?
```
---
-### `from_codepoint_names`
+### `find_all`
**Description:**
-Returns text that has the given codepoint names (according to the Unicode
-specification) as its codepoints. Note: the text will be normalized, so the
-resulting text's codepoints may not exactly match the input codepoints.
+Finds all occurrences of a [pattern](patterns.md) in the given text.
**Signature:**
```tomo
-func from_codepoint_names(codepoint_names: [Text] -> [Text])
+func find_all(text: Text, pattern: Pattern -> [Match])
```
**Parameters:**
-- `codepoint_names`: The names of each codepoint in the desired text. Names
- are case-insentive.
+- `text`: The text to be searched.
+- `pattern`: The [pattern](patterns.md) to search for.
**Returns:**
-A new text with the specified codepoints after normalization has been applied.
-Any invalid names are ignored.
+An array of every match of the [pattern](patterns.md) in the given text.
+Note: if `text` or `pattern` is empty, an empty array will be returned.
**Example:**
```tomo
->> Text.from_codepoint_names([
- "LATIN CAPITAL LETTER A WITH RING ABOVE",
- "LATIN SMALL LETTER K",
- "LATIN SMALL LETTER E",
-]
-= "Åke"
+>> " #one #two #three ":find_all($/#{alpha}/)
+= [Match(text="#one", index=2, captures=["one"]), Match(text="#two", index=8, captures=["two"]), Match(text="#three", index=13, captures=["three"])]
+
+>> " ":find_all("{alpha}")
+= []
+
+>> " foo(baz(), 1) doop() ":find_all("{id}(?)")
+= [Match(text="foo(baz(), 1)", index=2, captures=["foo", "baz(), 1"]), Match(text="doop()", index=17, captures=["doop", ""])]
+
+>> "":find_all($//)
+= []
+
+>> "Hello":find_all($//)
+= []
```
---
-### `from_codepoints`
+### `from`
**Description:**
-Returns text that has been constructed from the given UTF32 codepoints. Note:
-the text will be normalized, so the resulting text's codepoints may not exactly
-match the input codepoints.
+Get a slice of the text, starting at the given position.
**Signature:**
```tomo
-func from_codepoint_names(codepoints: [Int32] -> [Text])
+func from(text: Text, first: Int -> Text)
```
**Parameters:**
-- `codepoints`: The UTF32 codepoints in the desired text.
+- `text`: The text to be sliced.
+- `frist`: The index of the first grapheme cluster to include (1-indexed).
**Returns:**
-A new text with the specified codepoints after normalization has been applied.
+The text from the given grapheme cluster to the end of the text. Note: a
+negative index counts backwards from the end of the text, so `-1` refers to the
+last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to
+the length of the string.
**Example:**
```tomo
->> Text.from_codepoints([197[32], 107[32], 101[32]])
-= "Åke"
+>> "hello":from(2)
+= "ello"
+
+>> "hello":from(-2)
+= "lo"
```
---
@@ -664,108 +696,87 @@ A new text based on the input UTF8 bytes after normalization has been applied.
---
-### `find`
+### `from_c_string`
**Description:**
-Finds the first occurrence of a [pattern](patterns.md) in the given text (if
-any).
+Converts a C-style string to a `Text` value.
**Signature:**
```tomo
-func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)
+func from_c_string(str: CString -> Text)
```
**Parameters:**
-- `text`: The text to be searched.
-- `pattern`: The [pattern](patterns.md) to search for.
-- `start`: The index to start the search.
+- `str`: The C-style string to be converted.
**Returns:**
-`!Match` if the target [pattern](patterns.md) is not found, otherwise a `Match`
-struct containing information about the match.
+A `Text` value representing the C-style string.
**Example:**
```tomo
->> " #one #two #three ":find($/#{id}/, start=-999)
-= none : Match?
->> " #one #two #three ":find($/#{id}/, start=999)
-= none : Match?
->> " #one #two #three ":find($/#{id}/)
-= Match(text="#one", index=2, captures=["one"]) : Match?
->> " #one #two #three ":find("{id}", start=6)
-= Match(text="#two", index=9, captures=["two"]) : Match?
+>> Text.from_c_string(CString("Hello"))
+= "Hello"
```
---
-### `find_all`
+### `from_codepoint_names`
**Description:**
-Finds all occurrences of a [pattern](patterns.md) in the given text.
+Returns text that has the given codepoint names (according to the Unicode
+specification) as its codepoints. Note: the text will be normalized, so the
+resulting text's codepoints may not exactly match the input codepoints.
**Signature:**
```tomo
-func find_all(text: Text, pattern: Pattern -> [Match])
+func from_codepoint_names(codepoint_names: [Text] -> [Text])
```
**Parameters:**
-- `text`: The text to be searched.
-- `pattern`: The [pattern](patterns.md) to search for.
+- `codepoint_names`: The names of each codepoint in the desired text. Names
+ are case-insentive.
**Returns:**
-An array of every match of the [pattern](patterns.md) in the given text.
-Note: if `text` or `pattern` is empty, an empty array will be returned.
+A new text with the specified codepoints after normalization has been applied.
+Any invalid names are ignored.
**Example:**
```tomo
->> " #one #two #three ":find_all($/#{alpha}/)
-= [Match(text="#one", index=2, captures=["one"]), Match(text="#two", index=8, captures=["two"]), Match(text="#three", index=13, captures=["three"])]
-
->> " ":find_all("{alpha}")
-= []
-
->> " foo(baz(), 1) doop() ":find_all("{id}(?)")
-= [Match(text="foo(baz(), 1)", index=2, captures=["foo", "baz(), 1"]), Match(text="doop()", index=17, captures=["doop", ""])]
-
->> "":find_all($//)
-= []
-
->> "Hello":find_all($//)
-= []
+>> Text.from_codepoint_names([
+ "LATIN CAPITAL LETTER A WITH RING ABOVE",
+ "LATIN SMALL LETTER K",
+ "LATIN SMALL LETTER E",
+]
+= "Åke"
```
---
-### `from`
+### `from_codepoints`
**Description:**
-Get a slice of the text, starting at the given position.
+Returns text that has been constructed from the given UTF32 codepoints. Note:
+the text will be normalized, so the resulting text's codepoints may not exactly
+match the input codepoints.
**Signature:**
```tomo
-func from(text: Text, first: Int -> Text)
+func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
-- `text`: The text to be sliced.
-- `frist`: The index of the first grapheme cluster to include (1-indexed).
+- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
-The text from the given grapheme cluster to the end of the text. Note: a
-negative index counts backwards from the end of the text, so `-1` refers to the
-last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to
-the length of the string.
+A new text with the specified codepoints after normalization has been applied.
**Example:**
```tomo
->> "hello":from(2)
-= "ello"
-
->> "hello":from(-2)
-= "lo"
+>> Text.from_codepoints([197[32], 107[32], 101[32]])
+= "Åke"
```
---
@@ -887,67 +898,67 @@ The lowercase version of the text.
---
-### `matches`
+### `map`
**Description:**
-Checks if the `Text` matches target [pattern](patterns.md) and returns an array
-of the matching text captures or a null value if the entire text doesn't match
-the pattern.
+For each occurrence of the given [pattern](patterns.md), replace the text with
+the result of calling the given function on that match.
**Signature:**
```tomo
-func matches(text: Text, pattern: Pattern -> [Text])
+func map(text: Text, pattern: Pattern, fn: func(text:Match)->Text -> Text, recursive: Bool = yes)
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
+- `fn`: The function to apply to each match.
+- `recursive`: Whether to recursively map `fn` to each of the captures of the
+ pattern before handing them to `fn`.
**Returns:**
-An array of the matching text captures if the entire text matches the pattern,
-or a null value otherwise.
+The text with the matching parts replaced with the result of applying the given
+function to each.
**Example:**
```tomo
->> "hello world":matches($/{id}/)
-= none : [Text]?
-
->> "hello world":matches($/{id} {id}/)
-= ["hello", "world"] : [Text]?
+>> "hello world":map($/world/, func(m:Match): m.text:upper())
+= "hello WORLD"
+>> "Some nums: 1 2 3 4":map($/{int}/, func(m:Match): "$(Int.parse(m.text)! + 10)")
+= "Some nums: 11 12 13 14"
```
---
-### `map`
+### `matches`
**Description:**
-For each occurrence of the given [pattern](patterns.md), replace the text with
-the result of calling the given function on that match.
+Checks if the `Text` matches target [pattern](patterns.md) and returns an array
+of the matching text captures or a null value if the entire text doesn't match
+the pattern.
**Signature:**
```tomo
-func map(text: Text, pattern: Pattern, fn: func(text:Match)->Text -> Text, recursive: Bool = yes)
+func matches(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
-- `fn`: The function to apply to each match.
-- `recursive`: Whether to recursively map `fn` to each of the captures of the
- pattern before handing them to `fn`.
**Returns:**
-The text with the matching parts replaced with the result of applying the given
-function to each.
+An array of the matching text captures if the entire text matches the pattern,
+or a null value otherwise.
**Example:**
```tomo
->> "hello world":map($/world/, func(m:Match): m.text:upper())
-= "hello WORLD"
->> "Some nums: 1 2 3 4":map($/{int}/, func(m:Match): "$(Int.parse(m.text)! + 10)")
-= "Some nums: 11 12 13 14"
+>> "hello world":matches($/{id}/)
+= none : [Text]?
+
+>> "hello world":matches($/{id} {id}/)
+= ["hello", "world"] : [Text]?
```
---
@@ -1355,3 +1366,28 @@ The uppercase version of the text.
>> "amélie":upper()
= "AMÉLIE"
```
+
+---
+
+### `utf32_codepoints`
+
+**Description:**
+Returns an array of Unicode code points for UTF32 encoding of the text.
+
+**Signature:**
+```tomo
+func utf32_codepoints(text: Text -> [Int32])
+```
+
+**Parameters:**
+
+- `text`: The text from which to extract Unicode code points.
+
+**Returns:**
+An array of 32-bit integer Unicode code points (`[Int32]`).
+
+**Example:**
+```tomo
+>> "Amélie":utf32_codepoints()
+= [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32]
+```
diff --git a/docs/threads.md b/docs/threads.md
index 4d91e8bd..1ccacc38 100644
--- a/docs/threads.md
+++ b/docs/threads.md
@@ -6,64 +6,56 @@ through [mutex-guarded datastructures](mutexed.md).
## Thread Methods
-### `new`
+- [`func cancel(thread: Thread)`](#`cancel)
+- [`func detach(thread: Thread)`](#`detach)
+- [`func join(thread: Thread)`](#`join)
+- [`func new(fn: func(->Void) -> Thread)`](#`new)
+
+### `cancel`
**Description:**
-Creates a new thread to execute a specified function.
+Requests the cancellation of a specified thread.
**Signature:**
```tomo
-func new(fn: func(->Void) -> Thread)
+func cancel(thread: Thread)
```
**Parameters:**
-- `fn`: The function to be executed by the new thread.
+- `thread`: The thread to cancel.
**Returns:**
-A new `Thread` object representing the created thread.
+Nothing.
**Example:**
```tomo
->> jobs := |Int|
->> results := |Int|
->> thread := Thread.new(func():
- repeat:
- input := jobs:get()
- results:give(input + 10
-)
-= Thread<0x12345678>
->> jobs:give(10)
->> results:get()
-= 11
+>> thread:cancel()
```
---
-### `cancel`
+### `detach`
**Description:**
-Requests the cancellation of a specified thread.
+Detaches a specified thread, allowing it to run independently.
**Signature:**
```tomo
-func cancel(thread: Thread)
+func detach(thread: Thread)
```
**Parameters:**
-- `thread`: The thread to cancel.
+- `thread`: The thread to detach.
**Returns:**
Nothing.
**Example:**
```tomo
->> thread:cancel()
+>> thread:detach()
```
-
----
-
### `join`
**Description:**
@@ -88,24 +80,34 @@ Nothing.
---
-### `detach`
+### `new`
**Description:**
-Detaches a specified thread, allowing it to run independently.
+Creates a new thread to execute a specified function.
**Signature:**
```tomo
-func detach(thread: Thread)
+func new(fn: func(->Void) -> Thread)
```
**Parameters:**
-- `thread`: The thread to detach.
+- `fn`: The function to be executed by the new thread.
**Returns:**
-Nothing.
+A new `Thread` object representing the created thread.
**Example:**
```tomo
->> thread:detach()
+>> jobs := |Int|
+>> results := |Int|
+>> thread := Thread.new(func():
+ repeat:
+ input := jobs:get()
+ results:give(input + 10
+)
+= Thread<0x12345678>
+>> jobs:give(10)
+>> results:get()
+= 11
```
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-01 20:48:35 +0000