diff --git a/api_versioned_docs/version-latest/04-standard-library/fs/api-reference.md b/api_versioned_docs/version-latest/04-standard-library/fs/api-reference.md index 04ae4644..08cc8b22 100644 --- a/api_versioned_docs/version-latest/04-standard-library/fs/api-reference.md +++ b/api_versioned_docs/version-latest/04-standard-library/fs/api-reference.md @@ -51,6 +51,7 @@ new fs.Util(); | metadata | Gets the stats of the given path. | | mkdir | Create a directory. | | mkdtemp | Create a temporary directory. | +| readBytes | Read the contents of the file as bytes. | | readdir | Read the contents of the directory. | | readFile | Read the entire contents of a file. | | readJson | Read the contents of the file and convert it to JSON. | @@ -60,10 +61,12 @@ new fs.Util(); | setPermissions | Set the permissions of the file, directory, etc. | | symlink | Creates a symbolic link. | | symlinkMetadata | Gets the stats of the given path without following symbolic links. | +| tryReadBytes | If the file exists, read the contents of the file as bytes; | | tryReaddir | If the path exists, read the contents of the directory; | | tryReadFile | If the file exists and can be read successfully, read the entire contents; | | tryReadJson | Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return `undefined`. | | tryReadYaml | Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, `undefined` otherwise. | +| writeBytes | Write bytes to a file, replacing the file if it already exists. | | writeFile | Writes data to a file, replacing the file if it already exists. | | writeJson | Writes JSON to a file, replacing the file if it already exists. | | writeYaml | 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` + +```wing +bring fs; + +fs.readBytes(filepath: str); +``` + +Read the contents of the file as bytes. + +###### `filepath`Required + +- *Type:* str + +The file path. + +--- + ##### `readdir` ```wing @@ -572,6 +593,26 @@ The path to get stats for. --- +##### `tryReadBytes` + +```wing +bring fs; + +fs.tryReadBytes(filepath: str); +``` + +If the file exists, read the contents of the file as bytes; + +otherwise, return `undefined`. + +###### `filepath`Required + +- *Type:* str + +The file path. + +--- + ##### `tryReaddir` ```wing @@ -656,6 +697,43 @@ The file path of the YAML file. --- +##### `writeBytes` + +```wing +bring fs; + +fs.writeBytes(filepath: str, data: Bytes, options?: WriteFileOptions); +``` + +Write bytes to a file, replacing the file if it already exists. + +###### `filepath`Required + +- *Type:* str + +The file path that needs to be written. + +--- + +###### `data`Required + +- *Type:* Bytes + +The bytes to write. + +--- + +###### `options`Optional + +- *Type:* WriteFileOptions + +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` ```wing diff --git a/api_versioned_docs/version-latest/04-standard-library/std/bytes.md b/api_versioned_docs/version-latest/04-standard-library/std/bytes.md new file mode 100644 index 00000000..f583428b --- /dev/null +++ b/api_versioned_docs/version-latest/04-standard-library/std/bytes.md @@ -0,0 +1,282 @@ +--- +title: bytes +id: bytes +--- + +# API Reference + + +## Classes + +### Bytes + +Immutable sequence of binary data. + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| at | Get the byte at the given index. | +| copy | Create a copy of the `bytes` value. | +| slice | Get the slice of the `bytes` value from the given start index to the given end index. | +| toBase64 | Convert the `bytes` value to a base64 encoded string. | +| toHex | Convert the `bytes` value to a hex encoded string. | +| toRaw | Convert the `bytes` value to an array of byte values. | +| tryAt | Get the byte at the given index, returning nil if the index is out of bounds. | + +--- + +##### `at` + +```wing +at(index: num): num +``` + +Get the byte at the given index. + +###### `index`Required + +- *Type:* num + +index of the value to get. + +--- + +##### `copy` + +```wing +copy(): Bytes +``` + +Create a copy of the `bytes` value. + +##### `slice` + +```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`Required + +- *Type:* num + +index to start the slice. + +--- + +###### `endIndex`Optional + +- *Type:* num + +index to end the slice. + +--- + +##### `toBase64` + +```wing +toBase64(): str +``` + +Convert the `bytes` value to a base64 encoded string. + +##### `toHex` + +```wing +toHex(): str +``` + +Convert the `bytes` value to a hex encoded string. + +##### `toRaw` + +```wing +toRaw(): MutArray +``` + +Convert the `bytes` value to an array of byte values. + +##### `tryAt` + +```wing +tryAt(index: num): num? +``` + +Get the byte at the given index, returning nil if the index is out of bounds. + +###### `index`Required + +- *Type:* num + +index of the value to get. + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| concat | Concatenate multiple `bytes` values. | +| fromBase64 | Create a new `bytes` value from a base64 encoded string. | +| fromHex | Create a new `bytes` value from a hex encoded string. | +| fromRaw | Create a new `bytes` value from an array of byte values. | +| fromString | Create a new `bytes` value from a string. | +| zeros | Create a new `bytes` value with the given length, filled with zeros. | + +--- + +##### `concat` + +```wing +Bytes.concat(...values: Array); +``` + +Concatenate multiple `bytes` values. + +###### `values`Required + +- *Type:* Bytes + +the `bytes` values to concatenate. + +--- + +##### `fromBase64` + +```wing +Bytes.fromBase64(base64: str); +``` + +Create a new `bytes` value from a base64 encoded string. + +###### `base64`Required + +- *Type:* str + +The base64 encoded string to create the `bytes` from. + +--- + +##### `fromHex` + +```wing +Bytes.fromHex(hex: str); +``` + +Create a new `bytes` value from a hex encoded string. + +###### `hex`Required + +- *Type:* str + +The hex encoded string to create the `bytes` from. + +--- + +##### `fromRaw` + +```wing +Bytes.fromRaw(values: MutArray); +``` + +Create a new `bytes` value from an array of byte values. + +###### `values`Required + +- *Type:* MutArray<num> + +The byte values to create the `bytes` from. + +--- + +##### `fromString` + +```wing +Bytes.fromString(value: str); +``` + +Create a new `bytes` value from a string. + +###### `value`Required + +- *Type:* str + +The string to create the `bytes` from. + +--- + +##### `zeros` + +```wing +Bytes.zeros(length: num); +``` + +Create a new `bytes` value with the given length, filled with zeros. + +###### `length`Required + +- *Type:* num + +The length of the new `bytes` value. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| length | num | The length of the bytes. | + +--- + +##### `length`Required + +```wing +length: num; +``` + +- *Type:* num + +The length of the bytes. + +--- + + +## Structs + +### BytesToStringOptions + +Options for converting a `bytes` value to a string. + +#### Initializer + +```wing +let BytesToStringOptions = BytesToStringOptions{ ... }; +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| encoding | str | The encoding to use when converting the `bytes` value to a string. | + +--- + +##### `encoding`Required + +```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) + +--- + + diff --git a/api_versioned_docs/version-latest/05-language-reference.md b/api_versioned_docs/version-latest/05-language-reference.md index 236e9c05..6433997d 100644 --- a/api_versioned_docs/version-latest/05-language-reference.md +++ b/api_versioned_docs/version-latest/05-language-reference.md @@ -1233,14 +1233,14 @@ let rawData: bytes = bytes.fromRaw([104, 101, 108, 108, 111]); let rawString: bytes = bytes.fromString("hello"); let base64: bytes = bytes.fromBase64("aGVsbG8="); let hex: bytes = bytes.fromHex("68656c6c6f"); -let zeroes: bytes = bytes.alloc(20); // allocates 20 zeroed bytes +let zeros: bytes = bytes.zeros(20); // allocates 20 zeroed bytes // mutable initializers let rawDataMut: mutbytes = mutbytes.fromRaw([104, 101, 108, 108, 111]); let rawStringMut: mutbytes = mutbytes.fromString("hello"); let base64Mut: mutbytes = mutbytes.fromBase64("aGVsbG8="); let hexMut: mutbytes = mutbytes.fromHex("68656c6c6f"); -let zeroesMut: mutbytes = mutbytes.alloc(20); // allocates 20 zeroed bytes +let zerosMut: mutbytes = mutbytes.zeros(20); // allocates 20 zeroed bytes ``` #### Converting bytes to other types @@ -1262,7 +1262,7 @@ let asBytes: bytes = asMutBytes.copy(); #### Working with bytes ```TS -let concatenated: bytes = rawData.concat(rawData); +let concatenated: bytes = bytes.concat(rawData, rawData, rawData); let sliced: bytes = rawData.slice(1, 3); let length: num = rawData.length;