feat: bytes type (#7122)

Co-authored-by: wingbot <[email protected]> Co-authored-by: monada-bot[bot] <[email protected]>
winglang · Sep 16, 2024 · 6b016b1 · 6b016b1
1 parent ae30eb6
commit 6b016b1
Show file tree

Hide file tree

Showing 38 changed files with 942 additions and 17 deletions.
diff --git a/docs/api/04-standard-library/fs/api-reference.md b/docs/api/04-standard-library/fs/api-reference.md
@@ -51,6 +51,7 @@ new fs.Util();
 | <code><a href="#@winglang/sdk.fs.Util.metadata">metadata</a></code> | Gets the stats of the given path. |
 | <code><a href="#@winglang/sdk.fs.Util.mkdir">mkdir</a></code> | Create a directory. |
 | <code><a href="#@winglang/sdk.fs.Util.mkdtemp">mkdtemp</a></code> | Create a temporary directory. |
+| <code><a href="#@winglang/sdk.fs.Util.readBytes">readBytes</a></code> | Read the contents of the file as bytes. |
 | <code><a href="#@winglang/sdk.fs.Util.readdir">readdir</a></code> | Read the contents of the directory. |
 | <code><a href="#@winglang/sdk.fs.Util.readFile">readFile</a></code> | Read the entire contents of a file. |
 | <code><a href="#@winglang/sdk.fs.Util.readJson">readJson</a></code> | Read the contents of the file and convert it to JSON. |
@@ -60,10 +61,12 @@ new fs.Util();
 | <code><a href="#@winglang/sdk.fs.Util.setPermissions">setPermissions</a></code> | Set the permissions of the file, directory, etc. |
 | <code><a href="#@winglang/sdk.fs.Util.symlink">symlink</a></code> | Creates a symbolic link. |
 | <code><a href="#@winglang/sdk.fs.Util.symlinkMetadata">symlinkMetadata</a></code> | Gets the stats of the given path without following symbolic links. |
+| <code><a href="#@winglang/sdk.fs.Util.tryReadBytes">tryReadBytes</a></code> | If the file exists, read the contents of the file as bytes; |
 | <code><a href="#@winglang/sdk.fs.Util.tryReaddir">tryReaddir</a></code> | If the path exists, read the contents of the directory; |
 | <code><a href="#@winglang/sdk.fs.Util.tryReadFile">tryReadFile</a></code> | If the file exists and can be read successfully, read the entire contents; |
 | <code><a href="#@winglang/sdk.fs.Util.tryReadJson">tryReadJson</a></code> | Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return `undefined`. |
 | <code><a href="#@winglang/sdk.fs.Util.tryReadYaml">tryReadYaml</a></code> | Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, `undefined` otherwise. |
+| <code><a href="#@winglang/sdk.fs.Util.writeBytes">writeBytes</a></code> | Write bytes to a file, replacing the file if it already exists. |
 | <code><a href="#@winglang/sdk.fs.Util.writeFile">writeFile</a></code> | Writes data to a file, replacing the file if it already exists. |
 | <code><a href="#@winglang/sdk.fs.Util.writeJson">writeJson</a></code> | Writes JSON to a file, replacing the file if it already exists. |
 | <code><a href="#@winglang/sdk.fs.Util.writeYaml">writeYaml</a></code> | Writes multiple YAML objects to a file, replacing the file if it already exists. |
@@ -356,6 +359,24 @@ The prefix for the directory to be created, default `wingtemp`.
 
 ---
 
+##### `readBytes` <a name="readBytes" id="@winglang/sdk.fs.Util.readBytes"></a>
+
+```wing
+bring fs;
+
+fs.readBytes(filepath: str);
+```
+
+Read the contents of the file as bytes.
+
+###### `filepath`<sup>Required</sup> <a name="filepath" id="@winglang/sdk.fs.Util.readBytes.parameter.filepath"></a>
+
+- *Type:* str
+
+The file path.
+
+---
+
 ##### `readdir` <a name="readdir" id="@winglang/sdk.fs.Util.readdir"></a>
 
 ```wing
@@ -572,6 +593,26 @@ The path to get stats for.
 
 ---
 
+##### `tryReadBytes` <a name="tryReadBytes" id="@winglang/sdk.fs.Util.tryReadBytes"></a>
+
+```wing
+bring fs;
+
+fs.tryReadBytes(filepath: str);
+```
+
+If the file exists, read the contents of the file as bytes;
+
+otherwise, return `undefined`.
+
+###### `filepath`<sup>Required</sup> <a name="filepath" id="@winglang/sdk.fs.Util.tryReadBytes.parameter.filepath"></a>
+
+- *Type:* str
+
+The file path.
+
+---
+
 ##### `tryReaddir` <a name="tryReaddir" id="@winglang/sdk.fs.Util.tryReaddir"></a>
 
 ```wing
@@ -656,6 +697,43 @@ The file path of the YAML file.
 
 ---
 
+##### `writeBytes` <a name="writeBytes" id="@winglang/sdk.fs.Util.writeBytes"></a>
+
+```wing
+bring fs;
+
+fs.writeBytes(filepath: str, data: Bytes, options?: WriteFileOptions);
+```
+
+Write bytes to a file, replacing the file if it already exists.
+
+###### `filepath`<sup>Required</sup> <a name="filepath" id="@winglang/sdk.fs.Util.writeBytes.parameter.filepath"></a>
+
+- *Type:* str
+
+The file path that needs to be written.
+
+---
+
+###### `data`<sup>Required</sup> <a name="data" id="@winglang/sdk.fs.Util.writeBytes.parameter.data"></a>
+
+- *Type:* <a href="#@winglang/sdk.std.Bytes">Bytes</a>
+
+The bytes to write.
+
+---
+
+###### `options`<sup>Optional</sup> <a name="options" id="@winglang/sdk.fs.Util.writeBytes.parameter.options"></a>
+
+- *Type:* <a href="#@winglang/sdk.fs.WriteFileOptions">WriteFileOptions</a>
+
+The `encoding` can be set to specify the character encoding.
+
+And the `flag` can be set to specify the attributes.
+If a flag is not provided, it defaults to `"w"`.
+
+---
+
 ##### `writeFile` <a name="writeFile" id="@winglang/sdk.fs.Util.writeFile"></a>
 
 ```wing

diff --git a/docs/api/04-standard-library/std/bytes.md b/docs/api/04-standard-library/std/bytes.md
@@ -0,0 +1,282 @@
+---
+title: bytes
+id: bytes
+---
+
+# API Reference <a name="API Reference" id="api-reference"></a>
+
+
+## Classes <a name="Classes" id="Classes"></a>
+
+### Bytes <a name="Bytes" id="@winglang/sdk.std.Bytes"></a>
+
+Immutable sequence of binary data.
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.std.Bytes.at">at</a></code> | Get the byte at the given index. |
+| <code><a href="#@winglang/sdk.std.Bytes.copy">copy</a></code> | Create a copy of the `bytes` value. |
+| <code><a href="#@winglang/sdk.std.Bytes.slice">slice</a></code> | Get the slice of the `bytes` value from the given start index to the given end index. |
+| <code><a href="#@winglang/sdk.std.Bytes.toBase64">toBase64</a></code> | Convert the `bytes` value to a base64 encoded string. |
+| <code><a href="#@winglang/sdk.std.Bytes.toHex">toHex</a></code> | Convert the `bytes` value to a hex encoded string. |
+| <code><a href="#@winglang/sdk.std.Bytes.toRaw">toRaw</a></code> | Convert the `bytes` value to an array of byte values. |
+| <code><a href="#@winglang/sdk.std.Bytes.tryAt">tryAt</a></code> | Get the byte at the given index, returning nil if the index is out of bounds. |
+
+---
+
+##### `at` <a name="at" id="@winglang/sdk.std.Bytes.at"></a>
+
+```wing
+at(index: num): num
+```
+
+Get the byte at the given index.
+
+###### `index`<sup>Required</sup> <a name="index" id="@winglang/sdk.std.Bytes.at.parameter.index"></a>
+
+- *Type:* num
+
+index of the value to get.
+
+---
+
+##### `copy` <a name="copy" id="@winglang/sdk.std.Bytes.copy"></a>
+
+```wing
+copy(): Bytes
+```
+
+Create a copy of the `bytes` value.
+
+##### `slice` <a name="slice" id="@winglang/sdk.std.Bytes.slice"></a>
+
+```wing
+slice(startIndex: num, endIndex?: num): Bytes
+```
+
+Get the slice of the `bytes` value from the given start index to the given end index.
+
+###### `startIndex`<sup>Required</sup> <a name="startIndex" id="@winglang/sdk.std.Bytes.slice.parameter.startIndex"></a>
+
+- *Type:* num
+
+index to start the slice.
+
+---
+
+###### `endIndex`<sup>Optional</sup> <a name="endIndex" id="@winglang/sdk.std.Bytes.slice.parameter.endIndex"></a>
+
+- *Type:* num
+
+index to end the slice.
+
+---
+
+##### `toBase64` <a name="toBase64" id="@winglang/sdk.std.Bytes.toBase64"></a>
+
+```wing
+toBase64(): str
+```
+
+Convert the `bytes` value to a base64 encoded string.
+
+##### `toHex` <a name="toHex" id="@winglang/sdk.std.Bytes.toHex"></a>
+
+```wing
+toHex(): str
+```
+
+Convert the `bytes` value to a hex encoded string.
+
+##### `toRaw` <a name="toRaw" id="@winglang/sdk.std.Bytes.toRaw"></a>
+
+```wing
+toRaw(): MutArray<num>
+```
+
+Convert the `bytes` value to an array of byte values.
+
+##### `tryAt` <a name="tryAt" id="@winglang/sdk.std.Bytes.tryAt"></a>
+
+```wing
+tryAt(index: num): num?
+```
+
+Get the byte at the given index, returning nil if the index is out of bounds.
+
+###### `index`<sup>Required</sup> <a name="index" id="@winglang/sdk.std.Bytes.tryAt.parameter.index"></a>
+
+- *Type:* num
+
+index of the value to get.
+
+---
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.std.Bytes.concat">concat</a></code> | Concatenate multiple `bytes` values. |
+| <code><a href="#@winglang/sdk.std.Bytes.fromBase64">fromBase64</a></code> | Create a new `bytes` value from a base64 encoded string. |
+| <code><a href="#@winglang/sdk.std.Bytes.fromHex">fromHex</a></code> | Create a new `bytes` value from a hex encoded string. |
+| <code><a href="#@winglang/sdk.std.Bytes.fromRaw">fromRaw</a></code> | Create a new `bytes` value from an array of byte values. |
+| <code><a href="#@winglang/sdk.std.Bytes.fromString">fromString</a></code> | Create a new `bytes` value from a string. |
+| <code><a href="#@winglang/sdk.std.Bytes.zeros">zeros</a></code> | Create a new `bytes` value with the given length, filled with zeros. |
+
+---
+
+##### `concat` <a name="concat" id="@winglang/sdk.std.Bytes.concat"></a>
+
+```wing
+Bytes.concat(...values: Array<Bytes>);
+```
+
+Concatenate multiple `bytes` values.
+
+###### `values`<sup>Required</sup> <a name="values" id="@winglang/sdk.std.Bytes.concat.parameter.values"></a>
+
+- *Type:* <a href="#@winglang/sdk.std.Bytes">Bytes</a>
+
+the `bytes` values to concatenate.
+
+---
+
+##### `fromBase64` <a name="fromBase64" id="@winglang/sdk.std.Bytes.fromBase64"></a>
+
+```wing
+Bytes.fromBase64(base64: str);
+```
+
+Create a new `bytes` value from a base64 encoded string.
+
+###### `base64`<sup>Required</sup> <a name="base64" id="@winglang/sdk.std.Bytes.fromBase64.parameter.base64"></a>
+
+- *Type:* str
+
+The base64 encoded string to create the `bytes` from.
+
+---
+
+##### `fromHex` <a name="fromHex" id="@winglang/sdk.std.Bytes.fromHex"></a>
+
+```wing
+Bytes.fromHex(hex: str);
+```
+
+Create a new `bytes` value from a hex encoded string.
+
+###### `hex`<sup>Required</sup> <a name="hex" id="@winglang/sdk.std.Bytes.fromHex.parameter.hex"></a>
+
+- *Type:* str
+
+The hex encoded string to create the `bytes` from.
+
+---
+
+##### `fromRaw` <a name="fromRaw" id="@winglang/sdk.std.Bytes.fromRaw"></a>
+
+```wing
+Bytes.fromRaw(values: MutArray<num>);
+```
+
+Create a new `bytes` value from an array of byte values.
+
+###### `values`<sup>Required</sup> <a name="values" id="@winglang/sdk.std.Bytes.fromRaw.parameter.values"></a>
+
+- *Type:* MutArray&lt;num&gt;
+
+The byte values to create the `bytes` from.
+
+---
+
+##### `fromString` <a name="fromString" id="@winglang/sdk.std.Bytes.fromString"></a>
+
+```wing
+Bytes.fromString(value: str);
+```
+
+Create a new `bytes` value from a string.
+
+###### `value`<sup>Required</sup> <a name="value" id="@winglang/sdk.std.Bytes.fromString.parameter.value"></a>
+
+- *Type:* str
+
+The string to create the `bytes` from.
+
+---
+
+##### `zeros` <a name="zeros" id="@winglang/sdk.std.Bytes.zeros"></a>
+
+```wing
+Bytes.zeros(length: num);
+```
+
+Create a new `bytes` value with the given length, filled with zeros.
+
+###### `length`<sup>Required</sup> <a name="length" id="@winglang/sdk.std.Bytes.zeros.parameter.length"></a>
+
+- *Type:* num
+
+The length of the new `bytes` value.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@winglang/sdk.std.Bytes.property.length">length</a></code> | <code>num</code> | The length of the bytes. |
+
+---
+
+##### `length`<sup>Required</sup> <a name="length" id="@winglang/sdk.std.Bytes.property.length"></a>
+
+```wing
+length: num;
+```
+
+- *Type:* num
+
+The length of the bytes.
+
+---
+
+
+## Structs <a name="Structs" id="Structs"></a>
+
+### BytesToStringOptions <a name="BytesToStringOptions" id="@winglang/sdk.std.BytesToStringOptions"></a>
+
+Options for converting a `bytes` value to a string.
+
+#### Initializer <a name="Initializer" id="@winglang/sdk.std.BytesToStringOptions.Initializer"></a>
+
+```wing
+let BytesToStringOptions = BytesToStringOptions{ ... };
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@winglang/sdk.std.BytesToStringOptions.property.encoding">encoding</a></code> | <code>str</code> | The encoding to use when converting the `bytes` value to a string. |
+
+---
+
+##### `encoding`<sup>Required</sup> <a name="encoding" id="@winglang/sdk.std.BytesToStringOptions.property.encoding"></a>
+
+```wing
+encoding: str;
+```
+
+- *Type:* str
+- *Default:* "utf-8"
+
+The encoding to use when converting the `bytes` value to a string.
+
+> [https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings)
+
+---
+
+