Skip to content

Commit

Permalink
feat: bytes type (#7122)
Browse files Browse the repository at this point in the history
Co-authored-by: wingbot <[email protected]>
Co-authored-by: monada-bot[bot] <[email protected]>
  • Loading branch information
3 people authored Sep 16, 2024
1 parent ae30eb6 commit 6b016b1
Show file tree
Hide file tree
Showing 38 changed files with 942 additions and 17 deletions.
78 changes: 78 additions & 0 deletions docs/api/04-standard-library/fs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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. |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
282 changes: 282 additions & 0 deletions docs/api/04-standard-library/std/bytes.md
Original file line number Diff line number Diff line change
@@ -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)
---


Loading

0 comments on commit 6b016b1

Please sign in to comment.