aboutsummaryrefslogtreecommitdiff
path: root/api
diff options
context:
space:
mode:
Diffstat (limited to 'api')
-rw-r--r--api/api.md68
-rw-r--r--api/bytes.md7
-rw-r--r--api/bytes.yaml7
-rw-r--r--api/floats.md7
-rw-r--r--api/floats.yaml7
-rw-r--r--api/integers.md9
-rw-r--r--api/integers.yaml11
-rw-r--r--api/paths.md52
-rw-r--r--api/paths.yaml76
9 files changed, 216 insertions, 28 deletions
diff --git a/api/api.md b/api/api.md
index e5b45f5d..a155f525 100644
--- a/api/api.md
+++ b/api/api.md
@@ -295,15 +295,16 @@ Determines if an integer is between two numbers (inclusive).
Argument | Type | Description | Default
---------|------|-------------|---------
x | `Byte` | The integer to be checked. | -
-low | `Byte` | The lower bound to check (inclusive). | -
-high | `Byte` | The upper bound to check (inclusive). | -
+low | `Byte` | One end of the range to check (inclusive); | -
+high | `Byte` | The other end of the range to check (inclusive); | -
-**Return:** `yes` if `low <= x and x <= high`, otherwise `no`
+**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
**Example:**
```tomo
assert Byte(7).is_between(1, 10) == yes
+assert Byte(7).is_between(10, 1) == yes
assert Byte(7).is_between(100, 200) == no
assert Byte(7).is_between(1, 7) == yes
@@ -1698,7 +1699,7 @@ assert (255).hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"
## Int.is_between
```tomo
-Int.is_between : func(x: Int, low: Int, high: Int -> Bool)
+Int.is_between : func(x: Int, a: Int, b: Int -> Bool)
```
Determines if an integer is between two numbers (inclusive).
@@ -1706,15 +1707,16 @@ Determines if an integer is between two numbers (inclusive).
Argument | Type | Description | Default
---------|------|-------------|---------
x | `Int` | The integer to be checked. | -
-low | `Int` | The lower bound to check (inclusive). | -
-high | `Int` | The upper bound to check (inclusive). | -
+a | `Int` | One end of the range to check (inclusive). | -
+b | `Int` | The other end of the range to check (inclusive). | -
-**Return:** `yes` if `low <= x and x <= high`, otherwise `no`
+**Return:** `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no`
**Example:**
```tomo
assert (7).is_between(1, 10) == yes
+assert (7).is_between(10, 1) == yes
assert (7).is_between(100, 200) == no
assert (7).is_between(1, 7) == yes
@@ -2646,6 +2648,32 @@ for line in (/dev/stdin).by_line()!
say(line.upper())
```
+## Path.byte_writer
+
+```tomo
+Path.byte_writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(bytes:[Byte], close:Bool=no -> Result))
+```
+
+Returns a function that can be used to repeatedly write bytes to the same file.
+
+The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | The path of the file to write to. | -
+append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no`
+permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)`
+
+**Return:** Returns a function that can repeatedly write bytes to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending.
+
+
+**Example:**
+```tomo
+write := (./file.txt).byte_writer()
+write("Hello\n".utf8())!
+write("world\n".utf8(), close=yes)!
+
+```
## Path.can_execute
```tomo
@@ -3464,6 +3492,32 @@ assert created.read() == [1, 2, 3]
created.remove()
```
+## Path.writer
+
+```tomo
+Path.writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(text:Text, close:Bool=no -> Result))
+```
+
+Returns a function that can be used to repeatedly write to the same file.
+
+The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | The path of the file to write to. | -
+append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no`
+permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)`
+
+**Return:** Returns a function that can repeatedly write to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending.
+
+
+**Example:**
+```tomo
+write := (./file.txt).writer()
+write("Hello\n")!
+write("world\n", close=yes)!
+
+```
# Table
## Table.clear
diff --git a/api/bytes.md b/api/bytes.md
index bb54d92c..99055523 100644
--- a/api/bytes.md
+++ b/api/bytes.md
@@ -62,15 +62,16 @@ Determines if an integer is between two numbers (inclusive).
Argument | Type | Description | Default
---------|------|-------------|---------
x | `Byte` | The integer to be checked. | -
-low | `Byte` | The lower bound to check (inclusive). | -
-high | `Byte` | The upper bound to check (inclusive). | -
+low | `Byte` | One end of the range to check (inclusive); | -
+high | `Byte` | The other end of the range to check (inclusive); | -
-**Return:** `yes` if `low <= x and x <= high`, otherwise `no`
+**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
**Example:**
```tomo
assert Byte(7).is_between(1, 10) == yes
+assert Byte(7).is_between(10, 1) == yes
assert Byte(7).is_between(100, 200) == no
assert Byte(7).is_between(1, 7) == yes
diff --git a/api/bytes.yaml b/api/bytes.yaml
index dea650e2..adf7103b 100644
--- a/api/bytes.yaml
+++ b/api/bytes.yaml
@@ -57,7 +57,7 @@ Byte.is_between:
return:
type: 'Bool'
description: >
- `yes` if `low <= x and x <= high`, otherwise `no`
+ `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
args:
x:
type: 'Byte'
@@ -66,13 +66,14 @@ Byte.is_between:
low:
type: 'Byte'
description: >
- The lower bound to check (inclusive).
+ One end of the range to check (inclusive);
high:
type: 'Byte'
description: >
- The upper bound to check (inclusive).
+ The other end of the range to check (inclusive);
example: |
assert Byte(7).is_between(1, 10) == yes
+ assert Byte(7).is_between(10, 1) == yes
assert Byte(7).is_between(100, 200) == no
assert Byte(7).is_between(1, 7) == yes
diff --git a/api/floats.md b/api/floats.md
index 69097bfd..a6d78b78 100644
--- a/api/floats.md
+++ b/api/floats.md
@@ -574,15 +574,16 @@ Determines if a number is between two numbers (inclusive).
Argument | Type | Description | Default
---------|------|-------------|---------
x | `Float` | The integer to be checked. | -
-low | `Float` | The lower bound to check (inclusive). | -
-high | `Float` | The upper bound to check (inclusive). | -
+low | `Num` | One end of the range to check (inclusive). | -
+high | `Num` | The other end of the range to check (inclusive). | -
-**Return:** `yes` if `low <= x and x <= high`, otherwise `no`
+**Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
**Example:**
```tomo
assert (7.5).is_between(1, 10) == yes
+assert (7.5).is_between(10, 1) == yes
assert (7.5).is_between(100, 200) == no
assert (7.5).is_between(1, 7.5) == yes
diff --git a/api/floats.yaml b/api/floats.yaml
index 3720b160..da053d2c 100644
--- a/api/floats.yaml
+++ b/api/floats.yaml
@@ -401,7 +401,7 @@ Float.is_between:
return:
type: 'Bool'
description: >
- `yes` if `low <= x and x <= high`, otherwise `no`
+ `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
args:
x:
type: 'Float'
@@ -410,13 +410,14 @@ Float.is_between:
low:
type: 'Float'
description: >
- The lower bound to check (inclusive).
+ One end of the range to check (inclusive).
high:
type: 'Float'
description: >
- The upper bound to check (inclusive).
+ The other end of the range to check (inclusive).
example: |
assert (7.5).is_between(1, 10) == yes
+ assert (7.5).is_between(10, 1) == yes
assert (7.5).is_between(100, 200) == no
assert (7.5).is_between(1, 7.5) == yes
diff --git a/api/integers.md b/api/integers.md
index ef3a6a60..73779021 100644
--- a/api/integers.md
+++ b/api/integers.md
@@ -138,7 +138,7 @@ assert (255).hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"
## Int.is_between
```tomo
-Int.is_between : func(x: Int, low: Int, high: Int -> Bool)
+Int.is_between : func(x: Int, a: Int, b: Int -> Bool)
```
Determines if an integer is between two numbers (inclusive).
@@ -146,15 +146,16 @@ Determines if an integer is between two numbers (inclusive).
Argument | Type | Description | Default
---------|------|-------------|---------
x | `Int` | The integer to be checked. | -
-low | `Int` | The lower bound to check (inclusive). | -
-high | `Int` | The upper bound to check (inclusive). | -
+a | `Int` | One end of the range to check (inclusive). | -
+b | `Int` | The other end of the range to check (inclusive). | -
-**Return:** `yes` if `low <= x and x <= high`, otherwise `no`
+**Return:** `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no`
**Example:**
```tomo
assert (7).is_between(1, 10) == yes
+assert (7).is_between(10, 1) == yes
assert (7).is_between(100, 200) == no
assert (7).is_between(1, 7) == yes
diff --git a/api/integers.yaml b/api/integers.yaml
index b3c6b579..bbbd395d 100644
--- a/api/integers.yaml
+++ b/api/integers.yaml
@@ -146,22 +146,23 @@ Int.is_between:
return:
type: 'Bool'
description: >
- `yes` if `low <= x and x <= high`, otherwise `no`
+ `yes` if `a <= x and x <= b` or `a >= x and x >= b`, otherwise `no`
args:
x:
type: 'Int'
description: >
The integer to be checked.
- low:
+ a:
type: 'Int'
description: >
- The lower bound to check (inclusive).
- high:
+ One end of the range to check (inclusive).
+ b:
type: 'Int'
description: >
- The upper bound to check (inclusive).
+ The other end of the range to check (inclusive).
example: |
assert (7).is_between(1, 10) == yes
+ assert (7).is_between(10, 1) == yes
assert (7).is_between(100, 200) == no
assert (7).is_between(1, 7) == yes
diff --git a/api/paths.md b/api/paths.md
index 435932e3..8c08b45b 100644
--- a/api/paths.md
+++ b/api/paths.md
@@ -118,6 +118,32 @@ for line in (/dev/stdin).by_line()!
say(line.upper())
```
+## Path.byte_writer
+
+```tomo
+Path.byte_writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(bytes:[Byte], close:Bool=no -> Result))
+```
+
+Returns a function that can be used to repeatedly write bytes to the same file.
+
+The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | The path of the file to write to. | -
+append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no`
+permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)`
+
+**Return:** Returns a function that can repeatedly write bytes to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending.
+
+
+**Example:**
+```tomo
+write := (./file.txt).byte_writer()
+write("Hello\n".utf8())!
+write("world\n".utf8(), close=yes)!
+
+```
## Path.can_execute
```tomo
@@ -936,3 +962,29 @@ assert created.read() == [1, 2, 3]
created.remove()
```
+## Path.writer
+
+```tomo
+Path.writer : func(path: Path, append: Bool = no, permissions: Int32 = Int32(0o644) -> func(text:Text, close:Bool=no -> Result))
+```
+
+Returns a function that can be used to repeatedly write to the same file.
+
+The file writer will keep its file descriptor open after each write (unless the `close` argument is set to `yes`). If the file writer is never closed, it will be automatically closed when the file writer is garbage collected.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | The path of the file to write to. | -
+append | `Bool` | If set to `yes`, writes to the file will append. If set to `no`, then the first write to the file will overwrite its contents and subsequent calls will append. | `no`
+permissions | `Int32` | The permissions to set on the file if it is created. | `Int32(0o644)`
+
+**Return:** Returns a function that can repeatedly write to the same file. If `close` is set to `yes`, then the file will be closed after writing. If this function is called again after closing, the file will be reopened for appending.
+
+
+**Example:**
+```tomo
+write := (./file.txt).writer()
+write("Hello\n")!
+write("world\n", close=yes)!
+
+```
diff --git a/api/paths.yaml b/api/paths.yaml
index 02b8fbe8..a659ffbc 100644
--- a/api/paths.yaml
+++ b/api/paths.yaml
@@ -838,6 +838,82 @@ Path.write:
example: |
(./file.txt).write("Hello, world!")
+Path.writer:
+ short: create a file writer
+ description: >
+ Returns a function that can be used to repeatedly write to the same file.
+ note: >
+ The file writer will keep its file descriptor open after each write (unless
+ the `close` argument is set to `yes`). If the file writer is never closed,
+ it will be automatically closed when the file writer is garbage collected.
+ return:
+ type: 'func(text:Text, close:Bool=no -> Result)'
+ description: >
+ Returns a function that can repeatedly write to the same file. If `close`
+ is set to `yes`, then the file will be closed after writing. If this
+ function is called again after closing, the file will be reopened for
+ appending.
+ args:
+ path:
+ type: 'Path'
+ description: >
+ The path of the file to write to.
+ append:
+ type: 'Bool'
+ default: 'no'
+ description: >
+ If set to `yes`, writes to the file will append. If set to `no`, then
+ the first write to the file will overwrite its contents and subsequent
+ calls will append.
+ permissions:
+ type: 'Int32'
+ default: 'Int32(0o644)'
+ description: >
+ The permissions to set on the file if it is created.
+ example: |
+ write := (./file.txt).writer()
+ write("Hello\n")!
+ write("world\n", close=yes)!
+
+Path.byte_writer:
+ short: create a byte-based file writer
+ description: >
+ Returns a function that can be used to repeatedly write bytes to the same
+ file.
+ note: >
+ The file writer will keep its file descriptor open after each write (unless
+ the `close` argument is set to `yes`). If the file writer is never closed,
+ it will be automatically closed when the file writer is garbage collected.
+ return:
+ type: 'func(bytes:[Byte], close:Bool=no -> Result)'
+ description: >
+ Returns a function that can repeatedly write bytes to the same file. If
+ `close` is set to `yes`, then the file will be closed after writing. If
+ this function is called again after closing, the file will be reopened
+ for appending.
+ args:
+ path:
+ type: 'Path'
+ description: >
+ The path of the file to write to.
+ append:
+ type: 'Bool'
+ default: 'no'
+ description: >
+ If set to `yes`, writes to the file will append. If set to `no`, then
+ the first write to the file will overwrite its contents and subsequent
+ calls will append.
+ permissions:
+ type: 'Int32'
+ default: 'Int32(0o644)'
+ description: >
+ The permissions to set on the file if it is created.
+ example: |
+ write := (./file.txt).byte_writer()
+ write("Hello\n".utf8())!
+ write("world\n".utf8(), close=yes)!
+
+
Path.write_bytes:
short: write bytes to a file
description: >
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-01 06:11:47 +0000