From e422079fcced744e3a6247aeb12a09a658989072 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sun, 15 Sep 2024 15:33:47 -0400 Subject: Add a Byte datatype --- docs/README.md | 2 +- docs/integers.md | 6 +-- docs/operators.md | 6 +-- docs/paths.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- docs/text.md | 12 +++--- 5 files changed, 128 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 763f863a..642293ce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -76,7 +76,7 @@ Exits the program with a given status and optionally prints a message. **Usage:** ```markdown -ask(message:Text = "", status:Int32 = 0_i32) -> Void +ask(message:Text = "", status:Int32 = 0[32]) -> Void ``` **Parameters:** diff --git a/docs/integers.md b/docs/integers.md index 50ecd034..1b25bcf0 100644 --- a/docs/integers.md +++ b/docs/integers.md @@ -8,9 +8,9 @@ Tomo has five types of integers: the GNU MP library. These integers are fast for small numbers and guaranteed to always be correct and never overflow. - `Int8`/`Int16`/`Int32`/`Int64`: Fixed-size integers that take up `N` bits. - These integers must be manually specified with their suffix (e.g. `5_i64`) - and are subject to overflowing. If an overflow occurs, a runtime error will - be raised. + These integers must be manually specified with their bits in square brackets + (e.g. `5[64]`) and are subject to overflowing. If an overflow occurs, a + runtime error will be raised. Conversion between integer types can be done by calling the target type as a function: `Int32(x)`. For fixed-width types, the conversion function also diff --git a/docs/operators.md b/docs/operators.md index a3c9e01e..85e53242 100644 --- a/docs/operators.md +++ b/docs/operators.md @@ -25,11 +25,11 @@ value to the user. ```tomo >> 0 <> 99 -= -1_i32 += -1[32] >> 5 <> 5 -= 0_i32 += 0[32] >> 99 <> 0 -= 1_i32 += 1[32] ``` It's particularly handy for using the array `sort()` method, which takes a diff --git a/docs/paths.md b/docs/paths.md index de483168..6408cc8a 100644 --- a/docs/paths.md +++ b/docs/paths.md @@ -40,11 +40,12 @@ intended. Paths can be created from text with slashes using ### `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. +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. **Usage:** ```markdown -append(path: Path, text: Text, permissions: Int32 = 0o644_i32) -> Void +append(path: Path, text: Text, permissions: Int32 = 0o644[32]) -> Void ``` **Parameters:** @@ -63,6 +64,33 @@ 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. + +**Usage:** +```markdown +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`). + +**Returns:** +Nothing. + +**Example:** +```markdown +(./log.txt):append_bytes([104[B], 105[B]]) +``` + +--- + ### `base_name` **Description:** @@ -146,7 +174,7 @@ Creates a new directory at the specified path with the given permissions. **Usage:** ```markdown -create_directory(path: Path, permissions=0o644_i32) -> Void +create_directory(path: Path, permissions=0o644[32]) -> Void ``` **Parameters:** @@ -404,6 +432,29 @@ The contents of the file. If the file does not exist, an error will be raised. ```markdown content := (./file.txt):read() ``` +--- + +### `read_bytes` + +**Description:** +Reads the contents of the file at the specified path. + +**Usage:** +```markdown +read_bytes(path: Path) -> [Byte] +``` + +**Parameters:** + +- `path`: The path of the file to read. + +**Returns:** +The byte contents of the file. If the file does not exist, an error will be raised. + +**Example:** +```markdown +content := (./file.txt):read_bytes() +``` --- @@ -554,7 +605,7 @@ writing cannot be successfully completed, a runtime error is raised. **Usage:** ```markdown -write(path: Path, text: Text, permissions=0o644_i32) -> Void +write(path: Path, text: Text, permissions=0o644[32]) -> Void ``` **Parameters:** @@ -573,6 +624,34 @@ 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. + +**Usage:** +```markdown +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`). + +**Returns:** +Nothing. + +**Example:** +```markdown +(./file.txt):write_bytes([104[B], 105[B]]) +``` + +--- + ### `write_unique` **Description:** @@ -602,3 +681,35 @@ The path of the newly created unique file. = "Hello, world!" 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. + +**Usage:** +```markdown +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. + +**Returns:** +The path of the newly created unique file. + +**Example:** +```markdown +>> created := (./file-XXXXXX.txt):write_unique_bytes([1[B], 2[B], 3[B]]) += (./file-27QHtq.txt) +>> created:read() += [1[B], 2[B], 3[B]] +created:remove() +``` diff --git a/docs/text.md b/docs/text.md index 18960b02..0b2b5709 100644 --- a/docs/text.md +++ b/docs/text.md @@ -441,7 +441,7 @@ An array of bytes (`[Int8]`) representing the text in UTF8 encoding. **Example:** ```tomo >> "Amélie":utf8_bytes() -= [65_i8, 109_i8, -61_i8, -87_i8, 108_i8, 105_i8, 101_i8] : [Int8] += [65[B], 109[B], 195[B], 169[B], 108[B], 105[B], 101[B]] : [Byte] ``` --- @@ -491,7 +491,7 @@ An array of 32-bit integer Unicode code points (`[Int32]`). **Example:** ```tomo >> "Amélie":utf32_codepoints() -= [65_i32, 109_i32, 233_i32, 108_i32, 105_i32, 101_i32] : [Int32] += [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32] ``` --- @@ -601,7 +601,7 @@ A new text with the specified codepoints after normalization has been applied. **Example:** ```tomo ->> Text.from_codepoints([197_i32, 107_i32, 101_i32]) +>> Text.from_codepoints([197[32], 107[32], 101[32]]) = "Åke" ``` @@ -628,7 +628,7 @@ A new text based on the input UTF8 bytes after normalization has been applied. **Example:** ```tomo ->> Text.from_bytes([-61_i8, -123_i8, 107_i8, 101_i8]) +>> Text.from_bytes([195[B], 133[B], 107[B], 101[B]]) = "Åke" ``` @@ -668,11 +668,11 @@ found. >> " one two three ":find("{id}", start=5) = 8 ->> len := 0_i64 +>> len := 0[64] >> " one ":find("{id}", length=&len) = 4 >> len -= 3_i64 += 3[64] ``` --- -- cgit v1.2.3