diff --git a/docs/arrays.md b/docs/arrays.md index 29965fb..4d9c117 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 b516915..300a3a6 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 84f3341..e1c3a1e 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,158 +458,6 @@ of the representable range or if the entire text can't be parsed as an integer, --- -### `to` - -**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` - -**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 -``` - ---- - -### `sqrt` - -**Description:** -Calculates the square root of an integer. - -**Signature:** -```tomo -func sqrt(x: Int -> Int) -``` - -**Parameters:** - -- `x`: The integer whose square root is to be calculated. - -**Returns:** -The integer part of the square root of `x`. - -**Example:** -```tomo ->> 16:sqrt() -= 4 ->> 17:sqrt() -= 4 -``` - ---- - -### `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` **Description:** @@ -510,28 +491,62 @@ The previous prime number less than `x`. --- -### `clamped` +### `sqrt` **Description:** -Returns the given number clamped between two values so that it is within -that range. +Calculates the square root of an integer. **Signature:** ```tomo -func clamped(x, low, high: Int -> Int) +func sqrt(x: Int -> Int) ``` **Parameters:** -- `x`: The integer to clamp. -- `low`: The lowest value the result can take. -- `high`: The highest value the result can take. +- `x`: The integer whose square root is to be calculated. **Returns:** -The first argument clamped between the other two arguments. +The integer part of the square root of `x`. **Example:** ```tomo ->> 2:clamped(5, 10) -= 5 +>> 16:sqrt() += 4 +>> 17:sqrt() += 4 +``` + +--- + +### `to` + +**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] ``` diff --git a/docs/moments.md b/docs/moments.md index 1cd26ed..cee53bd 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 aae6a48..5589de5 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,6 +294,31 @@ The inverse hyperbolic sine of `x`. --- +### `atan` + +**Description:** +Computes the arc tangent of a number. + +**Signature:** +```tomo +func atan(x: Num -> Num) +``` + +**Parameters:** + +- `x`: The number for which the arc tangent is to be calculated. + +**Returns:** +The arc tangent of `x` in radians. + +**Example:** +```tomo +>> 1.0:atan() // -> (π/4) += 0.7854 +``` + +--- + ### `atan2` **Description:** @@ -270,31 +345,6 @@ The arc tangent of `x/y` in radians. --- -### `atan` - -**Description:** -Computes the arc tangent of a number. - -**Signature:** -```tomo -func atan(x: Num -> Num) -``` - -**Parameters:** - -- `x`: The number for which the arc tangent is to be calculated. - -**Returns:** -The arc tangent of `x` in radians. - -**Example:** -```tomo ->> 1.0:atan() // -> (π/4) -= 0.7854 -``` - ---- - ### `atanh` **Description:** @@ -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,31 +574,6 @@ The complementary error function of `x`. --- -### `exp2` - -**Description:** -Computes \( 2^x \) for a number. - -**Signature:** -```tomo -func exp2(x: Num -> Num) -``` - -**Parameters:** - -- `x`: The exponent. - -**Returns:** -The value of \( 2^x \). - -**Example:** -```tomo ->> 3.0:exp2() -= 8 -``` - ---- - ### `exp` **Description:** @@ -546,6 +599,31 @@ The value of \( e^x \). --- +### `exp2` + +**Description:** +Computes \( 2^x \) for a number. + +**Signature:** +```tomo +func exp2(x: Num -> Num) +``` + +**Parameters:** + +- `x`: The exponent. + +**Returns:** +The value of \( 2^x \). + +**Example:** +```tomo +>> 3.0:exp2() += 8 +``` + +--- + ### `expm1` **Description:** @@ -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 b6d62b6..d361b83 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 dd57ada..728b978 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 2663197..306f201 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 e9c44b2..83e5cd9 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,56 +137,6 @@ Nothing. --- -### `remove` - -**Description:** -Removes an item from the set. - -**Signature:** -```tomo -func remove(set:@{T}, item: T -> Void) -``` - -**Parameters:** - -- `set`: The mutable reference to the set. -- `item`: The item to remove from the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums:remove(42) -``` - ---- - -### `remove_all` - -**Description:** -Removes multiple items from the set. - -**Signature:** -```tomo -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. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums:remove_all([1, 2, 3]) -``` - ---- - ### `clear` **Description:** @@ -225,80 +161,28 @@ Nothing. --- -### `with` +### `has` **Description:** -Creates a new set that is the union of the original set and another set. +Checks if the set contains a specified item. **Signature:** ```tomo -func with(set:{T}, other: {T} -> {T}) +func has(set:{T}, item:T -> Bool) ``` **Parameters:** -- `set`: The original set. -- `other`: The set to union with. +- `set`: The set to check. +- `item`: The item to check for presence. **Returns:** -A new set containing all items from both sets. +`yes` if the item is present, `no` otherwise. **Example:** ```tomo ->> {1, 2}:with({2, 3}) -= {1, 2, 3} -``` - ---- - -### `overlap` - -**Description:** -Creates a new set with items that are in both the original set and another set. - -**Signature:** -```tomo -func overlap(set:{T}, other: {T} -> {T}) -``` - -**Parameters:** - -- `set`: The original set. -- `other`: The set to intersect with. - -**Returns:** -A new set containing only items present in both sets. - -**Example:** -```tomo ->> {1, 2}:overlap({2, 3}) -= {2} -``` - ---- - -### `without` - -**Description:** -Creates a new set with items from the original set but without items from another set. - -**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} +>> {10, 20}:has(20) += yes ``` --- @@ -354,3 +238,128 @@ func is_superset_of(set:{T}, other: {T}, strict: Bool = no -> Bool) >> {1, 2, 3}:is_superset_of({1, 2}) = yes ``` +### `overlap` + +**Description:** +Creates a new set with items that are in both the original set and another set. + +**Signature:** +```tomo +func overlap(set:{T}, other: {T} -> {T}) +``` + +**Parameters:** + +- `set`: The original set. +- `other`: The set to intersect with. + +**Returns:** +A new set containing only items present in both sets. + +**Example:** +```tomo +>> {1, 2}:overlap({2, 3}) += {2} +``` + +--- + +### `remove` + +**Description:** +Removes an item from the set. + +**Signature:** +```tomo +func remove(set:@{T}, item: T -> Void) +``` + +**Parameters:** + +- `set`: The mutable reference to the set. +- `item`: The item to remove from the set. + +**Returns:** +Nothing. + +**Example:** +```tomo +>> nums:remove(42) +``` + +--- + +### `remove_all` + +**Description:** +Removes multiple items from the set. + +**Signature:** +```tomo +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. + +**Returns:** +Nothing. + +**Example:** +```tomo +>> nums:remove_all([1, 2, 3]) +``` + +--- + +### `with` + +**Description:** +Creates a new set that is the union of the original set and another set. + +**Signature:** +```tomo +func with(set:{T}, other: {T} -> {T}) +``` + +**Parameters:** + +- `set`: The original set. +- `other`: The set to union with. + +**Returns:** +A new set containing all items from both sets. + +**Example:** +```tomo +>> {1, 2}:with({2, 3}) += {1, 2, 3} +``` + +--- + +### `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 f453a1d..8ca8fa2 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 5af2639..bb57a97 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 960aa07..67f65f9 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,118 +563,6 @@ func ends_with(text: Text, suffix: Text -> Bool) --- -### `from_c_string` - -**Description:** -Converts a C-style string to a `Text` value. - -**Signature:** -```tomo -func from_c_string(str: CString -> Text) -``` - -**Parameters:** - -- `str`: The C-style string to be converted. - -**Returns:** -A `Text` value representing the C-style string. - -**Example:** -```tomo ->> Text.from_c_string(CString("Hello")) -= "Hello" -``` - ---- - -### `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. - -**Signature:** -```tomo -func from_codepoint_names(codepoint_names: [Text] -> [Text]) -``` - -**Parameters:** - -- `codepoint_names`: The names of each codepoint in the desired text. Names - are case-insentive. - -**Returns:** -A new text with the specified codepoints after normalization has been applied. -Any invalid names are ignored. - -**Example:** -```tomo ->> Text.from_codepoint_names([ - "LATIN CAPITAL LETTER A WITH RING ABOVE", - "LATIN SMALL LETTER K", - "LATIN SMALL LETTER E", -] -= "Åke" -``` - ---- - -### `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. - -**Signature:** -```tomo -func from_codepoint_names(codepoints: [Int32] -> [Text]) -``` - -**Parameters:** - -- `codepoints`: The UTF32 codepoints in the desired text. - -**Returns:** -A new text with the specified codepoints after normalization has been applied. - -**Example:** -```tomo ->> Text.from_codepoints([197[32], 107[32], 101[32]]) -= "Åke" -``` - ---- - -### `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. - -**Signature:** -```tomo -func from_codepoint_names(codepoints: [Int32] -> [Text]) -``` - -**Parameters:** - -- `codepoints`: The UTF32 codepoints in the desired text. - -**Returns:** -A new text based on the input UTF8 bytes after normalization has been applied. - -**Example:** -```tomo ->> Text.from_bytes([195[B], 133[B], 107[B], 101[B]]) -= "Åke" -``` - ---- - ### `find` **Description:** @@ -770,6 +669,118 @@ 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. + +**Signature:** +```tomo +func from_codepoint_names(codepoints: [Int32] -> [Text]) +``` + +**Parameters:** + +- `codepoints`: The UTF32 codepoints in the desired text. + +**Returns:** +A new text based on the input UTF8 bytes after normalization has been applied. + +**Example:** +```tomo +>> Text.from_bytes([195[B], 133[B], 107[B], 101[B]]) += "Åke" +``` + +--- + +### `from_c_string` + +**Description:** +Converts a C-style string to a `Text` value. + +**Signature:** +```tomo +func from_c_string(str: CString -> Text) +``` + +**Parameters:** + +- `str`: The C-style string to be converted. + +**Returns:** +A `Text` value representing the C-style string. + +**Example:** +```tomo +>> Text.from_c_string(CString("Hello")) += "Hello" +``` + +--- + +### `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. + +**Signature:** +```tomo +func from_codepoint_names(codepoint_names: [Text] -> [Text]) +``` + +**Parameters:** + +- `codepoint_names`: The names of each codepoint in the desired text. Names + are case-insentive. + +**Returns:** +A new text with the specified codepoints after normalization has been applied. +Any invalid names are ignored. + +**Example:** +```tomo +>> Text.from_codepoint_names([ + "LATIN CAPITAL LETTER A WITH RING ABOVE", + "LATIN SMALL LETTER K", + "LATIN SMALL LETTER E", +] += "Åke" +``` + +--- + +### `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. + +**Signature:** +```tomo +func from_codepoint_names(codepoints: [Int32] -> [Text]) +``` + +**Parameters:** + +- `codepoints`: The UTF32 codepoints in the desired text. + +**Returns:** +A new text with the specified codepoints after normalization has been applied. + +**Example:** +```tomo +>> Text.from_codepoints([197[32], 107[32], 101[32]]) += "Åke" +``` + +--- + ### `has` **Description:** @@ -887,38 +898,6 @@ The lowercase version of the text. --- -### `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. - -**Signature:** -```tomo -func matches(text: Text, pattern: Pattern -> [Text]) -``` - -**Parameters:** - -- `text`: The text to be searched. -- `pattern`: The [pattern](patterns.md) to search for. - -**Returns:** -An array of the matching text captures if the entire text matches the pattern, -or a null value otherwise. - -**Example:** -```tomo ->> "hello world":matches($/{id}/) -= none : [Text]? - ->> "hello world":matches($/{id} {id}/) -= ["hello", "world"] : [Text]? -``` - ---- - ### `map` **Description:** @@ -952,6 +931,38 @@ 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. + +**Signature:** +```tomo +func matches(text: Text, pattern: Pattern -> [Text]) +``` + +**Parameters:** + +- `text`: The text to be searched. +- `pattern`: The [pattern](patterns.md) to search for. + +**Returns:** +An array of the matching text captures if the entire text matches the pattern, +or a null value otherwise. + +**Example:** +```tomo +>> "hello world":matches($/{id}/) += none : [Text]? + +>> "hello world":matches($/{id} {id}/) += ["hello", "world"] : [Text]? +``` + +--- + ### `quoted` **Description:** @@ -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 4d91e8b..1ccacc3 100644 --- a/docs/threads.md +++ b/docs/threads.md @@ -6,6 +6,80 @@ through [mutex-guarded datastructures](mutexed.md). ## Thread Methods +- [`func cancel(thread: Thread)`](#`cancel) +- [`func detach(thread: Thread)`](#`detach) +- [`func join(thread: Thread)`](#`join) +- [`func new(fn: func(->Void) -> Thread)`](#`new) + +### `cancel` + +**Description:** +Requests the cancellation of a specified thread. + +**Signature:** +```tomo +func cancel(thread: Thread) +``` + +**Parameters:** + +- `thread`: The thread to cancel. + +**Returns:** +Nothing. + +**Example:** +```tomo +>> thread:cancel() +``` + +--- + +### `detach` + +**Description:** +Detaches a specified thread, allowing it to run independently. + +**Signature:** +```tomo +func detach(thread: Thread) +``` + +**Parameters:** + +- `thread`: The thread to detach. + +**Returns:** +Nothing. + +**Example:** +```tomo +>> thread:detach() +``` +### `join` + +**Description:** +Waits for a specified thread to terminate. + +**Signature:** +```tomo +func join(thread: Thread) +``` + +**Parameters:** + +- `thread`: The thread to join. + +**Returns:** +Nothing. + +**Example:** +```tomo +>> thread:join() +``` + +--- + ### `new` **Description:** @@ -37,75 +111,3 @@ A new `Thread` object representing the created thread. >> results:get() = 11 ``` - ---- - -### `cancel` - -**Description:** -Requests the cancellation of a specified thread. - -**Signature:** -```tomo -func cancel(thread: Thread) -``` - -**Parameters:** - -- `thread`: The thread to cancel. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> thread:cancel() -``` - ---- - -### `join` - -**Description:** -Waits for a specified thread to terminate. - -**Signature:** -```tomo -func join(thread: Thread) -``` - -**Parameters:** - -- `thread`: The thread to join. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> thread:join() -``` - ---- - -### `detach` - -**Description:** -Detaches a specified thread, allowing it to run independently. - -**Signature:** -```tomo -func detach(thread: Thread) -``` - -**Parameters:** - -- `thread`: The thread to detach. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> thread:detach() -```