Merge branch 'dev' into constructive-reals

1 files changed, 61 insertions, 7 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