Update docs and changelog

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project does not currently adhere to a particular versioning scheme.
 - Add `to_f24`, `to_u24` and `to_i24` number casting builtin functions. ([#582][gh-582])
 - Add `IO/sleep` builtin function to sleep for a given amount of seconds as a float. ([#581][gh-581])
 - Add primitive file IO functions `IO/FS/{read, write, seek, open, close}`. ([#573][gh-573])
+- Add encoding/decoding builtin functions `Bytes/{decode_utf8, decode_ascii} String/{encode_ascii, decode_ascii} Utf8/decode_rune`. ([#580][gh-580])
 
 ## [0.2.35] - 2024-06-06
 
@@ -346,6 +347,7 @@ and this project does not currently adhere to a particular versioning scheme.
 [gh-528]: https://github.com/HigherOrderCO/Bend/issues/528
 [gh-581]: https://github.com/HigherOrderCO/Bend/issues/581
 [gh-573]: https://github.com/HigherOrderCO/Bend/issues/573
+[gh-580]: https://github.com/HigherOrderCO/Bend/issues/580
 [gh-582]: https://github.com/HigherOrderCO/Bend/issues/582
 [gh-583]: https://github.com/HigherOrderCO/Bend/issues/583
 [gh-586]: https://github.com/HigherOrderCO/Bend/issues/586

docs/builtins.md

@@ -1,25 +1,28 @@
->this is a WIP based on [Builtins.bend](https://github.com/HigherOrderCO/Bend/blob/main/src/fun/builtins.bend).
+> this is a WIP based on [Builtins.bend](https://github.com/HigherOrderCO/Bend/blob/main/src/fun/builtins.bend).
 
 # Built-in Types and Functions
+
 **Bend** built-in types and functions, this document serves as a reference guide. Read more at [FEATURES.md](https://github.com/HigherOrderCO/Bend/blob/main/FEATURES.md).
 
 ## String
+
 ```python
 type String = (Cons head ~tail) | (Nil)
 ```
 
-
 - **Nil**: Represents an empty string.
 - **Cons head ~tail**: Represents a string with a `head` character and a `tail` string.
 
 ### Syntax
+
 A String literal is surrounded with `"`. Accepts the same values as characters literals.
+
 ```
 "Hello, World!"
 ```
 
-
 ## List
+
 ```python
 type List = (Cons head ~tail) | (Nil)
 ```
@@ -28,14 +31,15 @@ type List = (Cons head ~tail) | (Nil)
 - **Cons head ~tail**: Represents a list with a `head` element and a `tail` list.
 
 ### Syntax
+
 A List of values can be written using `[ ]`, it can have multiple values inside, using `,` you can divide its value in a list of multiple elements.
 
 ```
 ["This", "List", "Has", "Multiple", "Values"]
 ```
 
-
 ## Tree
+
 ```python
 type Tree:
   Node { ~left, ~right }
@@ -49,15 +53,19 @@ Trees are a structure that naturally lends itself to parallel recursion, so writ
 - **Leaf { value }**: Represents one of the ends of the tree, storing `value`.
 
 #### Syntax
+
 **Bend** provides the `![]` operator to create tree branches and the `!` operator to create a tree leaf.
+
 ```py
 # ![a, b] => Equivalent to Tree/Node { left: a, right: b }
 # !x      => Equivalent to Tree/Leaf { value: x }
 tree = ![![!1, !2],![!3, !4]]
 ```
+
 Technically your trees don't need to end with leaves, but if you don't, your program will be very hard to reason about.
 
 ## Map
+
 ```python
 type Map:
   Node { value ~left ~right }
@@ -71,7 +79,9 @@ It is meant to be used as an efficient map data structure with integer keys and
 - **Leaf**: Represents an unwritten, empty portion of the map.
 
 #### Syntax
+
 Here's how you create a new `Map` with some initial values.:
+
 ```python
 { 0: 4, `hi`: "bye", 'c': 2 + 3 }
 ```
@@ -81,6 +91,7 @@ The keys must be `U24` numbers, and can be given as literals or any other expres
 The values can be anything, but storing data of different types in a `Map` will make it harder for you to reason about it.
 
 You can read and write a value of a map with the `[]` operator:
+
 ```python
 map = { 0: "zero", 1: "one", 2: "two", 3: "three" }
 map[0] = "not zero"
@@ -91,18 +102,21 @@ map[3] = map[1] + map[map[1]]
 
 Here, `map` must be the name of the `Map` variable, and the keys inside `[]` can be any expression that evaluates to a `U24`.
 
-
 ## Map functions
 
 ### Map/empty
+
 Initializes an empty map.
+
 ```python
 Map/empty = Map/Leaf
 ```
 
 ### Map/get
+
 Retrieves a `value` from the `map` based on the `key`.
 Returns a tuple with the value and the `map` unchanged.
+
 ```rust
 Map/get map key =
   match map {
@@ -123,22 +137,30 @@ Map/get map key =
 ```
 
 #### Syntax
+
 Considering the following map
+
 ```python
 { 0: "hello", 1: "bye", 2: "maybe", 3: "yes"}
 ```
+
 The `get` function can be written as
+
 ```
 return x[0]  # Gets the value of the key 0
 ```
+
 And the value resultant from the get function would be:
+
 ```
 "hello"
 ```
 
 ### Map/set
+
 Sets a `value` in the `map` at the specified `key`.
 Returns the map with the new value.
+
 ```rust
 Map/set map key value =
   match map {
@@ -160,32 +182,44 @@ Map/set map key value =
       }
   }
 ```
+
 #### Syntax
+
 Considering the following tree
+
 ```python
 { 0: "hello", 1: "bye", 2: "maybe", 3: "yes"}
 ```
+
 The `set` function can be written as
+
 ```py
 x[0] = "swapped"     # Assigns the key 0 to the value "swapped"
 ```
+
 And the value resultant from the get function would be:
+
 ```py
 { 0: "swapped", 1: "bye", 2: "maybe", 3: "yes"}
 ```
+
 If there's no matching `key` in the tree, it would add a new branch to that tree with the value `set`
 
 ```py
 x[4] = "added"     # Assigns the key 4 to the value "added"
 ```
+
 The new tree
+
 ```py
 { 0: "swapped", 1: "bye", 2: "maybe", 3: "yes", 4: "added"}
 ```
 
 ### Map/map
+
 Applies a function to a value in the map.
 Returns the map with the value mapped.
+
 ```rust
 Map/map (Map/Leaf)                  key f = Map/Leaf
 Map/map (Map/Node value left right) key f =
@@ -201,30 +235,33 @@ Map/map (Map/Node value left right) key f =
 ```
 
 #### Syntax
+
 With the same map that we `set` in the previous section, we can map it's values with `@=`:
+
 ```py
 x[0] @= lambda y: String/concat(y, " and mapped")
 # x[0] now contains "swapped and mapped"
 ```
 
-
 ## Nat
+
 ```python
 type Nat = (Succ ~pred) | (Zero)
 ```
+
 - **Succ ~pred**: Represents a natural number successor.
 - **Zero**: Represents the natural number zero.
 
 ### Syntax
+
 A Natural Number can be written with literals with a `#` before the literal number.
 
 ```
 #1337
 ```
 
-
-
 ## IO
+
 The basic builtin IO functions are under development and will be stable in the next milestone.
 
 Here is the current list of functions, but be aware that they may change in the near future.
@@ -232,11 +269,13 @@ Here is the current list of functions, but be aware that they may change in the
 ### File IO
 
 #### File open
+
 ```python
 def IO/FS/open(path, mode)
 ```
 
 Opens a file with with `path` being given as a string and `mode` being a string with the mode to open the file in. The mode should be one of the following:
+
 - `"r"`: Read mode
 - `"w"`: Write mode (write at the beginning of the file, overwriting any existing content)
 - `"a"`: Append mode (write at the end of the file)
@@ -249,11 +288,13 @@ Returns an U24 with the file descriptor. File descriptors are not necessarily th
 #### File descriptors for standard files
 
 The standard input/output files are always open and assigned the following file descriptors:
+
 - `IO/FS/STDIN = 0`: Standard input
 - `IO/FS/STDOUT = 1`: Standard output
 - `IO/FS/STDERR = 2`: Standard error
 
 #### File close
+
 ```python
 def IO/FS/close(file)
 ```
@@ -261,6 +302,7 @@ def IO/FS/close(file)
 Closes the file with the given `file` descriptor.
 
 #### File read
+
 ```python
 def IO/FS/read(file, num_bytes)
 ```
@@ -270,6 +312,7 @@ Reads `num_bytes` bytes from the file with the given `file` descriptor.
 Returns a list of U24 with each element representing a byte read from the file.
 
 #### File write
+
 ```python
 def IO/FS/write(file, bytes)
 ```
@@ -278,9 +321,10 @@ Writes `bytes`, a list of U24 with each element representing a byte, to the file
 
 Returns nothing (`*`).
 
-Writing discards any preexisting content that came after the current position. For example, if your file contains the text `Hello, world!` and the current position is at the `,`, writing `!` will 
+Writing discards any preexisting content that came after the current position. For example, if your file contains the text `Hello, world!` and the current position is at the `,`, writing `!` will
 
 #### File seek
+
 ```python
 def IO/FS/seek(file, offset, mode)
 ```
@@ -288,6 +332,7 @@ def IO/FS/seek(file, offset, mode)
 Moves the current position of the file with the given `file` descriptor to the given `offset`, an I24 or U24 number, in bytes.
 
 `mode` can be one of the following:
+
 - `IO/FS/SEEK_SET = 0`: Seek from start of file
 - `IO/FS/SEEK_CUR = 1`: Seek from current position
 - `IO/FS/SEEK_END = 2`: Seek from end of file
@@ -297,33 +342,86 @@ Returns nothing (`*`).
 ## Numeric operations
 
 ### log
+
 ```py
 def log(x: f24, base: f24) -> f24
 ```
+
 Computes the logarithm of `x` with the specified `base`.
 
 ### atan2
+
 ```py
 def atan2(x: f24, y: f24) -> f24
 ```
+
 Computes the arctangent of `y / x`.
 
 Has the same behaviour as `atan2f` in the C math lib.
 
 ### to_f24
+
 ```py
 def to_f24(x: any number) -> f24
 ```
+
 Casts any native number to an f24.
 
 ### to_u24
+
 ```py
 def to_u24(x: any number) -> u24
 ```
+
 Casts any native number to a u24.
 
 ### to_i24
+
 ```py
 def to_i24(x: any number) -> i24
 ```
+
 Casts any native number to an i24.
+
+## Encoding functions
+
+### Bytes/decode_utf8
+
+```python
+def Bytes/decode_utf8(bytes: [u24], out: String) -> String
+```
+
+Decodes a sequence of bytes to a String using utf-8 encoding.
+
+### Bytes/decode_ascii
+
+```python
+def Bytes/decode_ascii(bytes: [u24]) -> String
+```
+
+Decodes a sequence of bytes to a String using ascii encoding.
+
+### String/encode_utf8
+
+```python
+def String/encode_utf8(s: String, out: [u24]) -> [u24]
+```
+
+Encodes a String to a sequence of bytes using utf-8 encoding.
+
+### String/encode_ascii
+
+```python
+def String/encode_ascii(s: String) -> [u24]
+```
+
+Encodes a String to a sequence of bytes using ascii encoding.
+
+### Utf8/decode_rune
+
+```python
+def Utf8/decode_rune(bytes: [u24]) -> (rune: u24, length: u24, rest: [u24])
+```
+
+Decodes a utf-8 rune, returns a tuple containing the rune, rune length and the rest of the byte
+sequence.