aboutsummaryrefslogtreecommitdiff
path: root/api
diff options
context:
space:
mode:
Diffstat (limited to 'api')
-rw-r--r--api/api.md137
-rw-r--r--api/bytes.md30
-rw-r--r--api/bytes.yaml30
-rw-r--r--api/integers.md30
-rw-r--r--api/integers.yaml36
-rw-r--r--api/paths.md28
-rw-r--r--api/paths.yaml28
-rw-r--r--api/sets.md24
-rw-r--r--api/tables.md27
9 files changed, 369 insertions, 1 deletions
diff --git a/api/api.md b/api/api.md
index cbaa7a54..9711ab44 100644
--- a/api/api.md
+++ b/api/api.md
@@ -210,6 +210,36 @@ text | `Text` | The string containing the boolean value. | -
```
# Byte
+## Byte.get_bit
+
+```tomo
+Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)
+```
+
+In the binary representation of a byte, check whether a given bit index is set to 1 or not.
+
+The bit index must be between 1-8 or a runtime error will be produced.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Byte` | The byte whose bits are being inspected. | -
+bit_index | `Int` | The index of the bit to check (1-indexed, range 1-8). | -
+
+**Return:** Whether or not the given bit index is set to 1 in the byte.
+
+
+**Example:**
+```tomo
+>> Byte(6).get_bit(1)
+= no
+>> Byte(6).get_bit(2)
+= yes
+>> Byte(6).get_bit(3)
+= yes
+>> Byte(6).get_bit(4)
+= no
+
+```
## Byte.hex
```tomo
@@ -402,6 +432,36 @@ n | `Int` | The integer to compute the factorial of. | -
= 3628800
```
+## Int.get_bit
+
+```tomo
+Int.get_bit : func(i: Int, bit_index: Int -> Bool)
+```
+
+In the binary representation of an integer, check whether a given bit index is set to 1 or not.
+
+For fixed-size integers, the bit index must be between 1 and the number of bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must be between 1 and `Int64.max`. Values outside this range will produce a runtime error.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Int` | The integer whose bits are being inspected. | -
+bit_index | `Int` | The index of the bit to check (1-indexed). | -
+
+**Return:** Whether or not the given bit index is set to 1 in the binary representation of the integer.
+
+
+**Example:**
+```tomo
+>> (6).get_bit(1)
+= no
+>> (6).get_bit(2)
+= yes
+>> (6).get_bit(3)
+= yes
+>> (6).get_bit(4)
+= no
+
+```
## Int.hex
```tomo
@@ -3010,6 +3070,34 @@ follow_symlinks | `Bool` | Whether to follow symbolic links. | `yes`
= none
```
+## Path.has_extension
+
+```tomo
+Path.has_extension : func(path: Path, extension: Text -> Bool)
+```
+
+Return whether or not a path has a given file extension.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | A path. | -
+extension | `Text` | A file extension (leading `.` is optional). If empty, the check will test if the file does not have any file extension. | -
+
+**Return:** Whether or not the path has the given extension.
+
+
+**Example:**
+```tomo
+>> (/foo.txt).has_extension("txt")
+= yes
+>> (/foo.txt).has_extension(".txt")
+= yes
+>> (/foo.tar.gz).has_extension("gz")
+= yes
+>> (/foo.tar.gz).has_extension("zip")
+= no
+
+```
## Path.is_directory
```tomo
@@ -3880,6 +3968,55 @@ t.set("C", 3)
= {"A"=1, "B"=2, "C"=3}
```
+## Table.with_fallback
+
+```tomo
+Table.with_fallback : func(t: {K=V}, fallback: {K=V}? -> {K=V})
+```
+
+Return a copy of a table with a different fallback table.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K=V}` | The table whose fallback will be replaced. | -
+fallback | `{K=V}?` | The new fallback table value. | -
+
+**Return:** The original table with a different fallback.
+
+
+**Example:**
+```tomo
+t := {"A"=1; fallback={"B"=2}}
+t2 = t.with_fallback({"B"=3"})
+>> t2["B"]
+= 3?
+t3 = t.with_fallback(none)
+>> t2["B"]
+= none
+
+```
+## Table.xor
+
+```tomo
+Table.xor : func(a: |T|, b: |T| -> |T|)
+```
+
+Return set with the elements in one, but not both of the arguments. This is also known as the symmetric difference or disjunctive union.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+a | `|T|` | The first set. | -
+b | `|T|` | The second set. | -
+
+**Return:** A set with the symmetric difference of the arguments.
+
+
+**Example:**
+```tomo
+>> |1, 2, 3|.xor(|2, 3, 4|)
+= |1, 4|
+
+```
# Text
## Text.as_c_string
diff --git a/api/bytes.md b/api/bytes.md
index 598c92b7..908d78e2 100644
--- a/api/bytes.md
+++ b/api/bytes.md
@@ -3,6 +3,36 @@
# Builtins
# Byte
+## Byte.get_bit
+
+```tomo
+Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)
+```
+
+In the binary representation of a byte, check whether a given bit index is set to 1 or not.
+
+The bit index must be between 1-8 or a runtime error will be produced.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Byte` | The byte whose bits are being inspected. | -
+bit_index | `Int` | The index of the bit to check (1-indexed, range 1-8). | -
+
+**Return:** Whether or not the given bit index is set to 1 in the byte.
+
+
+**Example:**
+```tomo
+>> Byte(6).get_bit(1)
+= no
+>> Byte(6).get_bit(2)
+= yes
+>> Byte(6).get_bit(3)
+= yes
+>> Byte(6).get_bit(4)
+= no
+
+```
## Byte.hex
```tomo
diff --git a/api/bytes.yaml b/api/bytes.yaml
index 52f48528..2785513d 100644
--- a/api/bytes.yaml
+++ b/api/bytes.yaml
@@ -1,3 +1,33 @@
+Byte.get_bit:
+ short: check whether a bit is set
+ description: >
+ In the binary representation of a byte, check whether a given bit index is
+ set to 1 or not.
+ note: >
+ The bit index must be between 1-8 or a runtime error will be produced.
+ return:
+ type: 'Bool'
+ description: >
+ Whether or not the given bit index is set to 1 in the byte.
+ args:
+ i:
+ type: 'Byte'
+ description: >
+ The byte whose bits are being inspected.
+ bit_index:
+ type: 'Int'
+ description: >
+ The index of the bit to check (1-indexed, range 1-8).
+ example: |
+ >> Byte(6).get_bit(1)
+ = no
+ >> Byte(6).get_bit(2)
+ = yes
+ >> Byte(6).get_bit(3)
+ = yes
+ >> Byte(6).get_bit(4)
+ = no
+
Byte.hex:
short: convert to hexidecimal
description: >
diff --git a/api/integers.md b/api/integers.md
index 0865e93f..efb891bf 100644
--- a/api/integers.md
+++ b/api/integers.md
@@ -90,6 +90,36 @@ n | `Int` | The integer to compute the factorial of. | -
= 3628800
```
+## Int.get_bit
+
+```tomo
+Int.get_bit : func(i: Int, bit_index: Int -> Bool)
+```
+
+In the binary representation of an integer, check whether a given bit index is set to 1 or not.
+
+For fixed-size integers, the bit index must be between 1 and the number of bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must be between 1 and `Int64.max`. Values outside this range will produce a runtime error.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Int` | The integer whose bits are being inspected. | -
+bit_index | `Int` | The index of the bit to check (1-indexed). | -
+
+**Return:** Whether or not the given bit index is set to 1 in the binary representation of the integer.
+
+
+**Example:**
+```tomo
+>> (6).get_bit(1)
+= no
+>> (6).get_bit(2)
+= yes
+>> (6).get_bit(3)
+= yes
+>> (6).get_bit(4)
+= no
+
+```
## Int.hex
```tomo
diff --git a/api/integers.yaml b/api/integers.yaml
index f927c75f..a91a21ce 100644
--- a/api/integers.yaml
+++ b/api/integers.yaml
@@ -81,7 +81,41 @@ Int.factorial:
example: |
>> (10).factorial()
= 3628800
-
+
+Int.get_bit:
+ short: check whether a bit is set
+ description: >
+ In the binary representation of an integer, check whether a given bit index
+ is set to 1 or not.
+ note: >
+ For fixed-size integers, the bit index must be between 1 and the number of
+ bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must
+ be between 1 and `Int64.max`. Values outside this range will produce a
+ runtime error.
+ return:
+ type: 'Bool'
+ description: >
+ Whether or not the given bit index is set to 1 in the binary
+ representation of the integer.
+ args:
+ i:
+ type: 'Int'
+ description: >
+ The integer whose bits are being inspected.
+ bit_index:
+ type: 'Int'
+ description: >
+ The index of the bit to check (1-indexed).
+ example: |
+ >> (6).get_bit(1)
+ = no
+ >> (6).get_bit(2)
+ = yes
+ >> (6).get_bit(3)
+ = yes
+ >> (6).get_bit(4)
+ = no
+
Int.hex:
short: convert to hexidecimal
description: >
diff --git a/api/paths.md b/api/paths.md
index ad6b894b..aade9b0f 100644
--- a/api/paths.md
+++ b/api/paths.md
@@ -489,6 +489,34 @@ follow_symlinks | `Bool` | Whether to follow symbolic links. | `yes`
= none
```
+## Path.has_extension
+
+```tomo
+Path.has_extension : func(path: Path, extension: Text -> Bool)
+```
+
+Return whether or not a path has a given file extension.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | A path. | -
+extension | `Text` | A file extension (leading `.` is optional). If empty, the check will test if the file does not have any file extension. | -
+
+**Return:** Whether or not the path has the given extension.
+
+
+**Example:**
+```tomo
+>> (/foo.txt).has_extension("txt")
+= yes
+>> (/foo.txt).has_extension(".txt")
+= yes
+>> (/foo.tar.gz).has_extension("gz")
+= yes
+>> (/foo.tar.gz).has_extension("zip")
+= no
+
+```
## Path.is_directory
```tomo
diff --git a/api/paths.yaml b/api/paths.yaml
index 40813129..1bfe5d6d 100644
--- a/api/paths.yaml
+++ b/api/paths.yaml
@@ -463,6 +463,34 @@ Path.group:
= "root"
>> (/non/existent/file).group()
= none
+
+Path.has_extension:
+ short: check if a path has a given extension
+ description: >
+ Return whether or not a path has a given file extension.
+ return:
+ type: 'Bool'
+ description: >
+ Whether or not the path has the given extension.
+ args:
+ path:
+ type: 'Path'
+ description: >
+ A path.
+ extension:
+ type: 'Text'
+ description: >
+ A file extension (leading `.` is optional). If empty, the check will
+ test if the file does not have any file extension.
+ example: |
+ >> (/foo.txt).has_extension("txt")
+ = yes
+ >> (/foo.txt).has_extension(".txt")
+ = yes
+ >> (/foo.tar.gz).has_extension("gz")
+ = yes
+ >> (/foo.tar.gz).has_extension("zip")
+ = no
Path.is_directory:
short: check if a path is a directory
diff --git a/api/sets.md b/api/sets.md
index b64439c2..8b07cf08 100644
--- a/api/sets.md
+++ b/api/sets.md
@@ -241,3 +241,27 @@ other | `|T|` | The set of items to remove from the original set. | -
= |1|
```
+
+# Table
+## Table.xor
+
+```tomo
+Table.xor : func(a: |T|, b: |T| -> |T|)
+```
+
+Return set with the elements in one, but not both of the arguments. This is also known as the symmetric difference or disjunctive union.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+a | `|T|` | The first set. | -
+b | `|T|` | The second set. | -
+
+**Return:** A set with the symmetric difference of the arguments.
+
+
+**Example:**
+```tomo
+>> |1, 2, 3|.xor(|2, 3, 4|)
+= |1, 4|
+
+```
diff --git a/api/tables.md b/api/tables.md
index 580488f4..26bfe908 100644
--- a/api/tables.md
+++ b/api/tables.md
@@ -164,3 +164,30 @@ t.set("C", 3)
= {"A"=1, "B"=2, "C"=3}
```
+## Table.with_fallback
+
+```tomo
+Table.with_fallback : func(t: {K=V}, fallback: {K=V}? -> {K=V})
+```
+
+Return a copy of a table with a different fallback table.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K=V}` | The table whose fallback will be replaced. | -
+fallback | `{K=V}?` | The new fallback table value. | -
+
+**Return:** The original table with a different fallback.
+
+
+**Example:**
+```tomo
+t := {"A"=1; fallback={"B"=2}}
+t2 = t.with_fallback({"B"=3"})
+>> t2["B"]
+= 3?
+t3 = t.with_fallback(none)
+>> t2["B"]
+= none
+
+```
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-01 06:31:39 +0000