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

Shorten API docs

Browse Source
This commit is contained in:
Bruce Hill 2025-03-05 00:40:00 -05:00
parent dba2d62d15
commit 9a3162633d
13 changed files with 0 additions and 852 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/README.md
View File

@ -39,8 +39,6 @@ Information about Tomo's built-in types can be found here:
## Built-in Functions
### `ask`
**Description:**
Gets a line of user input text with a prompt.
**Signature:**
@ -48,8 +46,6 @@ Gets a line of user input text with a prompt.
func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Void)
```
**Parameters:**
- `prompt`: The text to print as a prompt before getting the input.
- `bold`: Whether or not to print make the prompt appear bold on a console
using the ANSI escape sequence `\x1b[1m`.
@ -74,8 +70,6 @@ something went wrong (e.g. the user hit `Ctrl-D`).
---
### `exit`
**Description:**
Exits the program with a given status and optionally prints a message.
**Signature:**
@ -83,8 +77,6 @@ Exits the program with a given status and optionally prints a message.
func ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)
```
**Parameters:**
- `message`: If nonempty, this message will be printed (with a newline) before
exiting.
- `status`: The status code that the program with exit with (default: 1, which
@ -101,8 +93,6 @@ exit(status=1, "Goodbye forever!")
---
### `say`
**Description:**
Prints a message to the console.
**Signature:**
@ -110,8 +100,6 @@ Prints a message to the console.
func say(text:Text, newline:Bool = yes -> Void)
```
**Parameters:**
- `text`: The text to print.
- `newline`: Whether or not to print a newline after the text.
@ -127,8 +115,6 @@ say("world!")
---
### `sleep`
**Description:**
Pause execution for a given number of seconds.
**Signature:**
@ -136,8 +122,6 @@ Pause execution for a given number of seconds.
func sleep(seconds: Num -> Void)
```
**Parameters:**
- `seconds`: How many seconds to sleep for.
**Returns:**
@ -151,8 +135,6 @@ sleep(1.5)
---
### `fail`
**Description:**
Prints a message to the console, aborts the program, and prints a stack trace.
**Signature:**
@ -160,8 +142,6 @@ Prints a message to the console, aborts the program, and prints a stack trace.
func fail(message:Text -> Abort)
```
**Parameters:**
- `message`: The error message to print.
**Returns:**
@ -175,8 +155,6 @@ fail("Oh no!")
---
### `now`
**Description:**
Gets the current time. This is an alias for `Moment.now()`.
**Signature:**
@ -184,8 +162,6 @@ Gets the current time. This is an alias for `Moment.now()`.
func now(->Moment)
```
**Parameters:**
None.
**Returns:**

104
docs/arrays.md
View File

@ -260,8 +260,6 @@ variable or dereference a heap pointer, it may trigger copy-on-write behavior.
- [`unique(arr: [T] -> {T})`](#unique)
### `binary_search`
**Description:**
Performs a binary search on a sorted array.
**Signature:**
@ -269,8 +267,6 @@ Performs a binary search on a sorted array.
func binary_search(arr: [T], by: func(x,y:&T->Int32) = 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.
@ -296,8 +292,6 @@ place where it would be found if it were inserted and the array were sorted.
---
### `by`
**Description:**
Creates a new array with elements spaced by the specified step value.
**Signature:**
@ -305,8 +299,6 @@ Creates a new array with elements spaced by the specified step value.
func by(arr: [T], step: Int -> [T])
```
**Parameters:**
- `arr`: The original array.
- `step`: The step value for selecting elements.
@ -322,8 +314,6 @@ A new array with every `step`-th element from the original array.
---
### `clear`
**Description:**
Clears all elements from the array.
**Signature:**
@ -331,8 +321,6 @@ Clears all elements from the array.
func clear(arr: @[T] -> Void)
```
**Parameters:**
- `arr`: The mutable reference to the array to be cleared.
**Returns:**
@ -346,8 +334,6 @@ Nothing.
---
### `counts`
**Description:**
Counts the occurrences of each element in the array.
**Signature:**
@ -355,8 +341,6 @@ Counts the occurrences of each element in the array.
func counts(arr: [T] -> {T,Int})
```
**Parameters:**
- `arr`: The array to count elements in.
**Returns:**
@ -371,8 +355,6 @@ A table mapping each element to its count.
---
### `find`
**Description:**
Finds the index of the first occurrence of an element (if any).
**Signature:**
@ -380,8 +362,6 @@ Finds the index of the first occurrence of an element (if any).
func find(arr: [T], target: T -> Int?)
```
**Parameters:**
- `arr`: The array to search through.
- `item`: The item to find in the array.
@ -400,8 +380,6 @@ The index of the first occurrence or `!Int` if not found.
---
### `first`
**Description:**
Find the index of the first item that matches a predicate function (if any).
**Signature:**
@ -409,8 +387,6 @@ Find the index of the first item that matches a predicate function (if any).
func first(arr: [T], predicate: func(item:&T -> Bool) -> Int)
```
**Parameters:**
- `arr`: The array to search through.
- `predicate`: A function that returns `yes` if the item should be returned or
`no` if it should not.
@ -430,8 +406,6 @@ item matches.
---
### `from`
**Description:**
Returns a slice of the array starting from a specified index.
**Signature:**
@ -439,8 +413,6 @@ Returns a slice of the array starting from a specified index.
func from(arr: [T], first: Int -> [T])
```
**Parameters:**
- `arr`: The original array.
- `first`: The index to start from.
@ -456,8 +428,6 @@ A new array starting from the specified index.
---
### `has`
**Description:**
Checks if the array has any elements.
**Signature:**
@ -465,8 +435,6 @@ Checks if the array has any elements.
func has(arr: [T] -> Bool)
```
**Parameters:**
- `arr`: The array to check.
**Returns:**
@ -481,8 +449,6 @@ func has(arr: [T] -> Bool)
---
### `heap_pop`
**Description:**
Removes and returns the top element of a heap or `none` if the array is empty.
By default, this is the *minimum* value in the heap.
@ -491,8 +457,6 @@ By default, this is the *minimum* value in the heap.
func heap_pop(arr: @[T], by: func(x,y:&T->Int32) = 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.
@ -511,8 +475,6 @@ The removed top element of the heap or `none` if the array is empty.
---
### `heap_push`
**Description:**
Adds an element to the heap and maintains the heap property. By default, this
is a *minimum* heap.
@ -521,8 +483,6 @@ is a *minimum* heap.
func 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
@ -539,8 +499,6 @@ Nothing.
---
### `heapify`
**Description:**
Converts an array into a heap.
**Signature:**
@ -548,8 +506,6 @@ Converts an array into a heap.
func heapify(arr: @[T], by: func(x,y:&T->Int32) = 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.
@ -566,8 +522,6 @@ Nothing.
---
### `insert`
**Description:**
Inserts an element at a specified position in the array.
**Signature:**
@ -575,8 +529,6 @@ Inserts an element at a specified position in the array.
func 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
@ -601,8 +553,6 @@ Nothing.
---
### `insert_all`
**Description:**
Inserts an array of items at a specified position in the array.
**Signature:**
@ -610,8 +560,6 @@ Inserts an array of items at a specified position in the array.
func 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
@ -636,8 +584,6 @@ arr:insert_all([99, 100], at=2)
---
### `pop`
**Description:**
Removes and returns an item from the array. If the given index is present in
the array, the item at that index will be removed and the array will become one
element shorter.
@ -647,8 +593,6 @@ element shorter.
func pop(arr: &[T], index: Int = -1 -> T?)
```
**Parameters:**
- `arr`: The array to remove an item from.
- `index`: The index from which to remove the item (default: the last item).
@ -674,8 +618,6 @@ otherwise the item at the given index.
---
### `random`
**Description:**
Selects a random element from the array.
**Signature:**
@ -683,8 +625,6 @@ Selects a random element from the array.
func random(arr: [T], rng: RNG = random -> T)
```
**Parameters:**
- `arr`: The array from which to select a random element.
- `rng`: The [random number generator](rng.md) to use.
@ -700,8 +640,6 @@ A random element from the array.
---
### `remove_at`
**Description:**
Removes elements from the array starting at a specified index.
**Signature:**
@ -709,8 +647,6 @@ Removes elements from the array starting at a specified index.
func 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`).
@ -733,8 +669,6 @@ arr:remove_at(2, count=2)
---
### `remove_item`
**Description:**
Removes all occurrences of a specified item from the array.
**Signature:**
@ -742,8 +676,6 @@ Removes all occurrences of a specified item from the array.
func 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).
@ -766,8 +698,6 @@ arr:remove_item(20, max_count=1)
---
### `reversed`
**Description:**
Returns a reversed slice of the array.
**Signature:**
@ -775,8 +705,6 @@ Returns a reversed slice of the array.
func reversed(arr: [T] -> [T])
```
**Parameters:**
- `arr`: The array to be reversed.
**Returns:**
@ -791,8 +719,6 @@ A slice of the array with elements in reverse order.
---
### `sample`
**Description:**
Selects a sample of elements from the array, optionally with weighted
probabilities.
@ -801,8 +727,6 @@ probabilities.
func sample(arr: [T], count: Int, weights: [Num]? = ![Num], rng: RNG = random -> [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
@ -831,8 +755,6 @@ A list of sampled elements from the array.
---
### `shuffle`
**Description:**
Shuffles the elements of the array in place.
**Signature:**
@ -840,8 +762,6 @@ Shuffles the elements of the array in place.
func shuffle(arr: @[T], rng: RNG = random -> Void)
```
**Parameters:**
- `arr`: The mutable reference to the array to be shuffled.
- `rng`: The [random number generator](rng.md) to use.
@ -856,8 +776,6 @@ Nothing.
---
### `shuffled`
**Description:**
Creates a new array with elements shuffled.
**Signature:**
@ -865,8 +783,6 @@ Creates a new array with elements shuffled.
func shuffled(arr: [T], rng: RNG = random -> [T])
```
**Parameters:**
- `arr`: The array to be shuffled.
- `rng`: The [random number generator](rng.md) to use.
@ -882,8 +798,6 @@ A new array with shuffled elements.
---
### `slice`
**Description:**
Returns a slice of the array spanning the given indices (inclusive).
**Signature:**
@ -891,8 +805,6 @@ Returns a slice of the array spanning the given indices (inclusive).
func slice(arr: [T], from: Int, to: Int -> [T])
```
**Parameters:**
- `arr`: The original array.
- `from`: The first index to include.
- `to`: The last index to include.
@ -914,8 +826,6 @@ second-to-last, and so on.
---
### `sort`
**Description:**
Sorts the elements of the array in place in ascending order (small to large).
**Signature:**
@ -923,8 +833,6 @@ Sorts the elements of the array in place in ascending order (small to large).
func 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.
@ -947,8 +855,6 @@ arr:sort(func(a,b:&Int): a:abs() <> b:abs())
---
### `sorted`
**Description:**
Creates a new array with elements sorted.
**Signature:**
@ -956,8 +862,6 @@ Creates a new array with elements sorted.
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.
@ -977,8 +881,6 @@ A new array with sorted elements.
---
### `to`
**Description:**
Returns a slice of the array from the start of the original array up to a specified index (inclusive).
**Signature:**
@ -986,8 +888,6 @@ Returns a slice of the array from the start of the original array up to a specif
to(arr: [T], last: Int -> [T])
```
**Parameters:**
- `arr`: The original array.
- `last`: The index up to which elements should be included.
@ -1006,8 +906,6 @@ A new array containing elements from the start up to the specified index.
---
### `unique`
**Description:**
Returns a Set that contains the unique elements of the array.
**Signature:**
@ -1015,8 +913,6 @@ Returns a Set that contains the unique elements of the array.
unique(arr: [T] -> {T})
```
**Parameters:**
- `arr`: The array to process.
**Returns:**

4
docs/booleans.md
View File

@ -10,8 +10,6 @@ This documentation provides details on boolean functions available in the API.
- [`func parse(text: Text -> Bool?)`](#parse)
### `parse`
**Description:**
Converts a string representation of a boolean value into a boolean. Acceptable
boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`,
`true`/`false`, `on`/`off`.
@ -21,8 +19,6 @@ boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`,
func parse(text: Text -> Bool?)
```
**Parameters:**
- `text`: The string containing the boolean value.
**Returns:**

56
docs/integers.md
View File

@ -138,8 +138,6 @@ can be called either on the type itself: `Int.sqrt(x)` or as a method call:
- [`func to(first: Int, last: Int, step : Int? = none:Int -> func(->Int?))`](#to)
### `abs`
**Description:**
Calculates the absolute value of an integer.
**Signature:**
@ -147,8 +145,6 @@ Calculates the absolute value of an integer.
func abs(x: Int -> Int)
```
**Parameters:**
- `x`: The integer whose absolute value is to be calculated.
**Returns:**
@ -163,8 +159,6 @@ The absolute value of `x`.
---
### `choose`
**Description:**
Computes the binomial coefficient of the given numbers (the equivalent of `n`
choose `k` in combinatorics). This is equal to `n:factorial()/(k:factorial() *
(n-k):factorial())`.
@ -174,8 +168,6 @@ choose `k` in combinatorics). This is equal to `n:factorial()/(k:factorial() *
func choose(n: Int, k: Int -> Int)
```
**Parameters:**
- `n`: The number of things to choose from.
- `k`: The number of things to be chosen.
@ -192,8 +184,6 @@ 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.
@ -202,8 +192,6 @@ that range.
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.
@ -220,8 +208,6 @@ The first argument clamped between the other two arguments.
---
### `factorial`
**Description:**
Computes the factorial of an integer.
**Signature:**
@ -229,8 +215,6 @@ Computes the factorial of an integer.
func factorial(n: Int -> Text)
```
**Parameters:**
- `n`: The integer to compute the factorial of.
**Returns:**
@ -245,8 +229,6 @@ The factorial of the given integer.
---
### `format`
**Description:**
Formats an integer as a string with a specified number of digits.
**Signature:**
@ -254,8 +236,6 @@ Formats an integer as a string with a specified number of digits.
func format(i: Int, digits: Int = 0 -> Text)
```
**Parameters:**
- `i`: The integer to be formatted.
- `digits`: The minimum number of digits to which the integer should be padded. Default is `0`.
@ -271,8 +251,6 @@ A string representation of the integer, padded to the specified number of digits
---
### `hex`
**Description:**
Converts an integer to its hexadecimal representation.
**Signature:**
@ -280,8 +258,6 @@ Converts an integer to its hexadecimal representation.
func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)
```
**Parameters:**
- `i`: The integer to be converted.
- `digits`: The minimum number of digits in the output string. Default is `0`.
- `uppercase`: Whether to use uppercase letters for hexadecimal digits. Default is `yes`.
@ -299,8 +275,6 @@ The hexadecimal string representation of the integer.
---
### `is_prime`
**Description:**
Determines if an integer is a prime number.
**Note:**
@ -314,8 +288,6 @@ for more details.
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`.
@ -333,8 +305,6 @@ func is_prime(x: Int, reps: Int = 50 -> Bool)
---
### `next_prime`
**Description:**
Finds the next prime number greater than the given integer.
**Note:**
@ -348,8 +318,6 @@ for more details.
func next_prime(x: Int -> Int)
```
**Parameters:**
- `x`: The integer after which to find the next prime.
**Returns:**
@ -364,8 +332,6 @@ The next prime number greater than `x`.
---
### `octal`
**Description:**
Converts an integer to its octal representation.
**Signature:**
@ -373,8 +339,6 @@ Converts an integer to its octal representation.
func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)
```
**Parameters:**
- `i`: The integer to be converted.
- `digits`: The minimum number of digits in the output string. Default is `0`.
- `prefix`: Whether to include a "0o" prefix. Default is `yes`.
@ -391,8 +355,6 @@ The octal string representation of the integer.
---
### `onward`
**Description:**
Return an iterator that counts infinitely from the starting integer (with an
optional step size).
@ -401,8 +363,6 @@ optional step size).
func onward(first: Int, step: Int = 1 -> Text)
```
**Parameters:**
- `first`: The starting integer.
- `step`: The increment step size (default: 1).
@ -422,8 +382,6 @@ for i in 5:onward():
---
### `parse`
**Description:**
Converts a text representation of an integer into an integer.
**Signature:**
@ -431,8 +389,6 @@ Converts a text representation of an integer into an integer.
func parse(text: Text -> Int?)
```
**Parameters:**
- `text`: The text containing the integer.
**Returns:**
@ -459,8 +415,6 @@ of the representable range or if the entire text can't be parsed as an integer,
---
### `prev_prime`
**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.
@ -476,8 +430,6 @@ for more details.
func prev_prime(x: Int -> Int)
```
**Parameters:**
- `x`: The integer before which to find the previous prime.
**Returns:**
@ -492,8 +444,6 @@ The previous prime number less than `x`.
---
### `sqrt`
**Description:**
Calculates the square root of an integer.
**Signature:**
@ -501,8 +451,6 @@ Calculates the square root of an integer.
func sqrt(x: Int -> Int)
```
**Parameters:**
- `x`: The integer whose square root is to be calculated.
**Returns:**
@ -519,8 +467,6 @@ The integer part of the square root of `x`.
---
### `to`
**Description:**
Returns an iterator function that iterates over the range of numbers specified.
Iteration is assumed to be nonempty and
@ -529,8 +475,6 @@ Iteration is assumed to be nonempty and
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`.

92
docs/moments.md
View File

@ -88,8 +88,6 @@ Time zones are specified by name, such as `America/New_York` or `UTC`.
- [`func unix_timestamp(moment:Moment->Int64)`](#unix_timestamp)
### `after`
**Description:**
Returns a Moment that occurs after the specified time differences. Time
differences may be either positive or negative.
@ -107,8 +105,6 @@ calculated.
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)
```
**Parameters:**
- `moment`: The moment used as a starting point.
- `seconds` (optional): An amount of seconds to offset the moment (default: 0).
- `minutes` (optional): An amount of minutes to offset the moment (default: 0).
@ -132,8 +128,6 @@ A new `Moment` offset by the given amount.
---
### `date`
**Description:**
Return a text representation of the moment using the `"%F"` format
specifier, which gives the date in `YYYY-MM-DD` form.
@ -142,8 +136,6 @@ specifier, which gives the date in `YYYY-MM-DD` form.
func date(moment: Moment, timezone : Text? = !Text -> Text)
```
**Parameters:**
- `moment`: The moment to get the date from.
- `timezone` (optional): If specified, give the date in the given timezone (otherwise, use the current local timezone).
@ -159,8 +151,6 @@ The date in `YYYY-MM-DD` format.
---
### `day_of_month`
**Description:**
Return the integer day of the month (1-31).
**Signature:**
@ -168,8 +158,6 @@ Return the integer day of the month (1-31).
func day_of_month(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the day of the month from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -185,8 +173,6 @@ The day of the month as an integer (1-31).
---
### `day_of_week`
**Description:**
Return the integer day of the week (1-7), where 1 = Sunday, 2 = Monday,
3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.
@ -195,8 +181,6 @@ Return the integer day of the week (1-7), where 1 = Sunday, 2 = Monday,
func day_of_week(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the day of the week from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -212,8 +196,6 @@ The day of the week as an integer (1-7).
---
### `day_of_year`
**Description:**
Return the integer day of the year (1-366, including leap years).
**Signature:**
@ -221,8 +203,6 @@ Return the integer day of the year (1-366, including leap years).
func day_of_year(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the day of the year from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -238,8 +218,6 @@ The day of the year as an integer (1-366).
---
### `format`
**Description:**
Using the C-style [`strftime`](https://linux.die.net/man/3/strftime) format
options, return a text representation of the given date in the given format. If
`timezone` is specified, use that timezone instead of the current local
@ -250,8 +228,6 @@ timezone.
func format(moment: Moment, format: Text = "%Y-%m-%dT%H:%M:%S%z", timezone : Text? = !Text -> Text)
```
**Parameters:**
- `moment`: The moment to format.
- `format`: The `strftime` format to use (default: `"%Y-%m-%dT%H:%M:%S%z"`).
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -268,8 +244,6 @@ Nothing.
---
### `from_unix_timestamp`
**Description:**
Return a moment object that represents the same moment in time as
the given UNIX epoch timestamp (seconds since January 1, 1970 UTC).
@ -278,8 +252,6 @@ the given UNIX epoch timestamp (seconds since January 1, 1970 UTC).
func from_unix_timestamp(timestamp: Int64 -> Moment)
```
**Parameters:**
- `timestamp`: The UNIX timestamp.
**Returns:**
@ -293,8 +265,6 @@ A `Moment` object representing the same moment as the given UNIX timestamp.
```
### `get_local_timezone`
**Description:**
Get the local timezone's name (e.g. `America/New_York` or `UTC`. By default,
this value is read from `/etc/localtime`, however, this can be overridden by
calling `Moment.set_local_timezone(...)`.
@ -304,8 +274,6 @@ calling `Moment.set_local_timezone(...)`.
func get_local_timezone(->Text)
```
**Parameters:**
None.
**Returns:**
@ -320,8 +288,6 @@ The name of the current local timezone.
---
### `hour`
**Description:**
Return the hour of the day as an integer (1-24).
**Signature:**
@ -329,8 +295,6 @@ Return the hour of the day as an integer (1-24).
func hour(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the hour from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -346,8 +310,6 @@ The hour of the day as an integer (1-24).
---
### `hours_till`
**Description:**
Return the number of hours until a given moment.
**Signature:**
@ -355,8 +317,6 @@ Return the number of hours until a given moment.
func hours_till(moment: Moment, then:Moment -> Num)
```
**Parameters:**
- `moment`: The starting point moment.
- `then`: Another moment that we want to calculate the time offset from (in hours).
@ -373,8 +333,6 @@ the_future := now():after(hours=1, minutes=30)
---
### `minute`
**Description:**
Return the minute of the day as an integer (0-59).
**Signature:**
@ -382,8 +340,6 @@ Return the minute of the day as an integer (0-59).
func minute(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the minute from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -399,8 +355,6 @@ The minute of the hour as an integer (0-59).
---
### `minutes_till`
**Description:**
Return the number of minutes until a given moment.
**Signature:**
@ -408,8 +362,6 @@ Return the number of minutes until a given moment.
func minutes_till(moment: Moment, then:Moment -> Num)
```
**Parameters:**
- `moment`: The starting point moment.
- `then`: Another moment that we want to calculate the time offset from (in minutes).
@ -426,8 +378,6 @@ the_future := now():after(minutes=1, seconds=30)
---
### `month`
**Description:**
Return the month of the year as an integer (1-12).
**Signature:**
@ -435,8 +385,6 @@ Return the month of the year as an integer (1-12).
func month(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the month from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -452,8 +400,6 @@ The month of the year as an integer (1-12).
---
### `nanosecond`
**Description:**
Return the nanosecond of the second as an integer (0-999,999,999).
**Signature:**
@ -461,8 +407,6 @@ Return the nanosecond of the second as an integer (0-999,999,999).
func nanosecond(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the nanosecond from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -478,8 +422,6 @@ The nanosecond of the second as an integer (0-999,999,999).
---
### `new`
**Description:**
Return a new `Moment` object representing the given time parameters expressed
in local time. This function is the same as calling `Moment` directly as a
constructor.
@ -489,8 +431,6 @@ constructor.
func new(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Num = 0.0 -> Moment)
```
**Parameters:**
- `year`: The year.
- `month`: The month of the year (1-12).
- `day`: The day of the month (1-31).
@ -518,8 +458,6 @@ integer, an error will be raised.
---
### `now`
**Description:**
Get a `Moment` object representing the current date and time. This function
is the same as the global function `now()`.
@ -528,8 +466,6 @@ is the same as the global function `now()`.
func now(->Moment)
```
**Parameters:**
None.
**Returns:**
@ -544,8 +480,6 @@ Returns a `Moment` object representing the current date and time.
---
### `parse`
**Description:**
Return a new `Moment` object parsed from the given string in the given format,
or `none` if the value could not be successfully parsed.
@ -554,8 +488,6 @@ or `none` if the value could not be successfully parsed.
func parse(text: Text, format: Text = "%Y-%m-%dT%H:%M:%S%z" -> Moment?)
```
**Parameters:**
- `text`: The text to parse.
- `format`: The date format of the text being parsed (see:
[strptime](https://linux.die.net/man/3/strptime) for more info on this
@ -577,8 +509,6 @@ If the text was successfully parsed according to the given format, return a
---
### `relative`
**Description:**
Return a plain English textual representation of the approximate time difference
between two `Moment`s. For example: `5 minutes ago` or `1 day later`
@ -587,8 +517,6 @@ between two `Moment`s. For example: `5 minutes ago` or `1 day later`
func relative(moment: Moment, relative_to : Moment = Moment.now(), timezone : Text? = !Text -> Text)
```
**Parameters:**
- `moment`: The moment whose relative time you're getting.
- `relative_to` (optional): The time against which the relative time is calculated (default: `Moment.now()`).
- `timezone` (optional): If specified, perform calculations in the given
@ -614,8 +542,6 @@ ago"`, while moments in the future will have the suffix `" later"`.
---
### `second`
**Description:**
Return the second of the minute as an integer (0-59).
**Signature:**
@ -623,8 +549,6 @@ Return the second of the minute as an integer (0-59).
func second(moment: Moment, timezone : Text? = !Text -> Int)
```
**Parameters:**
- `moment`: The moment to get the second from.
- `timezone` (optional): If specified, use the given timezone (otherwise, use the current local timezone).
@ -640,8 +564,6 @@ The second of the hour as an integer (0-59).
---
### `seconds_till`
**Description:**
Return the number of seconds until a given moment.
**Signature:**
@ -649,8 +571,6 @@ Return the number of seconds until a given moment.
func seconds_till(moment: Moment, then:Moment -> Num)
```
**Parameters:**
- `moment`: The starting point moment.
- `then`: Another moment that we want to calculate the time offset from (in seconds).
@ -667,8 +587,6 @@ the_future := now():after(seconds=1)
---
### `set_local_timezone`
**Description:**
Set the current local timezone to a given value by name (e.g.
`America/New_York` or `UTC`). The local timezone is used as the default
timezone for performing calculations and constructing `Moment` objects from
@ -680,8 +598,6 @@ converted to text.
func set_local_timezone(timezone : Text? = !Text -> Void)
```
**Parameters:**
- `timezone` (optional): if specified, set the current local timezone to the
timezone with the given name. If null, reset the current local timezone to
the system default (the value referenced in `/etc/localtime`).
@ -697,8 +613,6 @@ Moment.set_local_timezone("America/Los_Angeles")
---
### `time`
**Description:**
Return a text representation of the time component of the given moment.
**Signature:**
@ -706,8 +620,6 @@ Return a text representation of the time component of the given moment.
func time(moment: Moment, seconds : Bool = no, am_pm : Bool = yes, timezone : Text? = !Text -> Text)
```
**Parameters:**
- `moment`: The moment whose time value you want to get.
- `seconds`: Whether to include seconds in the time (default: `no`).
- `am_pm`: Whether to use am/pm in the representation or use a 24-hour clock (default: `yes`).
@ -733,8 +645,6 @@ moment := Moment(2024, 9, 29, hours=13, minutes=59, seconds=30)
---
### `unix_timestamp`
**Description:**
Get the UNIX timestamp of the given moment (seconds since the UNIX epoch:
January 1, 1970 UTC).
@ -743,8 +653,6 @@ January 1, 1970 UTC).
func unix_timestamp(moment:Moment->Int64)
```
**Parameters:**
`moment`: The moment whose UNIX timestamp you want to get.
**Returns:**

196
docs/nums.md
View File

@ -170,8 +170,6 @@ called either on the type itself: `Num.sqrt(x)` or as a method call:
- [`func y1(x: Num -> Num)`](#y1)
### `abs`
**Description:**
Calculates the absolute value of a number.
**Signature:**
@ -179,8 +177,6 @@ Calculates the absolute value of a number.
func abs(n: Num -> Num)
```
**Parameters:**
- `n`: The number whose absolute value is to be computed.
**Returns:**
@ -195,8 +191,6 @@ The absolute value of `n`.
---
### `acos`
**Description:**
Computes the arc cosine of a number.
**Signature:**
@ -204,8 +198,6 @@ Computes the arc cosine of a number.
func acos(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the arc cosine is to be calculated.
**Returns:**
@ -220,8 +212,6 @@ The arc cosine of `x` in radians.
---
### `acosh`
**Description:**
Computes the inverse hyperbolic cosine of a number.
**Signature:**
@ -229,8 +219,6 @@ Computes the inverse hyperbolic cosine of a number.
func acosh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the inverse hyperbolic cosine is to be calculated.
**Returns:**
@ -245,8 +233,6 @@ The inverse hyperbolic cosine of `x`.
---
### `asin`
**Description:**
Computes the arc sine of a number.
**Signature:**
@ -254,8 +240,6 @@ Computes the arc sine of a number.
func asin(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the arc sine is to be calculated.
**Returns:**
@ -270,8 +254,6 @@ The arc sine of `x` in radians.
---
### `asinh`
**Description:**
Computes the inverse hyperbolic sine of a number.
**Signature:**
@ -279,8 +261,6 @@ Computes the inverse hyperbolic sine of a number.
func asinh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the inverse hyperbolic sine is to be calculated.
**Returns:**
@ -295,8 +275,6 @@ The inverse hyperbolic sine of `x`.
---
### `atan`
**Description:**
Computes the arc tangent of a number.
**Signature:**
@ -304,8 +282,6 @@ Computes the arc tangent of a number.
func atan(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the arc tangent is to be calculated.
**Returns:**
@ -320,8 +296,6 @@ The arc tangent of `x` in radians.
---
### `atan2`
**Description:**
Computes the arc tangent of the quotient of two numbers.
**Signature:**
@ -329,8 +303,6 @@ Computes the arc tangent of the quotient of two numbers.
func atan2(x: Num, y: Num -> Num)
```
**Parameters:**
- `x`: The numerator.
- `y`: The denominator.
@ -346,8 +318,6 @@ The arc tangent of `x/y` in radians.
---
### `atanh`
**Description:**
Computes the inverse hyperbolic tangent of a number.
**Signature:**
@ -355,8 +325,6 @@ Computes the inverse hyperbolic tangent of a number.
func atanh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the inverse hyperbolic tangent is to be calculated.
**Returns:**
@ -371,8 +339,6 @@ The inverse hyperbolic tangent of `x`.
---
### `cbrt`
**Description:**
Computes the cube root of a number.
**Signature:**
@ -380,8 +346,6 @@ Computes the cube root of a number.
func cbrt(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the cube root is to be calculated.
**Returns:**
@ -396,8 +360,6 @@ The cube root of `x`.
---
### `ceil`
**Description:**
Rounds a number up to the nearest integer.
**Signature:**
@ -405,8 +367,6 @@ Rounds a number up to the nearest integer.
func ceil(x: Num -> Num)
```
**Parameters:**
- `x`: The number to be rounded up.
**Returns:**
@ -421,8 +381,6 @@ 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.
@ -431,8 +389,6 @@ that range.
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.
@ -449,8 +405,6 @@ The first argument clamped between the other two arguments.
---
### `copysign`
**Description:**
Copies the sign of one number to another.
**Signature:**
@ -458,8 +412,6 @@ Copies the sign of one number to another.
func copysign(x: Num, y: Num -> Num)
```
**Parameters:**
- `x`: The number whose magnitude will be copied.
- `y`: The number whose sign will be copied.
@ -475,8 +427,6 @@ A number with the magnitude of `x` and the sign of `y`.
---
### `cos`
**Description:**
Computes the cosine of a number (angle in radians).
**Signature:**
@ -484,8 +434,6 @@ Computes the cosine of a number (angle in radians).
func cos(x: Num -> Num)
```
**Parameters:**
- `x`: The angle in radians.
**Returns:**
@ -500,8 +448,6 @@ The cosine of `x`.
---
### `cosh`
**Description:**
Computes the hyperbolic cosine of a number.
**Signature:**
@ -509,8 +455,6 @@ Computes the hyperbolic cosine of a number.
func cosh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the hyperbolic cosine is to be calculated.
**Returns:**
@ -525,8 +469,6 @@ The hyperbolic cosine of `x`.
---
### `erf`
**Description:**
Computes the error function of a number.
**Signature:**
@ -534,8 +476,6 @@ Computes the error function of a number.
func erf(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the error function is to be calculated.
**Returns:**
@ -550,8 +490,6 @@ The error function of `x`.
---
### `erfc`
**Description:**
Computes the complementary error function of a number.
**Signature:**
@ -559,8 +497,6 @@ Computes the complementary error function of a number.
func erfc(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the complementary error function is to be calculated.
**Returns:**
@ -575,8 +511,6 @@ The complementary error function of `x`.
---
### `exp`
**Description:**
Computes the exponential function \( e^x \) for a number.
**Signature:**
@ -584,8 +518,6 @@ Computes the exponential function \( e^x \) for a number.
func exp(x: Num -> Num)
```
**Parameters:**
- `x`: The exponent.
**Returns:**
@ -600,8 +532,6 @@ The value of \( e^x \).
---
### `exp2`
**Description:**
Computes \( 2^x \) for a number.
**Signature:**
@ -609,8 +539,6 @@ Computes \( 2^x \) for a number.
func exp2(x: Num -> Num)
```
**Parameters:**
- `x`: The exponent.
**Returns:**
@ -625,8 +553,6 @@ The value of \( 2^x \).
---
### `expm1`
**Description:**
Computes \( e^x - 1 \) for a number.
**Signature:**
@ -634,8 +560,6 @@ Computes \( e^x - 1 \) for a number.
func expm1(x: Num -> Num)
```
**Parameters:**
- `x`: The exponent.
**Returns:**
@ -650,8 +574,6 @@ The value of \( e^x - 1 \).
---
### `fdim`
**Description:**
Computes the positive difference between two numbers.
**Signature:**
@ -659,8 +581,6 @@ Computes the positive difference between two numbers.
func fdim(x: Num, y: Num -> Num)
```
**Parameters:**
- `x`: The first number.
- `y`: The second number.
@ -678,8 +598,6 @@ fd
---
### `floor`
**Description:**
Rounds a number down to the nearest integer.
**Signature:**
@ -687,8 +605,6 @@ Rounds a number down to the nearest integer.
func floor(x: Num -> Num)
```
**Parameters:**
- `x`: The number to be rounded down.
**Returns:**
@ -703,8 +619,6 @@ The largest integer less than or equal to `x`.
---
### `format`
**Description:**
Formats a number as a text with a specified precision.
**Signature:**
@ -712,8 +626,6 @@ Formats a number as a text with a specified precision.
func format(n: Num, precision: Int = 0 -> Text)
```
**Parameters:**
- `n`: The number to be formatted.
- `precision`: The number of decimal places. Default is `0`.
@ -729,8 +641,6 @@ A text representation of the number with the specified precision.
---
### `hypot`
**Description:**
Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
**Signature:**
@ -738,8 +648,6 @@ Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
func hypot(x: Num, y: Num -> Num)
```
**Parameters:**
- `x`: The first number.
- `y`: The second number.
@ -755,8 +663,6 @@ The Euclidean norm of `x` and `y`.
---
### `isfinite`
**Description:**
Checks if a number is finite.
**Signature:**
@ -764,8 +670,6 @@ Checks if a number is finite.
func isfinite(n: Num -> Bool)
```
**Parameters:**
- `n`: The number to be checked.
**Returns:**
@ -782,8 +686,6 @@ func isfinite(n: Num -> Bool)
---
### `isinf`
**Description:**
Checks if a number is infinite.
**Signature:**
@ -791,8 +693,6 @@ Checks if a number is infinite.
func isinf(n: Num -> Bool)
```
**Parameters:**
- `n`: The number to be checked.
**Returns:**
@ -809,8 +709,6 @@ func isinf(n: Num -> Bool)
---
### `j0`
**Description:**
Computes the Bessel function of the first kind of order 0.
**Signature:**
@ -818,8 +716,6 @@ Computes the Bessel function of the first kind of order 0.
func j0(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the Bessel function is to be calculated.
**Returns:**
@ -834,8 +730,6 @@ The Bessel function of the first kind of order 0 of `x`.
---
### `j1`
**Description:**
Computes the Bessel function of the first kind of order 1.
**Signature:**
@ -843,8 +737,6 @@ Computes the Bessel function of the first kind of order 1.
func j1(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the Bessel function is to be calculated.
**Returns:**
@ -859,8 +751,6 @@ The Bessel function of the first kind of order 1 of `x`.
---
### `log`
**Description:**
Computes the natural logarithm (base \( e \)) of a number.
**Signature:**
@ -868,8 +758,6 @@ Computes the natural logarithm (base \( e \)) of a number.
func log(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the natural logarithm is to be calculated.
**Returns:**
@ -884,8 +772,6 @@ The natural logarithm of `x`.
---
### `log10`
**Description:**
Computes the base-10 logarithm of a number.
**Signature:**
@ -893,8 +779,6 @@ Computes the base-10 logarithm of a number.
func log10(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the base-10 logarithm is to be calculated.
**Returns:**
@ -909,8 +793,6 @@ The base-10 logarithm of `x`.
---
### `log1p`
**Description:**
Computes \( \log(1 + x) \) for a number.
**Signature:**
@ -918,8 +800,6 @@ Computes \( \log(1 + x) \) for a number.
func log1p(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which \( \log(1 + x) \) is to be calculated.
**Returns:**
@ -934,8 +814,6 @@ The value of \( \log(1 + x) \).
---
### `log2`
**Description:**
Computes the base-2 logarithm of a number.
**Signature:**
@ -943,8 +821,6 @@ Computes the base-2 logarithm of a number.
func log2(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the base-2 logarithm is to be calculated.
**Returns:**
@ -959,8 +835,6 @@ The base-2 logarithm of `x`.
---
### `logb`
**Description:**
Computes the binary exponent (base-2 logarithm) of a number.
**Signature:**
@ -968,8 +842,6 @@ Computes the binary exponent (base-2 logarithm) of a number.
func logb(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the binary exponent is to be calculated.
**Returns:**
@ -984,8 +856,6 @@ The binary exponent of `x`.
---
### `mix`
**Description:**
Interpolates between two numbers based on a given amount.
**Signature:**
@ -993,8 +863,6 @@ Interpolates between two numbers based on a given amount.
func mix(amount: Num, x: Num, y: Num -> Num)
```
**Parameters:**
- `amount`: The interpolation factor (between `0` and `1`).
- `x`: The starting number.
- `y`: The ending number.
@ -1013,8 +881,6 @@ The interpolated number between `x` and `y` based on `amount`.
---
### `near`
**Description:**
Checks if two numbers are approximately equal within specified tolerances. If
two numbers are within an absolute difference or the ratio between the two is
small enough, they are considered near each other.
@ -1024,8 +890,6 @@ small enough, they are considered near each other.
func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
```
**Parameters:**
- `x`: The first number.
- `y`: The second number.
- `ratio`: The relative tolerance. Default is `1e-9`.
@ -1049,8 +913,6 @@ func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
---
### `nextafter`
**Description:**
Computes the next representable value after a given number towards a specified direction.
**Signature:**
@ -1058,8 +920,6 @@ Computes the next representable value after a given number towards a specified d
func nextafter(x: Num, y: Num -> Num)
```
**Parameters:**
- `x`: The starting number.
- `y`: The direction towards which to find the next representable value.
@ -1075,8 +935,6 @@ 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:**
@ -1084,8 +942,6 @@ Converts a text representation of a number into a floating-point number.
func parse(text: Text -> Num?)
```
**Parameters:**
- `text`: The text containing the number.
**Returns:**
@ -1103,8 +959,6 @@ as a number.
---
### `rint`
**Description:**
Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
**Signature:**
@ -1112,8 +966,6 @@ Rounds a number to the nearest integer, with ties rounded to the nearest even in
func rint(x: Num -> Num)
```
**Parameters:**
- `x`: The number to be rounded.
**Returns:**
@ -1130,8 +982,6 @@ The nearest integer value of `x`.
---
### `round`
**Description:**
Rounds a number to the nearest whole number integer.
**Signature:**
@ -1139,8 +989,6 @@ Rounds a number to the nearest whole number integer.
func round(x: Num -> Num)
```
**Parameters:**
- `x`: The number to be rounded.
**Returns:**
@ -1157,8 +1005,6 @@ The nearest integer value of `x`.
---
### `scientific`
**Description:**
Formats a number in scientific notation with a specified precision.
**Signature:**
@ -1166,8 +1012,6 @@ Formats a number in scientific notation with a specified precision.
func scientific(n: Num, precision: Int = 0 -> Text)
```
**Parameters:**
- `n`: The number to be formatted.
- `precision`: The number of decimal places. Default is `0`.
@ -1183,8 +1027,6 @@ A text representation of the number in scientific notation with the specified pr
---
### `significand`
**Description:**
Extracts the significand (or mantissa) of a number.
**Signature:**
@ -1192,8 +1034,6 @@ Extracts the significand (or mantissa) of a number.
func significand(x: Num -> Num)
```
**Parameters:**
- `x`: The number from which to extract the significand.
**Returns:**
@ -1208,8 +1048,6 @@ The significand of `x`.
---
### `sin`
**Description:**
Computes the sine of a number (angle in radians).
**Signature:**
@ -1217,8 +1055,6 @@ Computes the sine of a number (angle in radians).
func sin(x: Num -> Num)
```
**Parameters:**
- `x`: The angle in radians.
**Returns:**
@ -1233,8 +1069,6 @@ The sine of `x`.
---
### `sinh`
**Description:**
Computes the hyperbolic sine of a number.
**Signature:**
@ -1242,8 +1076,6 @@ Computes the hyperbolic sine of a number.
func sinh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the hyperbolic sine is to be calculated.
**Returns:**
@ -1258,8 +1090,6 @@ The hyperbolic sine of `x`.
---
### `sqrt`
**Description:**
Computes the square root of a number.
**Signature:**
@ -1267,8 +1097,6 @@ Computes the square root of a number.
func sqrt(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the square root is to be calculated.
**Returns:**
@ -1283,8 +1111,6 @@ The square root of `x`.
---
### `tan`
**Description:**
Computes the tangent of a number (angle in radians).
**Signature:**
@ -1292,8 +1118,6 @@ Computes the tangent of a number (angle in radians).
func tan(x: Num -> Num)
```
**Parameters:**
- `x`: The angle in radians.
**Returns:**
@ -1308,8 +1132,6 @@ The tangent of `x`.
---
### `tanh`
**Description:**
Computes the hyperbolic tangent of a number.
**Signature:**
@ -1317,8 +1139,6 @@ Computes the hyperbolic tangent of a number.
func tanh(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the hyperbolic tangent is to be calculated.
**Returns:**
@ -1333,8 +1153,6 @@ The hyperbolic tangent of `x`.
---
### `tgamma`
**Description:**
Computes the gamma function of a number.
**Signature:**
@ -1342,8 +1160,6 @@ Computes the gamma function of a number.
func tgamma(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the gamma function is to be calculated.
**Returns:**
@ -1358,8 +1174,6 @@ The gamma function of `x`.
---
### `trunc`
**Description:**
Truncates a number to the nearest integer towards zero.
**Signature:**
@ -1367,8 +1181,6 @@ Truncates a number to the nearest integer towards zero.
func trunc(x: Num -> Num)
```
**Parameters:**
- `x`: The number to be truncated.
**Returns:**
@ -1385,8 +1197,6 @@ The integer part of `x` towards zero.
---
### `y0`
**Description:**
Computes the Bessel function of the second kind of order 0.
**Signature:**
@ -1394,8 +1204,6 @@ Computes the Bessel function of the second kind of order 0.
func y0(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the Bessel function is to be calculated.
**Returns:**
@ -1410,8 +1218,6 @@ The Bessel function of the second kind of order 0 of `x`.
---
### `y1`
**Description:**
Computes the Bessel function of the second kind of order 1.
**Signature:**
@ -1419,8 +1225,6 @@ Computes the Bessel function of the second kind of order 1.
func y1(x: Num -> Num)
```
**Parameters:**
- `x`: The number for which the Bessel function is to be calculated.
**Returns:**

104
docs/paths.md
View File

@ -65,8 +65,6 @@ intended. Paths can be created from text with slashes using
- [`func write_unique_bytes(path: Path, bytes: [Byte] -> Path)`](#write_unique_bytes)
### `append`
**Description:**
Appends the given text to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
@ -75,8 +73,6 @@ it doesn't already exist. Failure to write will result in a runtime error.
func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
```
**Parameters:**
- `path`: The path of the file to append to.
- `text`: The text to append to the file.
- `permissions` (optional): The permissions to set on the file if it is being created (default is `0o644`).
@ -92,8 +88,6 @@ Nothing.
---
### `append_bytes`
**Description:**
Appends the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
@ -102,8 +96,6 @@ it doesn't already exist. Failure to write will result in a runtime error.
func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
```
**Parameters:**
- `path`: The path of the file to append to.
- `bytes`: The bytes to append to the file.
- `permissions` (optional): The permissions to set on the file if it is being created (default is `0o644`).
@ -119,8 +111,6 @@ Nothing.
---
### `base_name`
**Description:**
Returns the base name of the file or directory at the specified path.
**Signature:**
@ -128,8 +118,6 @@ Returns the base name of the file or directory at the specified path.
func base_name(path: Path -> Text)
```
**Parameters:**
- `path`: The path of the file or directory.
**Returns:**
@ -144,8 +132,6 @@ The base name of the file or directory.
---
### `by_line`
**Description:**
Returns an iterator that can be used to iterate over a file one line at a time,
or returns a null value if the file could not be opened.
@ -154,8 +140,6 @@ or returns a null value if the file could not be opened.
func by_line(path: Path -> func(->Text?)?)
```
**Parameters:**
- `path`: The path of the file.
**Returns:**
@ -179,8 +163,6 @@ for line in (/dev/stdin):by_line()!:
---
### `children`
**Description:**
Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files.
**Signature:**
@ -188,8 +170,6 @@ Returns a list of children (files and directories) within the directory at the s
func children(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
- `path`: The path of the directory.
- `include_hidden` (optional): Whether to include hidden files, which start with a `.` (default is `no`).
@ -205,8 +185,6 @@ A list of paths for the children.
---
### `create_directory`
**Description:**
Creates a new directory at the specified path with the given permissions. If
any of the parent directories do not exist, they will be created as needed.
@ -215,8 +193,6 @@ any of the parent directories do not exist, they will be created as needed.
func create_directory(path: Path, permissions=0o755[32] -> Void)
```
**Parameters:**
- `path`: The path of the directory to create.
- `permissions` (optional): The permissions to set on the new directory (default is `0o644`).
@ -231,8 +207,6 @@ Nothing.
---
### `exists`
**Description:**
Checks if a file or directory exists at the specified path.
**Signature:**
@ -240,8 +214,6 @@ Checks if a file or directory exists at the specified path.
func exists(path: Path -> Bool)
```
**Parameters:**
- `path`: The path to check.
**Returns:**
@ -256,8 +228,6 @@ func exists(path: Path -> Bool)
---
### `extension`
**Description:**
Returns the file extension of the file at the specified path. Optionally returns the full extension.
**Signature:**
@ -265,8 +235,6 @@ Returns the file extension of the file at the specified path. Optionally returns
func extension(path: Path, full=yes -> Text)
```
**Parameters:**
- `path`: The path of the file.
- `full` (optional): Whether to return everything after the first `.` in the
base name, or only the last part of the extension (default is `yes`).
@ -290,8 +258,6 @@ no file extension.
---
### `files`
**Description:**
Returns a list of files within the directory at the specified path. Optionally includes hidden files.
**Signature:**
@ -299,8 +265,6 @@ Returns a list of files within the directory at the specified path. Optionally i
func files(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
- `path`: The path of the directory.
- `include_hidden` (optional): Whether to include hidden files (default is `no`).
@ -316,8 +280,6 @@ A list of file paths.
---
### `glob`
**Description:**
Perform a globbing operation and return an array of matching paths. Some glob
specific details:
@ -332,8 +294,6 @@ specific details:
func glob(path: Path -> [Path])
```
**Parameters:**
- `path`: The path of the directory which may contain special globbing characters
like `*`, `?`, or `{...}`
@ -363,8 +323,6 @@ A list of file paths that match the glob.
---
### `is_directory`
**Description:**
Checks if the path represents a directory. Optionally follows symbolic links.
**Signature:**
@ -372,8 +330,6 @@ Checks if the path represents a directory. Optionally follows symbolic links.
func is_directory(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
- `path`: The path to check.
- `follow_symlinks` (optional): Whether to follow symbolic links (default is `yes`).
@ -392,8 +348,6 @@ func is_directory(path: Path, follow_symlinks=yes -> Bool)
---
### `is_file`
**Description:**
Checks if the path represents a file. Optionally follows symbolic links.
**Signature:**
@ -401,8 +355,6 @@ Checks if the path represents a file. Optionally follows symbolic links.
func is_file(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
- `path`: The path to check.
- `follow_symlinks` (optional): Whether to follow symbolic links (default is `yes`).
@ -421,8 +373,6 @@ func is_file(path: Path, follow_symlinks=yes -> Bool)
---
### `is_socket`
**Description:**
Checks if the path represents a socket. Optionally follows symbolic links.
**Signature:**
@ -430,8 +380,6 @@ Checks if the path represents a socket. Optionally follows symbolic links.
func is_socket(path: Path, follow_symlinks=yes -> Bool)
```
**Parameters:**
- `path`: The path to check.
- `follow_symlinks` (optional): Whether to follow symbolic links (default is `yes`).
@ -447,8 +395,6 @@ func is_socket(path: Path, follow_symlinks=yes -> Bool)
---
### `is_symlink`
**Description:**
Checks if the path represents a symbolic link.
**Signature:**
@ -456,8 +402,6 @@ Checks if the path represents a symbolic link.
func is_symlink(path: Path -> Bool)
```
**Parameters:**
- `path`: The path to check.
**Returns:**
@ -472,8 +416,6 @@ func is_symlink(path: Path -> Bool)
---
### `parent`
**Description:**
Returns the parent directory of the file or directory at the specified path.
**Signature:**
@ -481,8 +423,6 @@ Returns the parent directory of the file or directory at the specified path.
func parent(path: Path -> Path)
```
**Parameters:**
- `path`: The path of the file or directory.
**Returns:**
@ -497,8 +437,6 @@ The path of the parent directory.
---
### `read`
**Description:**
Reads the contents of the file at the specified path or a null value if the
file could not be read.
@ -507,8 +445,6 @@ file could not be read.
func read(path: Path -> Text?)
```
**Parameters:**
- `path`: The path of the file to read.
**Returns:**
@ -527,8 +463,6 @@ raised.
---
### `read_bytes`
**Description:**
Reads the contents of the file at the specified path or a null value if the
file could not be read.
@ -537,8 +471,6 @@ file could not be read.
func read_bytes(path: Path -> [Byte]?)
```
**Parameters:**
- `path`: The path of the file to read.
**Returns:**
@ -557,8 +489,6 @@ returned.
---
### `relative`
**Description:**
Returns the path relative to a given base path. By default, the base path is the current directory.
**Signature:**
@ -566,8 +496,6 @@ Returns the path relative to a given base path. By default, the base path is the
func relative(path: Path, relative_to=(./) -> Path)
```
**Parameters:**
- `path`: The path to convert.
- `relative_to` (optional): The base path for the relative path (default is `./`).
@ -583,8 +511,6 @@ The relative path.
---
### `remove`
**Description:**
Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
**Signature:**
@ -592,8 +518,6 @@ Removes the file or directory at the specified path. A runtime error is raised i
func remove(path: Path, ignore_missing=no -> Void)
```
**Parameters:**
- `path`: The path to remove.
- `ignore_missing` (optional): Whether to ignore errors if the file or directory does not exist (default is `no`).
@ -608,8 +532,6 @@ Nothing.
---
### `resolved`
**Description:**
Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
**Signature:**
@ -617,8 +539,6 @@ Resolves the absolute path of the given path relative to a base path. By default
func resolved(path: Path, relative_to=(./) -> Path)
```
**Parameters:**
- `path`: The path to resolve.
- `relative_to` (optional): The base path for resolution (default is `./`).
@ -637,8 +557,6 @@ The resolved absolute path.
---
### `subdirectories`
**Description:**
Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
**Signature:**
@ -646,8 +564,6 @@ Returns a list of subdirectories within the directory at the specified path. Opt
func subdirectories(path: Path, include_hidden=no -> [Path])
```
**Parameters:**
- `path`: The path of the directory.
- `include_hidden` (optional): Whether to include hidden subdirectories (default is `no`).
@ -666,8 +582,6 @@ A list of subdirectory paths.
---
### `unique_directory`
**Description:**
Generates a unique directory path based on the given path. Useful for creating temporary directories.
**Signature:**
@ -675,8 +589,6 @@ Generates a unique directory path based on the given path. Useful for creating t
func unique_directory(path: Path -> Path)
```
**Parameters:**
- `path`: The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`.
**Returns:**
@ -695,8 +607,6 @@ created:remove()
---
### `write`
**Description:**
Writes the given text to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
@ -706,8 +616,6 @@ writing cannot be successfully completed, a runtime error is raised.
func write(path: Path, text: Text, permissions=0o644[32] -> Void)
```
**Parameters:**
- `path`: The path of the file to write to.
- `text`: The text to write to the file.
- `permissions` (optional): The permissions to set on the file if it is created (default is `0o644`).
@ -723,8 +631,6 @@ Nothing.
---
### `write_bytes`
**Description:**
Writes the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
@ -734,8 +640,6 @@ writing cannot be successfully completed, a runtime error is raised.
func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
```
**Parameters:**
- `path`: The path of the file to write to.
- `bytes`: An array of bytes to write to the file.
- `permissions` (optional): The permissions to set on the file if it is created (default is `0o644`).
@ -751,8 +655,6 @@ Nothing.
---
### `write_unique`
**Description:**
Writes the given text to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
@ -762,8 +664,6 @@ files.
func write_unique(path: Path, text: Text -> Path)
```
**Parameters:**
- `path`: The base path for generating the unique file. This path must include
the string `XXXXXX` in the file base name.
- `text`: The text to write to the file.
@ -783,8 +683,6 @@ created:remove()
---
### `write_unique_bytes`
**Description:**
Writes the given bytes to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
@ -794,8 +692,6 @@ files.
func write_unique_bytes(path: Path, bytes: [Byte] -> Path)
```
**Parameters:**
- `path`: The base path for generating the unique file. This path must include
the string `XXXXXX` in the file base name.
- `bytes`: The bytes to write to the file.

32
docs/rng.md
View File

@ -29,8 +29,6 @@ This documentation provides details on RNG functions available in the API.
- [`func set_seed(rng: RNG, seed: [Byte])`](#set_seed)
### `bool`
**Description:**
Generate a random boolean value with a given probability.
**Signature:**
@ -38,8 +36,6 @@ Generate a random boolean value with a given probability.
func bool(rng: RNG, p: Num = 0.5 -> Bool)
```
**Parameters:**
- `rng`: The random number generator to use.
- `p`: The probability of returning a `yes` value. Values less than zero and
`NaN` values are treated as equal to zero and values larger than zero are
@ -59,8 +55,6 @@ func bool(rng: RNG, p: Num = 0.5 -> Bool)
---
### `byte`
**Description:**
Generate a random byte with uniform probability.
**Signature:**
@ -68,8 +62,6 @@ Generate a random byte with uniform probability.
func byte(rng: RNG -> Byte)
```
**Parameters:**
- `rng`: The random number generator to use.
**Returns:**
@ -84,8 +76,6 @@ A random byte (0-255).
---
### `bytes`
**Description:**
Generate an array of uniformly random bytes with the given length.
**Signature:**
@ -93,8 +83,6 @@ Generate an array of uniformly random bytes with the given length.
func bytes(rng: RNG, count: Int -> [Byte])
```
**Parameters:**
- `rng`: The random number generator to use.
- `count`: The number of random bytes to return.
@ -110,8 +98,6 @@ An array of length `count` random bytes with uniform random distribution (0-255)
---
### `copy`
**Description:**
Return a copy of a random number generator. This copy will be a parallel version of
the given RNG with its own internal state.
@ -120,8 +106,6 @@ the given RNG with its own internal state.
func copy(rng: RNG -> RNG)
```
**Parameters:**
- `rng`: The random number generator to copy.
**Returns:**
@ -143,8 +127,6 @@ A copy of the given RNG.
---
### `int`, `int64`, `int32`, `int16`, `int8`
**Description:**
Generate a random integer value with the given range.
**Signature:**
@ -156,8 +138,6 @@ func int16(rng: RNG, min: Int16 = Int16.min, max: Int16 = Int16.max -> Int)
func int8(rng: RNG, min: Int8 = Int8.min, max: Int8 = Int8.max -> Int)
```
**Parameters:**
- `rng`: The random number generator to use.
- `min`: The minimum value to be returned.
- `max`: The maximum value to be returned.
@ -175,8 +155,6 @@ is greater than `max`, an error will be raised.
---
### `new`
**Description:**
Return a new random number generator.
**Signature:**
@ -184,8 +162,6 @@ Return a new random number generator.
func new(seed: [Byte] = (/dev/urandom):read_bytes(40)! -> RNG)
```
**Parameters:**
- `seed`: The seed use for the random number generator. A seed length of 40
bytes is recommended. Seed lengths of less than 40 bytes are padded with
zeroes.
@ -203,8 +179,6 @@ A new random number generator.
---
### `num`, `num32`
**Description:**
Generate a random floating point value with the given range.
**Signature:**
@ -213,8 +187,6 @@ func num(rng: RNG, min: Num = 0.0, max: Num = 1.0 -> Int)
func num32(rng: RNG, min: Num = 0.0_f32, max: Num = 1.0_f32 -> Int)
```
**Parameters:**
- `rng`: The random number generator to use.
- `min`: The minimum value to be returned.
- `max`: The maximum value to be returned.
@ -232,8 +204,6 @@ A floating point number uniformly chosen from the range `[min, max]`
---
### `set_seed`
**Description:**
Set the seed for an RNG.
**Signature:**
@ -241,8 +211,6 @@ Set the seed for an RNG.
func set_seed(rng: RNG, seed: [Byte])
```
**Parameters:**
- `rng`: The random number generator to modify.
- `seed`: A new seed to re-seed the random number generator with. A seed length
of 40 bytes is recommended. Seed lengths of less than 40 bytes are padded

44
docs/sets.md
View File

@ -88,8 +88,6 @@ iterating over any of the new values.
- [`func without(set:{T}, other: {T} -> {T})`](#without)
### `add`
**Description:**
Adds an item to the set.
**Signature:**
@ -97,8 +95,6 @@ Adds an item to the set.
func add(set:{T}, item: T -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `item`: The item to add to the set.
@ -113,8 +109,6 @@ Nothing.
---
### `add_all`
**Description:**
Adds multiple items to the set.
**Signature:**
@ -122,8 +116,6 @@ Adds multiple items to the set.
func 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.
@ -138,8 +130,6 @@ Nothing.
---
### `clear`
**Description:**
Removes all items from the set.
**Signature:**
@ -147,8 +137,6 @@ Removes all items from the set.
func clear(set:@{T} -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
**Returns:**
@ -162,8 +150,6 @@ Nothing.
---
### `has`
**Description:**
Checks if the set contains a specified item.
**Signature:**
@ -171,8 +157,6 @@ Checks if the set contains a specified item.
func has(set:{T}, item:T -> Bool)
```
**Parameters:**
- `set`: The set to check.
- `item`: The item to check for presence.
@ -188,8 +172,6 @@ func has(set:{T}, item:T -> Bool)
---
### `is_subset_of`
**Description:**
Checks if the set is a subset of another set.
**Signature:**
@ -197,8 +179,6 @@ Checks if the set is a subset of another set.
func (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 subset (does not equal the other set).
@ -215,8 +195,6 @@ func (set: {T}, other: {T}, strict: Bool = no -> Bool)
---
### `is_superset_of`
**Description:**
Checks if the set is a superset of another set.
**Signature:**
@ -224,8 +202,6 @@ Checks if the set is a superset of another set.
func 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).
@ -239,8 +215,6 @@ func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool)
= yes
```
### `overlap`
**Description:**
Creates a new set with items that are in both the original set and another set.
**Signature:**
@ -248,8 +222,6 @@ Creates a new set with items that are in both the original set and another set.
func overlap(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set to intersect with.
@ -265,8 +237,6 @@ A new set containing only items present in both sets.
---
### `remove`
**Description:**
Removes an item from the set.
**Signature:**
@ -274,8 +244,6 @@ Removes an item from the set.
func remove(set:@{T}, item: T -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `item`: The item to remove from the set.
@ -290,8 +258,6 @@ Nothing.
---
### `remove_all`
**Description:**
Removes multiple items from the set.
**Signature:**
@ -299,8 +265,6 @@ Removes multiple items from the set.
func remove_all(set:@{T}, items: [T] -> Void)
```
**Parameters:**
- `set`: The mutable reference to the set.
- `items`: The array of items to remove from the set.
@ -315,8 +279,6 @@ Nothing.
---
### `with`
**Description:**
Creates a new set that is the union of the original set and another set.
**Signature:**
@ -324,8 +286,6 @@ Creates a new set that is the union of the original set and another set.
func with(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set to union with.
@ -341,8 +301,6 @@ A new set containing all items from both sets.
---
### `without`
**Description:**
Creates a new set with items from the original set but without items from another set.
**Signature:**
@ -350,8 +308,6 @@ Creates a new set with items from the original set but without items from anothe
func without(set:{T}, other: {T} -> {T})
```
**Parameters:**
- `set`: The original set.
- `other`: The set of items to remove from the original set.

16
docs/shell.md
View File

@ -19,8 +19,6 @@ user-controlled string is automatically escaped when performing interpolation.
- [`func run(command: Shell -> [Byte]?)`](#run_bytes)
### `by_line`
**Description:**
Run a shell command and return an iterator over its output, line-by-line.
**Signature:**
@ -28,8 +26,6 @@ Run a shell command and return an iterator over its output, line-by-line.
func by_line(command: Shell -> Void)
```
**Parameters:**
- `command`: The command to run.
**Returns:**
@ -45,8 +41,6 @@ for line in $Shell"ping www.example.com":by_line()!:
```
### `execute`
**Description:**
Execute a shell command without capturing its output and return its exit status.
**Signature:**
@ -54,8 +48,6 @@ Execute a shell command without capturing its output and return its exit status.
func execute(command: Shell -> Int32?)
```
**Parameters:**
- `command`: The command to execute.
**Returns:**
@ -70,8 +62,6 @@ If the command exits normally, return its exit status. Otherwise return `none`.
---
### `run`
**Description:**
Run a shell command and return the output text from `stdout`.
**Signature:**
@ -79,8 +69,6 @@ Run a shell command and return the output text from `stdout`.
func run(command: Shell -> Text?)
```
**Parameters:**
- `command`: The command to run.
**Returns:**
@ -97,8 +85,6 @@ if there is a trailing newline, it will be stripped.
---
### `run_bytes`
**Description:**
Run a shell command and return the output in raw bytes from `stdout`.
**Signature:**
@ -106,8 +92,6 @@ Run a shell command and return the output in raw bytes from `stdout`.
func run(command: Shell -> [Byte]?)
```
**Parameters:**
- `command`: The command to run.
**Returns:**

24
docs/tables.md
View File

@ -141,8 +141,6 @@ iterating over any of the new values.
- [`func set(t:{K,V}, key: K, value: V -> Void)`](#set)
### `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.
@ -151,8 +149,6 @@ not already in the table, its value will be assumed to be zero.
func bump(t:@{K,V}, key: K, amount: Int = 1 -> Void)
```
**Parameters:**
- `t`: The reference to the table.
- `key`: The key whose value is to be incremented.
- `amount`: The amount to increment the value by (default: 1).
@ -172,8 +168,6 @@ t:bump("B", 10)
---
### `clear`
**Description:**
Removes all key-value pairs from the table.
**Signature:**
@ -181,8 +175,6 @@ Removes all key-value pairs from the table.
func clear(t:@{K,V})
```
**Parameters:**
- `t`: The reference to the table.
**Returns:**
@ -196,8 +188,6 @@ Nothing.
---
### `get`
**Description:**
Retrieves the value associated with a key, or returns null if the key is not present.
**Signature:**
@ -205,8 +195,6 @@ Retrieves the value associated with a key, or returns null if the key is not pre
func get(t:{K,V}, key: K -> V?)
```
**Parameters:**
- `t`: The table.
- `key`: The key whose associated value is to be retrieved.
@ -232,8 +220,6 @@ The value associated with the key or null if the key is not found.
---
### `has`
**Description:**
Checks if the table contains a specified key.
**Signature:**
@ -241,8 +227,6 @@ Checks if the table contains a specified key.
func has(t:{K,V}, key: K -> Bool)
```
**Parameters:**
- `t`: The table.
- `key`: The key to check for presence.
@ -260,8 +244,6 @@ func has(t:{K,V}, key: K -> Bool)
---
### `remove`
**Description:**
Removes the key-value pair associated with a specified key.
**Signature:**
@ -269,8 +251,6 @@ Removes the key-value pair associated with a specified key.
func remove(t:{K,V}, key: K -> Void)
```
**Parameters:**
- `t`: The reference to the table.
- `key`: The key of the key-value pair to remove.
@ -288,8 +268,6 @@ t:remove("A")
---
### `set`
**Description:**
Sets or updates the value associated with a specified key.
**Signature:**
@ -297,8 +275,6 @@ Sets or updates the value associated with a specified key.
func set(t:{K,V}, key: K, value: V -> Void)
```
**Parameters:**
- `t`: The reference to the table.
- `key`: The key to set or update.
- `value`: The value to associate with the key.

140
docs/text.md
View File

@ -307,8 +307,6 @@ pattern documentation](patterns.md) for more details.
- [`func utf32_codepoints(text: Text -> [Int32])`](#utf32_codepoints)
### `as_c_string`
**Description:**
Converts a `Text` value to a C-style string.
**Signature:**
@ -316,8 +314,6 @@ Converts a `Text` value to a C-style string.
func as_c_string(text: Text -> CString)
```
**Parameters:**
- `text`: The text to be converted to a C-style string.
**Returns:**
@ -332,8 +328,6 @@ A C-style string (`CString`) representing the text.
---
### `at`
**Description:**
Get the graphical cluster at a given index. This is similar to `str[i]` with
ASCII text, but has more correct behavior for unicode text.
@ -342,8 +336,6 @@ ASCII text, but has more correct behavior for unicode text.
func at(text: Text, index: Int -> Text)
```
**Parameters:**
- `text`: The text from which to get a cluster.
- `index`: The index of the graphical cluster (1-indexed).
@ -361,8 +353,6 @@ indices are counted from the back of the text, so `-1` means the last cluster,
---
### `by_line`
**Description:**
Returns an iterator function that can be used to iterate over the lines in a
text.
@ -371,8 +361,6 @@ text.
func by_line(text: Text -> func(->Text?))
```
**Parameters:**
- `text`: The text to be iterated over, line by line.
**Returns:**
@ -394,8 +382,6 @@ for line in text:by_line():
---
### `by_match`
**Description:**
Returns an iterator function that can be used to iterate over the occurrences
of a pattern in a text.
@ -404,8 +390,6 @@ of a pattern in a text.
func by_match(text: Text, pattern: Pattern -> func(->Match?))
```
**Parameters:**
- `text`: The text to be iterated over looking for matches.
- `pattern`: The [pattern](patterns.md) to look for.
@ -425,8 +409,6 @@ for match in text:by_match($/{alpha}/):
---
### `by_split`
**Description:**
Returns an iterator function that can be used to iterate over text separated by
a pattern.
@ -435,8 +417,6 @@ a pattern.
func by_split(text: Text, pattern: Pattern = $// -> func(->Text?))
```
**Parameters:**
- `text`: The text to be iterated over in pattern-delimited chunks.
- `pattern`: The [pattern](patterns.md) to split the text on.
@ -456,8 +436,6 @@ for chunk in text:by_split($/,/):
---
### `bytes`
**Description:**
Converts a `Text` value to an array of bytes representing a UTF8 encoding of
the text.
@ -466,8 +444,6 @@ the text.
func bytes(text: Text -> [Byte])
```
**Parameters:**
- `text`: The text to be converted to UTF8 bytes.
**Returns:**
@ -482,8 +458,6 @@ An array of bytes (`[Byte]`) representing the text in UTF8 encoding.
---
### `codepoint_names`
**Description:**
Returns an array of the names of each codepoint in the text.
**Signature:**
@ -491,8 +465,6 @@ Returns an array of the names of each codepoint in the text.
func codepoint_names(text: Text -> [Text])
```
**Parameters:**
- `text`: The text from which to extract codepoint names.
**Returns:**
@ -507,8 +479,6 @@ An array of codepoint names (`[Text]`).
---
### `each`
**Description:**
Iterates over each match of a [pattern](patterns.md) and passes the match to
the given function.
@ -517,8 +487,6 @@ the given function.
func each(text: Text, pattern: Pattern, fn: func(m: Match), recursive: Bool = yes -> Int?)
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
- `fn`: A function to be called on each match that was found.
@ -538,8 +506,6 @@ None.
---
### `ends_with`
**Description:**
Checks if the `Text` ends with a literal suffix text.
**Signature:**
@ -547,8 +513,6 @@ Checks if the `Text` ends with a literal suffix text.
func ends_with(text: Text, suffix: Text -> Bool)
```
**Parameters:**
- `text`: The text to be searched.
- `suffix`: The literal suffix text to check for.
@ -564,8 +528,6 @@ func ends_with(text: Text, suffix: Text -> Bool)
---
### `find`
**Description:**
Finds the first occurrence of a [pattern](patterns.md) in the given text (if
any).
@ -574,8 +536,6 @@ any).
func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
- `start`: The index to start the search.
@ -599,8 +559,6 @@ struct containing information about the match.
---
### `find_all`
**Description:**
Finds all occurrences of a [pattern](patterns.md) in the given text.
**Signature:**
@ -608,8 +566,6 @@ Finds all occurrences of a [pattern](patterns.md) in the given text.
func find_all(text: Text, pattern: Pattern -> [Match])
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
@ -638,8 +594,6 @@ Note: if `text` or `pattern` is empty, an empty array will be returned.
---
### `from`
**Description:**
Get a slice of the text, starting at the given position.
**Signature:**
@ -647,8 +601,6 @@ Get a slice of the text, starting at the given position.
func from(text: Text, first: Int -> Text)
```
**Parameters:**
- `text`: The text to be sliced.
- `frist`: The index of the first grapheme cluster to include (1-indexed).
@ -670,8 +622,6 @@ the length of the string.
---
### `from_bytes`
**Description:**
Returns text that has been constructed from the given UTF8 bytes. Note: the
text will be normalized, so the resulting text's UTF8 bytes may not exactly
match the input.
@ -681,8 +631,6 @@ match the input.
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
@ -697,8 +645,6 @@ A new text based on the input UTF8 bytes after normalization has been applied.
---
### `from_c_string`
**Description:**
Converts a C-style string to a `Text` value.
**Signature:**
@ -706,8 +652,6 @@ Converts a C-style string to a `Text` value.
func from_c_string(str: CString -> Text)
```
**Parameters:**
- `str`: The C-style string to be converted.
**Returns:**
@ -722,8 +666,6 @@ A `Text` value representing the C-style string.
---
### `from_codepoint_names`
**Description:**
Returns text that has the given codepoint names (according to the Unicode
specification) as its codepoints. Note: the text will be normalized, so the
resulting text's codepoints may not exactly match the input codepoints.
@ -733,8 +675,6 @@ resulting text's codepoints may not exactly match the input codepoints.
func from_codepoint_names(codepoint_names: [Text] -> [Text])
```
**Parameters:**
- `codepoint_names`: The names of each codepoint in the desired text. Names
are case-insentive.
@ -755,8 +695,6 @@ Any invalid names are ignored.
---
### `from_codepoints`
**Description:**
Returns text that has been constructed from the given UTF32 codepoints. Note:
the text will be normalized, so the resulting text's codepoints may not exactly
match the input codepoints.
@ -766,8 +704,6 @@ match the input codepoints.
func from_codepoint_names(codepoints: [Int32] -> [Text])
```
**Parameters:**
- `codepoints`: The UTF32 codepoints in the desired text.
**Returns:**
@ -782,8 +718,6 @@ A new text with the specified codepoints after normalization has been applied.
---
### `has`
**Description:**
Checks if the `Text` contains a target [pattern](patterns.md).
**Signature:**
@ -791,8 +725,6 @@ Checks if the `Text` contains a target [pattern](patterns.md).
func has(text: Text, pattern: Pattern -> Bool)
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
@ -814,8 +746,6 @@ func has(text: Text, pattern: Pattern -> Bool)
---
### `join`
**Description:**
Joins an array of text pieces with a specified glue.
**Signature:**
@ -823,8 +753,6 @@ Joins an array of text pieces with a specified glue.
func join(glue: Text, pieces: [Text] -> Text)
```
**Parameters:**
- `glue`: The text used to join the pieces.
- `pieces`: The array of text pieces to be joined.
@ -840,8 +768,6 @@ A single `Text` value with the pieces joined by the glue.
---
### `lines`
**Description:**
Splits the text into an array of lines of text, preserving blank lines,
ignoring trailing newlines, and handling `\r\n` the same as `\n`.
@ -850,8 +776,6 @@ ignoring trailing newlines, and handling `\r\n` the same as `\n`.
func split(text: Text -> [Text])
```
**Parameters:**
- `text`: The text to be split into lines.
**Returns:**
@ -874,8 +798,6 @@ An array of substrings resulting from the split.
---
### `lower`
**Description:**
Converts all characters in the text to lowercase.
**Signature:**
@ -883,8 +805,6 @@ Converts all characters in the text to lowercase.
func lower(text: Text -> Text)
```
**Parameters:**
- `text`: The text to be converted to lowercase.
**Returns:**
@ -899,8 +819,6 @@ The lowercase version of the text.
---
### `map`
**Description:**
For each occurrence of the given [pattern](patterns.md), replace the text with
the result of calling the given function on that match.
@ -909,8 +827,6 @@ the result of calling the given function on that match.
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.
@ -932,8 +848,6 @@ function to each.
---
### `matches`
**Description:**
Checks if the `Text` matches target [pattern](patterns.md) and returns an array
of the matching text captures or a null value if the entire text doesn't match
the pattern.
@ -943,8 +857,6 @@ the pattern.
func matches(text: Text, pattern: Pattern -> [Text])
```
**Parameters:**
- `text`: The text to be searched.
- `pattern`: The [pattern](patterns.md) to search for.
@ -964,8 +876,6 @@ or a null value otherwise.
---
### `quoted`
**Description:**
Formats the text as a quoted string.
**Signature:**
@ -973,8 +883,6 @@ Formats the text as a quoted string.
func quoted(text: Text, color: Bool = no -> Text)
```
**Parameters:**
- `text`: The text to be quoted.
- `color`: Whether to add color formatting (default is `no`).
@ -990,8 +898,6 @@ The text formatted as a quoted string.
---
### `repeat`
**Description:**
Repeat some text multiple times.
**Signature:**
@ -999,8 +905,6 @@ Repeat some text multiple times.
func repeat(text: Text, count:Int -> Text)
```
**Parameters:**
- `text`: The text to repeat.
- `count`: The number of times to repeat it. (Negative numbers are equivalent to zero).
@ -1016,8 +920,6 @@ The text repeated the given number of times.
---
### `replace`
**Description:**
Replaces occurrences of a [pattern](patterns.md) in the text with a replacement
string.
@ -1026,8 +928,6 @@ string.
func replace(text: Text, pattern: Pattern, replacement: Text, backref: Pattern = $/\/, recursive: Bool = yes -> Text)
```
**Parameters:**
- `text`: The text in which to perform replacements.
- `pattern`: The [pattern](patterns.md) to be replaced.
- `replacement`: The text to replace the pattern with.
@ -1082,8 +982,6 @@ The text with occurrences of the pattern replaced.
---
### `replace_all`
**Description:**
Takes a table mapping [patterns](patterns.md) to replacement texts and performs
all the replacements in the table on the whole text. At each position, the
first matching pattern's replacement is applied and the pattern matching moves
@ -1096,8 +994,6 @@ behavior.
func replace_all(replacements:{Pattern,Text}, backref: Pattern = $/\/, recursive: Bool = yes -> Text)
```
**Parameters:**
- `text`: The text in which to perform replacements.
- `replacements`: A table mapping from [pattern](patterns.md) to the
replacement text associated with that pattern.
@ -1131,8 +1027,6 @@ replacement text.
---
### `reversed`
**Description:**
Return a text that has the grapheme clusters in reverse order.
**Signature:**
@ -1140,8 +1034,6 @@ Return a text that has the grapheme clusters in reverse order.
func reversed(text: Text -> Text)
```
**Parameters:**
- `text`: The text to reverse.
**Returns:**
@ -1156,8 +1048,6 @@ A reversed version of the text.
---
### `slice`
**Description:**
Get a slice of the text.
**Signature:**
@ -1165,8 +1055,6 @@ Get a slice of the text.
func slice(text: Text, from: Int = 1, to: Int = -1 -> Text)
```
**Parameters:**
- `text`: The text to be sliced.
- `from`: The index of the first grapheme cluster to include (1-indexed).
- `to`: The index of the last grapheme cluster to include (1-indexed).
@ -1192,8 +1080,6 @@ the string.
---
### `split`
**Description:**
Splits the text into an array of substrings based on a [pattern](patterns.md).
**Signature:**
@ -1201,8 +1087,6 @@ Splits the text into an array of substrings based on a [pattern](patterns.md).
func split(text: Text, pattern: Pattern = "" -> [Text])
```
**Parameters:**
- `text`: The text to be split.
- `pattern`: The [pattern](patterns.md) used to split the text. If the pattern
is the empty string, the text will be split into individual grapheme clusters.
@ -1228,8 +1112,6 @@ An array of substrings resulting from the split.
---
### `starts_with`
**Description:**
Checks if the `Text` starts with a literal prefix text.
**Signature:**
@ -1237,8 +1119,6 @@ Checks if the `Text` starts with a literal prefix text.
func starts_with(text: Text, prefix: Text -> Bool)
```
**Parameters:**
- `text`: The text to be searched.
- `prefix`: The literal prefix text to check for.
@ -1254,8 +1134,6 @@ func starts_with(text: Text, prefix: Text -> Bool)
---
### `title`
**Description:**
Converts the text to title case (capitalizing the first letter of each word).
**Signature:**
@ -1263,8 +1141,6 @@ Converts the text to title case (capitalizing the first letter of each word).
func title(text: Text -> Text)
```
**Parameters:**
- `text`: The text to be converted to title case.
**Returns:**
@ -1279,8 +1155,6 @@ The text in title case.
---
### `to`
**Description:**
Get a slice of the text, ending at the given position.
**Signature:**
@ -1288,8 +1162,6 @@ Get a slice of the text, ending at the given position.
func to(text: Text, last: Int -> Text)
```
**Parameters:**
- `text`: The text to be sliced.
- `last`: The index of the last grapheme cluster to include (1-indexed).
@ -1311,8 +1183,6 @@ the string.
---
### `trim`
**Description:**
Trims the matching [pattern](patterns.md) from the left and/or right side of the text.
**Signature:**
@ -1320,8 +1190,6 @@ Trims the matching [pattern](patterns.md) from the left and/or right side of the
func trim(text: Text, pattern: Pattern = $/{whitespace/, trim_left: Bool = yes, trim_right: Bool = yes -> Text)
```
**Parameters:**
- `text`: The text to be trimmed.
- `pattern`: The [pattern](patterns.md) that will be trimmed away.
- `trim_left`: Whether or not to trim from the front of the text.
@ -1345,8 +1213,6 @@ The text without the trim pattern at either end.
---
### `upper`
**Description:**
Converts all characters in the text to uppercase.
**Signature:**
@ -1354,8 +1220,6 @@ Converts all characters in the text to uppercase.
func upper(text: Text -> Text)
```
**Parameters:**
- `text`: The text to be converted to uppercase.
**Returns:**
@ -1370,8 +1234,6 @@ The uppercase version of the text.
---
### `utf32_codepoints`
**Description:**
Returns an array of Unicode code points for UTF32 encoding of the text.
**Signature:**
@ -1379,8 +1241,6 @@ Returns an array of Unicode code points for UTF32 encoding of the text.
func utf32_codepoints(text: Text -> [Int32])
```
**Parameters:**
- `text`: The text from which to extract Unicode code points.
**Returns:**

16
docs/threads.md
View File

@ -12,8 +12,6 @@ through [mutex-guarded datastructures](mutexed.md).
- [`func new(fn: func(->Void) -> Thread)`](#new)
### `cancel`
**Description:**
Requests the cancellation of a specified thread.
**Signature:**
@ -21,8 +19,6 @@ Requests the cancellation of a specified thread.
func cancel(thread: Thread)
```
**Parameters:**
- `thread`: The thread to cancel.
**Returns:**
@ -36,8 +32,6 @@ Nothing.
---
### `detach`
**Description:**
Detaches a specified thread, allowing it to run independently.
**Signature:**
@ -45,8 +39,6 @@ Detaches a specified thread, allowing it to run independently.
func detach(thread: Thread)
```
**Parameters:**
- `thread`: The thread to detach.
**Returns:**
@ -57,8 +49,6 @@ Nothing.
>> thread:detach()
```
### `join`
**Description:**
Waits for a specified thread to terminate.
**Signature:**
@ -66,8 +56,6 @@ Waits for a specified thread to terminate.
func join(thread: Thread)
```
**Parameters:**
- `thread`: The thread to join.
**Returns:**
@ -81,8 +69,6 @@ Nothing.
---
### `new`
**Description:**
Creates a new thread to execute a specified function.
**Signature:**
@ -90,8 +76,6 @@ Creates a new thread to execute a specified function.
func new(fn: func(->Void) -> Thread)
```
**Parameters:**
- `fn`: The function to be executed by the new thread.
**Returns:**