diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 18370635bb05..65baf8463a52 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -30,6 +30,7 @@ const ENTRY_POINTS = [ "../bytes/mod.ts", "../collections/mod.ts", "../datetime/mod.ts", + "../encoding/mod.ts", "../internal/mod.ts", "../jsonc/mod.ts", "../media_types/mod.ts", diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts index 18e33ef7a46a..2ce8c4f20a8d 100644 --- a/encoding/ascii85.ts +++ b/encoding/ascii85.ts @@ -51,11 +51,17 @@ const Z85 = /** * Converts data into an ascii58-encoded string. * - * @example + * @param data The data to encode. + * @param options Options for encoding. + * + * @returns The ascii85-encoded string. + * + * @example Usage * ```ts * import { encodeAscii85 } from "@std/encoding/ascii85"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeAscii85("Hello world!"); // "87cURD]j7BEbo80" + * assertEquals(encodeAscii85("Hello world!"), "87cURD]j7BEbo80"); * ``` */ export function encodeAscii85( @@ -130,12 +136,15 @@ export function encodeAscii85( * @param options Options for decoding. * @returns The decoded data. * - * @example + * @example Usage * ```ts * import { decodeAscii85 } from "@std/encoding/ascii85"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeAscii85("87cURD]j7BEbo80"); - * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ] + * assertEquals( + * decodeAscii85("87cURD]j7BEbo80"), + * new TextEncoder().encode("Hello world!"), + * ); * ``` */ export function decodeAscii85( diff --git a/encoding/base32.ts b/encoding/base32.ts index 20a46a671392..6b3604ff0708 100644 --- a/encoding/base32.ts +++ b/encoding/base32.ts @@ -13,10 +13,14 @@ * * ```ts * import { encodeBase32, decodeBase32 } from "@std/encoding/base32"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const encoded = encodeBase32("foobar"); // "MZXW6YTBOI======" + * assertEquals(encodeBase32("foobar"), "MZXW6YTBOI======"); * - * decodeBase32(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * assertEquals( + * decodeBase32("MZXW6YTBOI======"), + * new TextEncoder().encode("foobar") + * ); * ``` * * @module @@ -64,12 +68,15 @@ function _byteLength(validLen: number, placeHoldersLen: number): number { * @param b32 The base32-encoded string to decode. * @returns The decoded data. * - * @example + * @example Usage * ```ts * import { decodeBase32 } from "@std/encoding/base32"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeBase32("NRQMA==="); - * // Uint8Array(3) [ 108, 96, 192 ] + * assertEquals( + * decodeBase32("GZRTMMDDGA======"), + * new TextEncoder().encode("6c60c0"), + * ); * ``` */ export function decodeBase32(b32: string): Uint8Array { @@ -170,11 +177,12 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string { * @param data The data to encode. * @returns The base32-encoded string. * - * @example + * @example Usage * ```ts * import { encodeBase32 } from "@std/encoding/base32"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeBase32("6c60c0"); // "NRQMA===" + * assertEquals(encodeBase32("6c60c0"), "GZRTMMDDGA======"); * ``` */ export function encodeBase32(data: ArrayBuffer | Uint8Array | string): string { diff --git a/encoding/base58.ts b/encoding/base58.ts index 64d554bf4bc9..2571375996e0 100644 --- a/encoding/base58.ts +++ b/encoding/base58.ts @@ -10,11 +10,13 @@ * * ```ts * import { encodeBase58, decodeBase58 } from "@std/encoding/base58"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const encoded = encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U" + * const hello = new TextEncoder().encode("Hello World!"); * - * decodeBase58(encoded); - * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 ] + * assertEquals(encodeBase58(hello), "2NEpo7TZRRrLZSi2U"); + * + * assertEquals(decodeBase58("2NEpo7TZRRrLZSi2U"), hello); * ``` * * @module @@ -43,11 +45,12 @@ const base58alphabet = * @param data The data to encode. * @returns The base58-encoded string. * - * @example + * @example Usage * ```ts * import { encodeBase58 } from "@std/encoding/base58"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U" + * assertEquals(encodeBase58("Hello World!"), "2NEpo7TZRRrLZSi2U"); * ``` */ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string { @@ -108,12 +111,15 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string { * @param b58 The base58-encoded string to decode. * @returns The decoded data. * - * @example + * @example Usage * ```ts * import { decodeBase58 } from "@std/encoding/base58"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeBase58("2NEpo7TZRRrLZSi2U"); - * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 ] + * assertEquals( + * decodeBase58("2NEpo7TZRRrLZSi2U"), + * new TextEncoder().encode("Hello World!") + * ); * ``` */ export function decodeBase58(b58: string): Uint8Array { diff --git a/encoding/base64.ts b/encoding/base64.ts index 13b067ae0643..ed4e645fe0d0 100644 --- a/encoding/base64.ts +++ b/encoding/base64.ts @@ -13,10 +13,12 @@ * encodeBase64, * decodeBase64, * } from "@std/encoding/base64"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const encoded = encodeBase64("foobar"); // "Zm9vYmFy" + * const foobar = new TextEncoder().encode("foobar"); * - * decodeBase64(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * assertEquals(encodeBase64(foobar), "Zm9vYmFy"); + * assertEquals(decodeBase64("Zm9vYmFy"), foobar); * ``` * * @module @@ -99,11 +101,12 @@ const base64abc = [ * @param data The data to encode. * @returns The base64-encoded string. * - * @example + * @example Usage * ```ts * import { encodeBase64 } from "@std/encoding/base64"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeBase64("foobar"); // "Zm9vYmFy" + * assertEquals(encodeBase64("foobar"), "Zm9vYmFy"); * ``` */ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string { @@ -151,11 +154,15 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string { * @param b64 The base64-encoded string to decode. * @returns The decoded data. * - * @example + * @example Usage * ```ts * import { decodeBase64 } from "@std/encoding/base64"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeBase64("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * assertEquals( + * decodeBase64("Zm9vYmFy"), + * new TextEncoder().encode("foobar") + * ); * ``` */ export function decodeBase64(b64: string): Uint8Array { diff --git a/encoding/base64url.ts b/encoding/base64url.ts index 976681d224c7..8910270e61d9 100644 --- a/encoding/base64url.ts +++ b/encoding/base64url.ts @@ -52,11 +52,12 @@ function convertBase64ToBase64url(b64: string) { * @param data The data to encode. * @returns The base64url-encoded string. * - * @example + * @example Usage * ```ts * import { encodeBase64Url } from "@std/encoding/base64url"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeBase64Url("foobar"); // "Zm9vYmFy" + * assertEquals(encodeBase64Url("foobar"), "Zm9vYmFy"); * ``` */ export function encodeBase64Url( @@ -73,11 +74,15 @@ export function encodeBase64Url( * @param b64url The base64url-encoded string to decode. * @returns The decoded data. * - * @example + * @example Usage * ```ts * import { decodeBase64Url } from "@std/encoding/base64url"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeBase64Url("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ] + * assertEquals( + * decodeBase64Url("Zm9vYmFy"), + * new TextEncoder().encode("foobar") + * ); * ``` */ export function decodeBase64Url(b64url: string): Uint8Array { diff --git a/encoding/hex.ts b/encoding/hex.ts index 63129379eec5..b4469a0af793 100644 --- a/encoding/hex.ts +++ b/encoding/hex.ts @@ -15,10 +15,14 @@ * decodeHex, * encodeHex, * } from "@std/encoding/hex"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * const encoded = encodeHex("abc"); // "616263" + * assertEquals(encodeHex("abc"), "616263"); * - * decodeHex(encoded); // Uint8Array(3) [ 97, 98, 99 ] + * assertEquals( + * decodeHex("616263"), + * new TextEncoder().encode("abc"), + * ); * ``` * * @module @@ -53,11 +57,16 @@ function fromHexChar(byte: number): number { /** * Converts data into a hex-encoded string. * - * @example + * @param src The data to encode. + * + * @returns The hex-encoded string. + * + * @example Usage * ```ts * import { encodeHex } from "@std/encoding/hex"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * encodeHex("abc"); // "616263" + * assertEquals(encodeHex("abc"), "616263"); * ``` */ export function encodeHex(src: string | Uint8Array | ArrayBuffer): string { @@ -76,11 +85,19 @@ export function encodeHex(src: string | Uint8Array | ArrayBuffer): string { * Decodes the given hex-encoded string. If the input is malformed, an error is * thrown. * - * @example + * @param src The hex-encoded string to decode. + * + * @returns The decoded data. + * + * @example Usage * ```ts * import { decodeHex } from "@std/encoding/hex"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * decodeHex("616263"); // Uint8Array(3) [ 97, 98, 99 ] + * assertEquals( + * decodeHex("616263"), + * new TextEncoder().encode("abc"), + * ); * ``` */ export function decodeHex(src: string): Uint8Array { diff --git a/encoding/varint.ts b/encoding/varint.ts index 6a98470bcfb5..c4e39879d9d8 100644 --- a/encoding/varint.ts +++ b/encoding/varint.ts @@ -2,16 +2,24 @@ // Copyright 2020 Keith Cirkel. All rights reserved. MIT license. // Copyright 2023 Skye "MierenManz". All rights reserved. MIT license. /** - * Functions for encoding typed integers in array buffers. + * Utilities for {@link https://protobuf.dev/programming-guides/encoding/#varints VarInt} encoding + * of typed integers. VarInt encoding represents integers using a variable number of bytes, with + * smaller values requiring fewer bytes. * * ```ts - * import { encode, decode } from "@std/encoding/varint"; + * import { encodeVarint, decodeVarint } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array(10); - * const [encoded, bytesWritten] = encode(42n, buf); - * // [ Uint8Array(1) [ 42 ], 1 ]; - * - * decode(encoded); // [ 42n, 1 ]; + * assertEquals( + * encodeVarint(42n, buf), + * [new Uint8Array([42]), 1] + * ); + * + * assertEquals( + * decodeVarint(new Uint8Array([42])), + * [ 42n, 1 ] + * ); * ``` * * @module @@ -20,8 +28,19 @@ // This implementation is a port of https://deno.land/x/varint@v2.0.0 by @keithamus // This module is browser compatible. +/** + * The maximum value of an unsigned 64-bit integer. + * Equivalent to `2n**64n - 1n` + */ export const MaxUInt64 = 18446744073709551615n; + +/** + * The maximum length, in bytes, of a VarInt encoded 64-bit integer. + */ export const MaxVarIntLen64 = 10; +/** + * The maximum length, in bytes, of a VarInt encoded 32-bit integer. + */ export const MaxVarIntLen32 = 5; const MSB = 0x80; @@ -55,9 +74,10 @@ const U64_VIEW = new BigUint64Array(AB); * @example * ```ts * import { decode } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array([0x8E, 0x02]); - * decode(buf); // [ 300n, 2 ]; + * assertEquals(decode(buf), [ 300n, 2 ]); * ``` * * @deprecated This will be removed in 1.0.0. Use {@linkcode decodeVarint} @@ -84,12 +104,13 @@ export function decode(buf: Uint8Array, offset = 0): [bigint, number] { * @param offset The offset to start decoding from. * @returns A tuple of the decoded varint 64-bit number, and the new offset. * - * @example + * @example Usage * ```ts * import { decodeVarint } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array([0x8E, 0x02]); - * decodeVarint(buf); // [ 300n, 2 ]; + * assertEquals(decodeVarint(buf), [270n, 2]); * ``` */ export function decodeVarint(buf: Uint8Array, offset = 0): [bigint, number] { @@ -172,9 +193,10 @@ export function decodeVarint(buf: Uint8Array, offset = 0): [bigint, number] { * @example * ```ts * import { decode32 } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array([0x8E, 0x02]); - * decode32(buf); // [ 300, 2 ]; + * assertEquals(decode32(buf), [ 300, 2 ]); * ``` * * @deprecated This will be removed in 1.0.0. Use {@linkcode decodeVarint32} @@ -200,12 +222,13 @@ export function decode32(buf: Uint8Array, offset = 0): [number, number] { * @param offset The offset to start decoding from. * @returns A tuple of the decoded varint 32-bit number, and the new offset. * - * @example + * @example Usage * ```ts * import { decodeVarint32 } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array([0x8E, 0x02]); - * decodeVarint32(buf); // [ 300, 2 ]; + * assertEquals(decodeVarint32(buf), [270, 2]); * ``` */ export function decodeVarint32(buf: Uint8Array, offset = 0): [number, number] { @@ -244,9 +267,10 @@ export function decodeVarint32(buf: Uint8Array, offset = 0): [number, number] { * @example * ```ts * import { encode } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array(10); - * encode(42n, buf); // [ Uint8Array(1) [ 42 ], 1 ]; + * assertEquals(encode(42n, buf), [new Uint8Array([42]), 1]); * ``` * * @deprecated This will be removed in 1.0.0. Use {@linkcode encodeVarint} instead. @@ -277,12 +301,13 @@ export function encode( * @param offset The offset to start writing at. * @returns A tuple of the encoded VarInt `Uint8Array` and the new offset. * - * @example + * @example Usage * ```ts * import { encodeVarint } from "@std/encoding/varint"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const buf = new Uint8Array(10); - * encodeVarint(42n, buf); // [ Uint8Array(1) [ 42 ], 1 ]; + * assertEquals(encodeVarint(42n, buf), [new Uint8Array([42]), 1]); * ``` */ export function encodeVarint(