Deno/std
1
0
Fork 0
mirror of https://github.com/denoland/std.git synced 2024-11-21 20:50:22 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

chore: ensure code examples use assertions in Doc Linter (#4911)

Browse Source
This commit is contained in:
Asher Gomez 2024-06-03 14:10:27 +10:00 committed by GitHub
parent 8b24cc7a40
commit 31b906db99
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
74 changed files with 716 additions and 456 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
_tools/check_docs.ts
View File

@ -61,6 +61,7 @@ const ENTRY_POINTS = [
] as const;
const TS_SNIPPET = /```ts[\s\S]*?```/g;
const ASSERTION_IMPORT = /import \{.*\} from "@std\/assert(?:\/.*)?";/gm;
const NEWLINE = "\n";
const diagnostics: DocumentError[] = [];
const snippetPromises: Promise<void>[] = [];
@ -198,9 +199,17 @@ function assertSnippetsWork(
}
}
for (let snippet of snippets) {
if (snippet.split(NEWLINE)[0]?.includes("no-eval")) continue;
const delim = snippet.split(NEWLINE)[0];
if (delim?.includes("no-eval")) continue;
// Trim the code block delimiters
snippet = snippet.split(NEWLINE).slice(1, -1).join(NEWLINE);
if (!delim?.includes("no-assert")) {
assert(
snippet.match(ASSERTION_IMPORT) !== null,
"Snippet must contain assertion from '@std/assert'",
document,
);
}
snippetPromises.push(assertSnippetEvals(snippet, document));
}
}

3
async/deadline.ts
View File

@ -13,8 +13,9 @@ export interface DeadlineOptions {
* Error thrown when {@linkcode deadline} times out.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { DeadlineError } from "@std/async/deadline";
*
* const error = new DeadlineError();
* ```
*/

4
async/delay.ts
View File

@ -19,7 +19,7 @@ export interface DelayOptions {
* @param options Additional options.
*
* @example Basic usage
* ```ts
* ```ts no-assert
* import { delay } from "@std/async/delay";
*
* // ...
@ -33,7 +33,7 @@ export interface DelayOptions {
* Setting `persistent` to `false` will allow the process to continue to run as
* long as the timer exists.
*
* ```ts
* ```ts no-assert
* import { delay } from "@std/async/delay";
*
* // ...

2
async/mod.ts
View File

@ -5,7 +5,7 @@
* Provide help with asynchronous tasks like delays, debouncing, deferring, or
* pooling.
*
* ```ts
* ```ts no-assert
* import { delay } from "@std/async/delay";
*
* await delay(100); // waits for 100 milliseconds

28
async/mux_async_iterator.ts
View File

@ -15,6 +15,7 @@ interface TaggedYieldedValue<T> {
* @example Usage
* ```ts
* import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
* import { assertEquals } from "@std/assert/assert-equals";
*
* async function* gen123(): AsyncIterableIterator<number> {
* yield 1;
@ -31,10 +32,10 @@ interface TaggedYieldedValue<T> {
* const mux = new MuxAsyncIterator<number>();
* mux.add(gen123());
* mux.add(gen456());
* for await (const value of mux) {
* // ...
* }
* // ...
*
* const result = await Array.fromAsync(mux);
*
* assertEquals(result, [1, 4, 2, 5, 3, 6]);
* ```
*
* @typeParam T The type of the provided async iterables and generated async iterable.
@ -54,6 +55,7 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
* @example Usage
* ```ts
* import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
* import { assertEquals } from "@std/assert/assert-equals";
*
* async function* gen123(): AsyncIterableIterator<number> {
* yield 1;
@ -63,6 +65,10 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
*
* const mux = new MuxAsyncIterator<number>();
* mux.add(gen123());
*
* const result = await Array.fromAsync(mux.iterate());
*
* assertEquals(result, [1, 2, 3]);
* ```
*/
add(iterable: AsyncIterable<T>) {
@ -93,6 +99,7 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
* @example Usage
* ```ts
* import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
* import { assertEquals } from "@std/assert/assert-equals";
*
* async function* gen123(): AsyncIterableIterator<number> {
* yield 1;
@ -103,9 +110,9 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
* const mux = new MuxAsyncIterator<number>();
* mux.add(gen123());
*
* for await (const value of mux) {
* // ...
* }
* const result = await Array.fromAsync(mux.iterate());
*
* assertEquals(result, [1, 2, 3]);
* ```
*/
async *iterate(): AsyncIterableIterator<T> {
@ -137,6 +144,7 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
* @example Usage
* ```ts
* import { MuxAsyncIterator } from "@std/async/mux-async-iterator";
* import { assertEquals } from "@std/assert/assert-equals";
*
* async function* gen123(): AsyncIterableIterator<number> {
* yield 1;
@ -147,9 +155,9 @@ export class MuxAsyncIterator<T> implements AsyncIterable<T> {
* const mux = new MuxAsyncIterator<number>();
* mux.add(gen123());
*
* for await (const value of mux) {
* // ...
* }
* const result = await Array.fromAsync(mux);
*
* assertEquals(result, [1, 2, 3]);
* ```
*/
[Symbol.asyncIterator](): AsyncIterator<T> {

5
async/pool.ts
View File

@ -17,6 +17,7 @@ export const ERROR_WHILE_MAPPING_MESSAGE = "Threw while mapping.";
* @example Usage
* ```ts
* import { pooledMap } from "@std/async/pool";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const results = pooledMap(
* 2,
@ -24,9 +25,7 @@ export const ERROR_WHILE_MAPPING_MESSAGE = "Threw while mapping.";
* (i) => new Promise((r) => setTimeout(() => r(i), 1000)),
* );
*
* for await (const value of results) {
* // ...
* }
* assertEquals(await Array.fromAsync(results), [1, 2, 3]);
* ```
*
* @typeParam T the input type.

12
async/retry.ts
View File

@ -9,10 +9,10 @@ import { exponentialBackoffWithJitter } from "./_util.ts";
* has been reached.
*
* @example Usage
* ```ts
* ```ts no-assert no-eval
* import { RetryError } from "@std/async/retry";
*
* const error = new RetryError({ foo: "bar" }, 3);
* throw new RetryError({ foo: "bar" }, 3);
* ```
*/
export class RetryError extends Error {
@ -23,10 +23,10 @@ export class RetryError extends Error {
* @param attempts the number of retry attempts made.
*
* @example Usage
* ```ts
* ```ts no-assert no-eval
* import { RetryError } from "@std/async/retry";
*
* const error = new RetryError({ foo: "bar" }, 3);
* throw new RetryError({ foo: "bar" }, 3);
* ```
*/
constructor(cause: unknown, attempts: number) {
@ -95,7 +95,7 @@ const defaultRetryOptions: Required<RetryOptions> = {
* When `jitter` is `0`, waits the full backoff time.
*
* @example Example configuration 1
* ```ts
* ```ts no-assert
* import { retry } from "@std/async/retry";
* const req = async () => {
* // some function that throws sometimes
@ -112,7 +112,7 @@ const defaultRetryOptions: Required<RetryOptions> = {
* ```
*
* @example Example configuration 2
* ```ts
* ```ts no-assert
* import { retry } from "@std/async/retry";
* const req = async () => {
* // some function that throws sometimes

11
async/tee.ts
View File

@ -54,6 +54,7 @@ class Queue<T> {
* @example Usage
* ```ts
* import { tee } from "@std/async/tee";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const gen = async function* gen() {
* yield 1;
@ -63,13 +64,11 @@ class Queue<T> {
*
* const [branch1, branch2] = tee(gen());
*
* for await (const n of branch1) {
* console.log(n); // => 1, 2, 3
* }
* const result1 = await Array.fromAsync(branch1);
* assertEquals(result1, [1, 2, 3]);
*
* for await (const n of branch2) {
* console.log(n); // => 1, 2, 3
* }
* const result2 = await Array.fromAsync(branch2);
* assertEquals(result2, [1, 2, 3]);
* ```
*
* @typeParam T The type of the provided async iterable and the returned async iterables.

2
bytes/concat.ts
View File

@ -10,7 +10,7 @@
* @example Basic usage
* ```ts
* import { concat } from "@std/bytes/concat";
* import { assertEquals } from "@std/assert/assert-equals"
* import { assertEquals } from "@std/assert/assert-equals";
*
* const a = new Uint8Array([0, 1, 2]);
* const b = new Uint8Array([3, 4, 5]);

14
cli/parse_args.ts
View File

@ -451,14 +451,14 @@ const FLAG_REGEXP =
* @example Usage
* ```ts
* import { parseArgs } from "@std/cli/parse-args";
* const parsedArgs = parseArgs(Deno.args);
* ```
* import { assertEquals } from "@std/assert/assert-equals";
*
* @example Usage
* ```ts
* import { parseArgs } from "@std/cli/parse-args";
* const parsedArgs = parseArgs(["--foo", "--bar=baz", "./quux.txt"]);
* // parsedArgs: { foo: true, bar: "baz", _: ["./quux.txt"] }
* // For proper use, one should use `parseArgs(Deno.args)`
* assertEquals(parseArgs(["--foo", "--bar=baz", "./quux.txt"]), {
* foo: true,
* bar: "baz",
* _: ["./quux.txt"],
* });
* ```
*/
export function parseArgs<

7
cli/spinner.ts
View File

@ -121,7 +121,7 @@ export class Spinner {
* Creates a new spinner.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { Spinner } from "@std/cli/spinner";
*
* const spinner = new Spinner({ message: "Loading..." });
@ -169,11 +169,12 @@ export class Spinner {
* Get the current color of the spinner.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { Spinner } from "@std/cli/spinner";
*
* const spinner = new Spinner({ message: "Loading", color: "blue" });
* console.log(spinner.color); // "blue"
*
* spinner.color; // Blue ANSI escape sequence
* ```
* @returns The color of the spinner or `undefined` if it's using the terminal default.
*/

14
cli/unicode_width.ts
View File

@ -54,20 +54,22 @@ function charWidth(ch: string) {
* @example Calculating the unicode width of a string
* ```ts
* import { unicodeWidth } from "@std/cli/unicode-width";
* import { assertEquals } from "@std/assert/assert-equals";
*
* unicodeWidth("hello world"); // 11
* unicodeWidth("天地玄黃宇宙洪荒"); // 16
* unicodeWidth("ｆｕｌｌｗｉｄｔｈ"); // 18
* assertEquals(unicodeWidth("hello world"), 11);
* assertEquals(unicodeWidth("天地玄黃宇宙洪荒"), 16);
* assertEquals(unicodeWidth("ｆｕｌｌｗｉｄｔｈ"), 18);
* ```
*
* @example Calculating the unicode width of a color-encoded string
* ```ts
* import { unicodeWidth } from "@std/cli/unicode-width";
* import { stripAnsiCode } from "@std/fmt/colors";
* import { assertEquals } from "@std/assert/assert-equals";
*
* unicodeWidth(stripAnsiCode("\x1b[36mголубой\x1b[39m")); // 7
* unicodeWidth(stripAnsiCode("\x1b[31m紅色\x1b[39m")); // 4
* unicodeWidth(stripAnsiCode("\x1B]8;;https://deno.land\x07🦕\x1B]8;;\x07")); // 2
* assertEquals(unicodeWidth(stripAnsiCode("\x1b[36mголубой\x1b[39m")), 7);
* assertEquals(unicodeWidth(stripAnsiCode("\x1b[31m紅色\x1b[39m")), 4);
* assertEquals(unicodeWidth(stripAnsiCode("\x1B]8;;https://deno.land\x07🦕\x1B]8;;\x07")), 2);
* ```
*
* Use

7
collections/sort_by.ts
View File

@ -77,6 +77,7 @@ export function sortBy<T>(
* @example Usage
* ```ts
* import { sortBy } from "@std/collections/sort-by";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const people = [
* { name: "Anna" },
@ -84,6 +85,12 @@ export function sortBy<T>(
* { name: "John" },
* ];
* const sortedByName = sortBy(people, (it) => it.name);
*
* assertEquals(sortedByName, [
* { name: "Anna" },
* { name: "John" },
* { name: "Kim" },
* ]);
* ```
*/
export function sortBy<T>(

2
crypto/mod.ts
View File

@ -7,7 +7,7 @@
* supporting additional encryption APIs, but also delegating to the built-in
* APIs when possible.
*
* ```ts
* ```ts no-assert
* import { crypto } from "@std/crypto/crypto";
*
* const message = "Hello, Deno!";

86
data_structures/binary_heap.ts
View File

@ -67,14 +67,16 @@ export class BinaryHeap<T> implements Iterable<T> {
* Construct an empty binary heap.
*
* @example Creating an empty binary heap
* ```ts
* ```ts no-assert
* import { BinaryHeap } from "@std/data-structures";
*
* const heap = new BinaryHeap<number>();
* ```
*
* @example Creating a binary heap with a custom comparison function
* ```ts
* ```ts no-assert
* import { BinaryHeap, ascend } from "@std/data-structures";
*
* const heap = new BinaryHeap(ascend);
* ```
*
@ -95,8 +97,11 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Getting the underlying array
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* heap.toArray(); // [ 5, 4, 3, 1, 2 ]
*
* assertEquals(heap.toArray(), [ 5, 4, 3, 1, 2 ]);
* ```
*
* @returns An array containing the values in the binary heap.
@ -115,27 +120,31 @@ export class BinaryHeap<T> implements Iterable<T> {
* function is copied from the input heap.
*
* @example Creating a binary heap from an array like
* ```ts
* ```ts no-assert
* import { BinaryHeap } from "@std/data-structures";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* ```
*
* @example Creating a binary heap from an iterable object
* ```ts
* ```ts no-assert
* import { BinaryHeap } from "@std/data-structures";
*
* const heap = BinaryHeap.from((function*() { yield* [4, 1, 3, 5, 2]; })());
* ```
*
* @example Creating a binary heap from an existing binary heap
* ```ts
* ```ts no-assert
* import { BinaryHeap } from "@std/data-structures";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* const copy = BinaryHeap.from(heap);
* ```
*
* @example Creating a binary heap from an array like with a custom comparison function
* ```ts
* ```ts no-assert
* import { BinaryHeap, ascend } from "@std/data-structures";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2], { compare: ascend });
* ```
*
@ -164,8 +173,9 @@ export class BinaryHeap<T> implements Iterable<T> {
* sort the values in the heap after mapping the values.
*
* @example Creating a binary heap from an array like with a custom mapping function
* ```ts
* ```ts no-eval
* import { BinaryHeap } from "@std/data-structures";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2], { map: (value) => value * 2 });
* ```
*
@ -224,8 +234,11 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Getting the length of the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* heap.length; // 5
*
* assertEquals(heap.length, 5);
* ```
*
* @returns The count of values stored in the binary heap.
@ -243,15 +256,21 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Getting the greatest value from the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* heap.peek(); // 5
*
* assertEquals(heap.peek(), 5);
* ```
*
* @example Getting the greatest value from an empty binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = new BinaryHeap<number>();
* heap.peek(); // undefined
*
* assertEquals(heap.peek(), undefined);
* ```
*
* @returns The greatest value from the binary heap, or undefined if it is empty.
@ -267,9 +286,12 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Removing the greatest value from the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* heap.pop(); // 5
* [...heap]; // [ 4, 3, 2, 1 ]
*
* assertEquals(heap.pop(), 5);
* assertEquals([...heap], [4, 3, 2, 1]);
* ```
*
* The complexity of this operation is on average and worst case O(log n),
@ -278,8 +300,11 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Removing the greatest value from an empty binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = new BinaryHeap<number>();
* heap.pop(); // undefined
*
* assertEquals(heap.pop(), undefined);
* ```
*
* @returns The greatest value from the binary heap, or undefined if the heap is empty.
@ -317,9 +342,12 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Adding values to the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 2]);
* heap.push(5);
* [...heap]; // [ 5, 4, 3, 1, 2 ]
*
* assertEquals([...heap], [5, 4, 3, 2, 1]);
* ```
*
* @param values The values to add to the binary heap.
@ -348,9 +376,12 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Clearing the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* heap.clear();
* [...heap]; // []
*
* assertEquals([...heap], []);
* ```
*/
clear() {
@ -363,10 +394,15 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Checking if the binary heap is empty
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = new BinaryHeap<number>();
* heap.isEmpty(); // true
*
* assertEquals(heap.isEmpty(), true);
*
* heap.push(42);
* heap.isEmpty(); // false
*
* assertEquals(heap.isEmpty(), false);
* ```
*
* @returns true if the binary heap is empty, otherwise false.
@ -385,9 +421,12 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Draining the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* [...heap.drain()]; // [ 5, 4, 3, 2, 1 ]
* [...heap.drain()]; // []
*
* assertEquals([...heap.drain()], [ 5, 4, 3, 2, 1 ]);
* assertEquals([...heap.drain()], []);
* ```
*
* @returns An iterator for retrieving and removing values from the binary heap.
@ -407,9 +446,12 @@ export class BinaryHeap<T> implements Iterable<T> {
* @example Getting an iterator for the binary heap
* ```ts
* import { BinaryHeap } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const heap = BinaryHeap.from([4, 1, 3, 5, 2]);
* [...heap]; // [ 5, 4, 3, 2, 1 ]
* [...heap]; // []
*
* assertEquals([...heap], [ 5, 4, 3, 2, 1 ]);
* assertEquals([...heap], []);
* ```
*
* @returns An iterator for retrieving and removing values from the binary heap.

101
data_structures/binary_search_tree.ts
View File

@ -99,13 +99,14 @@ export class BinarySearchTree<T> implements Iterable<T> {
* Construct an empty binary search tree.
*
* @example Creating an empty binary search tree
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
*
* const tree = new BinarySearchTree<number>();
* ```
*
* @example Creating a binary search tree with a custom comparison function
* ```ts
* ```ts no-assert
* import { BinarySearchTree, ascend } from "@std/data-structures";
*
* const tree = new BinarySearchTree<{ price: number, name: string }>(
@ -167,14 +168,16 @@ export class BinarySearchTree<T> implements Iterable<T> {
* function is copied from the input tree.
*
* @example Creating a binary search tree from an array like
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* ```
*
* @example Creating a binary search tree from an iterable object
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
*
* const tree = BinarySearchTree.from<number>((function*() {
* yield 42;
* yield 43;
@ -183,15 +186,17 @@ export class BinarySearchTree<T> implements Iterable<T> {
* ```
*
* @example Creating a binary search tree from an existing binary search tree
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* const copy = BinarySearchTree.from(tree);
* ```
*
* @example Creating a binary search tree from an array like with a custom comparison function
* ```ts
* ```ts no-assert
* import { BinarySearchTree, descend } from "@std/data-structures";
*
* const tree = BinarySearchTree.from<number>(
* [42, 43, 41],
* { compare: descend }
@ -225,8 +230,9 @@ export class BinarySearchTree<T> implements Iterable<T> {
* the values.
*
* @example Creating a binary search tree from an array like with a custom mapping function
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
*
* const tree = BinarySearchTree.from<number, string>(
* [42, 43, 41],
* { map: (value) => value.toString() }
@ -311,10 +317,13 @@ export class BinarySearchTree<T> implements Iterable<T> {
* The complexity of this operation is O(1).
*
* @example Getting the size of the tree
* ```ts
* ```ts no-assert
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* tree.size; // 3
*
* assertEquals(tree.size, 3);
* ```
*
* @returns The count of values stored in the binary search tree.
@ -427,9 +436,12 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Inserting values into the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = new BinarySearchTree<number>();
* tree.insert(42); // true
* tree.insert(42); // false
*
* assertEquals(tree.insert(42), true);
* assertEquals(tree.insert(42), false);
* ```
*
* @param value The value to insert into the binary search tree.
@ -448,9 +460,12 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Removing values from the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42]);
* tree.remove(42); // true
* tree.remove(42); // false
*
* assertEquals(tree.remove(42), true);
* assertEquals(tree.remove(42), false);
* ```
*
* @param value The value to remove from the binary search tree.
@ -471,9 +486,12 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Finding values in the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42]);
* tree.find(42); // 42
* tree.find(43); // null
*
* assertEquals(tree.find(42), 42);
* assertEquals(tree.find(43), null);
* ```
*
* @param value The value to search for in the binary search tree.
@ -493,8 +511,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Finding the minimum value in the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* tree.min(); // 41
*
* assertEquals(tree.min(), 41);
* ```
*
* @returns The minimum value in the binary search tree, or null if the tree is empty.
@ -513,8 +534,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Finding the maximum value in the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* tree.max(); // 43
*
* assertEquals(tree.max(), 43);
* ```
*
* @returns The maximum value in the binary search tree, or null if the tree is empty.
@ -531,10 +555,13 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Clearing the tree
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from<number>([42, 43, 41]);
* tree.clear();
* tree.size; // 0
* tree.find(42); // null
*
* assertEquals(tree.size, 0);
* assertEquals(tree.find(42), null);
* ```
*/
clear() {
@ -550,10 +577,15 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Checking if the tree is empty
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = new BinarySearchTree<number>();
* tree.isEmpty(); // true
*
* assertEquals(tree.isEmpty(), true);
*
* tree.insert(42);
* tree.isEmpty(); // false
*
* assertEquals(tree.isEmpty(), false);
* ```
*
* @returns `true` if the binary search tree is empty, `false` otherwise.
@ -569,8 +601,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the in-order LNR iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree.lnrValues()] // 1, 2, 3, 4, 5
*
* assertEquals([...tree.lnrValues()], [1, 2, 3, 4, 5]);
* ```
*
* @returns An iterator that traverses the tree in-order (LNR).
@ -597,6 +632,8 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the reverse in-order RNL iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree.rnlValues()] // 5, 4, 3, 2, 1
* ```
@ -625,8 +662,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the pre-order NLR iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree.nlrValues()] // 4, 1, 2, 3, 5
*
* assertEquals([...tree.nlrValues()], [4, 1, 2, 3, 5]);
* ```
*
* @returns An iterator that traverses the tree in pre-order (NLR).
@ -649,8 +689,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the post-order LRN iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree.lrnValues()] // 3, 2, 1, 5, 4
*
* assertEquals([...tree.lrnValues()], [3, 2, 1, 5, 4]);
* ```
*
* @returns An iterator that traverses the tree in post-order (LRN).
@ -682,8 +725,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the level-order BFS iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree.lvlValues()] // 4, 1, 5, 2, 3
*
* assertEquals([...tree.lvlValues()], [4, 1, 5, 2, 3]);
* ```
*
* @returns An iterator that traverses the tree in level-order (BFS).
@ -706,8 +752,11 @@ export class BinarySearchTree<T> implements Iterable<T> {
* @example Using the in-order iterator
* ```ts
* import { BinarySearchTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = BinarySearchTree.from([4, 1, 2, 5, 3]);
* [...tree] // 1, 2, 3, 4, 5
*
* assertEquals([...tree], [1, 2, 3, 4, 5]);
* ```
*
* See {@link BinarySearchTree#lnrValues}.

16
data_structures/comparators.ts
View File

@ -8,9 +8,11 @@
* @example Comparing numbers
* ```ts
* import { ascend } from "@std/data-structures";
* ascend(1, 2); // -1
* ascend(2, 1); // 1
* ascend(1, 1); // 0
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(ascend(1, 2), -1);
* assertEquals(ascend(2, 1), 1);
* assertEquals(ascend(1, 1), 0);
* ```
*
* @typeparam T The type of the values being compared.
@ -29,9 +31,11 @@ export function ascend<T>(a: T, b: T): -1 | 0 | 1 {
* @example Comparing numbers
* ```ts
* import { descend } from "@std/data-structures";
* descend(1, 2); // 1
* descend(2, 1); // -1
* descend(1, 1); // 0
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(descend(1, 2), 1);
* assertEquals(descend(2, 1), -1);
* assertEquals(descend(1, 1), 0);
* ```
*
* @typeparam T The type of the values being compared.

35
data_structures/red_black_tree.ts
View File

@ -105,14 +105,16 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* Construct an empty red-black tree.
*
* @example Creating an empty red-black tree
* ```ts
* ```ts no-assert
* import { RedBlackTree } from "@std/data-structures";
*
* const tree = new RedBlackTree<number>();
* ```
*
* @example Creating a red-black tree with a custom comparison function
* ```ts
* ```ts no-assert
* import { RedBlackTree, ascend } from "@std/data-structures";
*
* const tree = new RedBlackTree<{ price: number, name: string }>(
* (a, b) => ascend(a.price, b.price) || ascend(a.name, b.name)
* );
@ -139,14 +141,16 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* function is copied from the input tree.
*
* @example Creating a red-black tree from an array like
* ```ts
* ```ts no-assert
* import { RedBlackTree } from "@std/data-structures";
*
* const tree = RedBlackTree.from<number>([3, 10, 13, 4, 6, 7, 1, 14]);
* ```
*
* @example Creating a red-black tree from an iterable object
* ```ts
* ```ts no-assert
* import { RedBlackTree } from "@std/data-structures";
*
* const tree = RedBlackTree.from<number>((function*() {
* yield 3;
* yield 10;
@ -155,15 +159,17 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* ```
*
* @example Creating a red-black tree from an existing red-black tree
* ```ts
* ```ts no-assert
* import { RedBlackTree } from "@std/data-structures";
*
* const tree = RedBlackTree.from<number>([3, 10, 13, 4, 6, 7, 1, 14]);
* const copy = RedBlackTree.from(tree);
* ```
*
* @example Creating a red-black tree from an array like with a custom comparison function
* ```ts
* ```ts no-assert
* import { RedBlackTree, descend } from "@std/data-structures";
*
* const tree = RedBlackTree.from<number>([3, 10, 13, 4, 6, 7, 1, 14], {
* compare: descend,
* });
@ -196,8 +202,9 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* the values.
*
* @example Creating a red-black tree from an array like with a custom mapping function
* ```ts
* ```ts no-assert
* import { RedBlackTree } from "@std/data-structures";
*
* const tree = RedBlackTree.from<number, string>([3, 10, 13, 4, 6, 7, 1, 14], {
* map: (value) => value.toString(),
* });
@ -324,9 +331,12 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* @example Inserting a value into the tree
* ```ts
* import { RedBlackTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = new RedBlackTree<number>();
* tree.insert(42); // true
* tree.insert(42); // false
*
* assertEquals(tree.insert(42), true);
* assertEquals(tree.insert(42), false);
* ```
*
* @param value The value to insert into the tree.
@ -378,9 +388,12 @@ export class RedBlackTree<T> extends BinarySearchTree<T> {
* @example Removing values from the tree
* ```ts
* import { RedBlackTree } from "@std/data-structures";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const tree = RedBlackTree.from<number>([42]);
* tree.remove(42); // true
* tree.remove(42); // false
*
* assertEquals(tree.remove(42), true);
* assertEquals(tree.remove(42), false);
* ```
*
* @param value The value to remove from the tree.

6
datetime/day_of_year.ts
View File

@ -12,8 +12,9 @@ import { DAY } from "./constants.ts";
* @example Basic usage
* ```ts
* import { dayOfYear } from "@std/datetime/day-of-year";
* import { assertEquals } from "@std/assert/assert-equals";
*
* dayOfYear(new Date("2019-03-11T03:24:00")); // 70
* assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70);
* ```
*/
export function dayOfYear(date: Date): number {
@ -38,8 +39,9 @@ export function dayOfYear(date: Date): number {
* @example Usage
* ```ts
* import { dayOfYearUtc } from "@std/datetime/day-of-year";
* import { assertEquals } from "@std/assert/assert-equals";
*
* dayOfYearUtc(new Date("2019-03-11T03:24:00.000Z")) // 70
* assertEquals(dayOfYearUtc(new Date("2019-03-11T03:24:00.000Z")), 70);
* ```
*/
export function dayOfYearUtc(date: Date): number {

38
datetime/difference.ts
View File

@ -50,35 +50,43 @@ function calculateMonthsDifference(from: Date, to: Date): number {
* @example Basic usage
* ```ts
* import { difference } from "@std/datetime/difference";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const date0 = new Date("2018-05-14");
* const date1 = new Date("2020-05-13");
*
* difference(date0, date1);
* // {
* // milliseconds: 63072000000,
* // seconds: 63072000,
* // minutes: 1051200,
* // hours: 17520,
* // days: 730,
* // weeks: 104,
* // months: 23,
* // quarters: 7,
* // years: 1
* // }
* assertEquals(difference(date0, date1), {
* milliseconds: 63072000000,
* seconds: 63072000,
* minutes: 1051200,
* hours: 17520,
* days: 730,
* weeks: 104,
* months: 23,
* quarters: 7,
* years: 1
* });
* ```
*
* @example Calculate difference in specific units
*
* The `units` option defines which units to calculate the difference in.
*
* ```ts
* import { difference } from "@std/datetime/difference";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const date0 = new Date("2018-05-14");
* const date1 = new Date("2020-05-13");
*
* difference(date0, date1, { units: ["days", "months", "years"] });
* // { days: 730, months: 23, years: 1 }
* const result = difference(date0, date1, { units: ["days", "months", "years"] });
*
* assertEquals(result, {
* days: 730,
* months: 23,
* years: 1
* });
* ```
* The `units` option defines which units to calculate the difference in.
*/
export function difference(
from: Date,

18
datetime/format.ts
View File

@ -42,27 +42,31 @@ export interface FormatOptions {
* @return The formatted date string.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { format } from "@std/datetime/format";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const date = new Date(2019, 0, 20, 16, 34, 23, 123);
*
* format(date, "dd-MM-yyyy"); // "20-01-2019"
* assertEquals(format(date, "dd-MM-yyyy"), "20-01-2019");
*
* format(date, "MM-dd-yyyy HH:mm:ss.SSS"); // "01-20-2019 16:34:23.123"
* assertEquals(format(date, "MM-dd-yyyy HH:mm:ss.SSS"), "01-20-2019 16:34:23.123");
*
* format(date, "'today:' yyyy-MM-dd"); // "today: 2019-01-20"
* assertEquals(format(date, "'today:' yyyy-MM-dd"), "today: 2019-01-20");
* ```
*
* @example UTC formatting
* ```ts
*
* Enable UTC formatting by setting the `utc` option to `true`.
*
* ```ts no-eval
* import { format } from "@std/datetime/format";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const date = new Date(2019, 0, 20, 16, 34, 23, 123);
*
* format(date, "yyyy-MM-dd HH:mm:ss", { utc: true }); // "2019-01-20 05:34:23"
* assertEquals(format(date, "yyyy-MM-dd HH:mm:ss", { utc: true }), "2019-01-20 05:34:23");
* ```
* Enable UTC formatting by setting the `utc` option to `true`.
*/
export function format(
date: Date,

25
datetime/is_leap.ts
View File

@ -22,25 +22,27 @@ function isYearNumberALeapYear(yearNumber: number): boolean {
* @example Basic usage
* ```ts
* import { isLeap } from "@std/datetime/is-leap";
* import { assertEquals } from "@std/assert/assert-equals";
*
* isLeap(new Date("1970-01-02")); // false
* assertEquals(isLeap(new Date("1970-01-02")), false);
*
* isLeap(1970); // false
* assertEquals(isLeap(1970), false);
*
* isLeap(new Date("1972-01-02")); // true
* assertEquals(isLeap(new Date("1972-01-02")), true);
*
* isLeap(1972); // true
* assertEquals(isLeap(1972), true);
* ```
*
* @example Accounting for timezones
* ```ts
* ```ts no-assert
* import { isLeap } from "@std/datetime/is-leap";
*
* // True if the local timezone is GMT+0; false if the local timezone is GMT-1
* isLeap(new Date("2000-01-01"));
* // true if the local timezone is GMT+0; false if the local timezone is GMT-1
*
* // True regardless of the local timezone
* isLeap(2000);
* // true regardless of the local timezone
*
* ```
*/
export function isLeap(year: Date | number): boolean {
@ -61,14 +63,15 @@ export function isLeap(year: Date | number): boolean {
* @example Basic usage
* ```ts
* import { isUtcLeap } from "@std/datetime/is-leap";
* import { assertEquals } from "@std/assert/assert-equals";
*
* isUtcLeap(new Date("2000-01-01")); // true
* assertEquals(isUtcLeap(new Date("2000-01-01")), true);
*
* isUtcLeap(new Date("December 31, 1999 23:59:59 GMT-01:00")); // true
* assertEquals(isUtcLeap(new Date("December 31, 1999 23:59:59 GMT-01:00")), true);
*
* isUtcLeap(2000); // true
* assertEquals(isUtcLeap(2000), true);
*
* isUtcLeap(1999); // false
* assertEquals(isUtcLeap(1999), false);
* ```
*/
export function isUtcLeap(year: Date | number): boolean {

12
datetime/mod.ts
View File

@ -14,7 +14,7 @@
* {@linkcode dayOfYear} returns the number of the day in the year in the local
* timezone. {@linkcode dayOfYearUtc} does the same but in UTC time.
*
* ```ts
* ```ts no-assert
* import { dayOfYear } from "@std/datetime/day-of-year";
*
* dayOfYear(new Date("2019-03-11T03:24:00")); // 70
@ -25,7 +25,7 @@
* {@linkcode difference} calculates the difference of the 2 given dates in
* various units.
*
* ```ts
* ```ts no-assert
* import { difference } from "@std/datetime/difference";
*
* const date0 = new Date("2018-05-14");
@ -49,7 +49,7 @@
*
* {@linkcode format} formats a date to a string with the specified format.
*
* ```ts
* ```ts no-assert
* import { format } from "@std/datetime/format";
*
* const date = new Date(2019, 0, 20, 16, 34, 23, 123);
@ -66,7 +66,7 @@
* {@linkcode isLeap} returns whether the given year is a leap year.
* {@linkcode isUtcLeap} does the same but in UTC time.
*
* ```ts
* ```ts no-assert
* import { isLeap } from "@std/datetime/is-leap";
*
* isLeap(new Date("1970-01-02")); // false
@ -82,7 +82,7 @@
*
* {@linkcode parse} parses a date string using the specified format string.
*
* ```ts
* ```ts no-assert
* import { parse } from "@std/datetime/parse";
*
* parse("20-01-2019", "dd-MM-yyyy"); // 2019-01-19T13:00:00.000Z
@ -97,7 +97,7 @@
* {@linkcode weekOfYear} returns the number of the week in the year in the local
* timezone.
*
* ```ts
* ```ts no-assert
* import { weekOfYear } from "@std/datetime/week-of-year";
*
* weekOfYear(new Date("2020-12-28T03:24:00")); // 53

7
datetime/parse.ts
View File

@ -37,12 +37,11 @@ import { DateTimeFormatter } from "./_date_time_formatter.ts";
* @example Basic usage
* ```ts
* import { parse } from "@std/datetime/parse";
* import { assertEquals } from "@std/assert/assert-equals";
*
* parse("20-01-2019", "dd-MM-yyyy"); // 2019-01-19T13:00:00.000Z
* assertEquals(parse("01-03-2019 16:30", "MM-dd-yyyy HH:mm"), new Date(2019, 0, 3, 16, 30));
*
* parse("01-20-2019 04:34 PM", "MM-dd-yyyy hh:mm a"); // 2019-01-20T05:34:00.000Z
*
* parse("01-20-2019 16:34:23.123", "MM-dd-yyyy HH:mm:ss.SSS"); // 2019-01-20T05:34:23.123Z
* assertEquals(parse("01-03-2019 16:33:23.123", "MM-dd-yyyy HH:mm:ss.SSS"), new Date(2019, 0, 3, 16, 33, 23, 123));
* ```
*/
export function parse(dateString: string, formatString: string): Date {

5
datetime/week_of_year.ts
View File

@ -24,10 +24,11 @@ const Day = {
* @example Basic usage
* ```ts
* import { weekOfYear } from "@std/datetime/week-of-year";
* import { assertEquals } from "@std/assert/assert-equals";
*
* weekOfYear(new Date("2020-12-28T03:24:00")); // 53
* assertEquals(weekOfYear(new Date("2020-12-28T03:24:00")), 53);
*
* weekOfYear(new Date("2020-07-10T03:24:00")); // 28
* assertEquals(weekOfYear(new Date("2020-07-10T03:24:00")), 28);
* ```
*/
export function weekOfYear(date: Date): number {

4
deno.json
View File

@ -23,7 +23,7 @@
"@std/data-structures": "jsr:@std/data-structures@^0.225.0",
"@std/datetime": "jsr:@std/datetime@^0.224.0",
"@std/dotenv": "jsr:@std/dotenv@^0.224.0",
"@std/encoding": "jsr:@std/encoding@^0.224.3",
"@std/encoding": "jsr:@std/encoding@1.0.0-rc.1",
"@std/expect": "jsr:@std/expect@^0.224.3",
"@std/fmt": "jsr:@std/fmt@^0.225.2",
"@std/front-matter": "jsr:@std/front-matter@^0.224.1",
@ -48,7 +48,7 @@
"@std/toml": "jsr:@std/toml@^0.224.0",
"@std/ulid": "jsr:@std/ulid@^0.224.1",
"@std/url": "jsr:@std/url@^0.224.0",
"@std/uuid": "jsr:@std/uuid@^0.224.3",
"@std/uuid": "jsr:@std/uuid@1.0.0-rc.1",
"@std/webgpu": "jsr:@std/webgpu@^0.224.2",
"@std/yaml": "jsr:@std/yaml@^0.224.1"
},

4
expect/expect.ts
View File

@ -114,8 +114,8 @@ const matchers: Record<MatcherKey, Matcher> = {
* The `expect` function is used to test a value. You will use `expect` along with a
* "matcher" function to assert something about a value.
*
* @example basic usage
* ```ts
* @example Usage
* ```ts no-assert
* import { expect } from "@std/expect";
*
* function bestLaCroixFlavor(): string {

4
expect/fn.ts
View File

@ -29,8 +29,8 @@ import { MOCK_SYMBOL, type MockCall } from "./_mock_util.ts";
* @param stubs - functions to be used as stubs for different calls.
* @returns A mock function that keeps track of calls and returns values based on the provided stubs.
*
* @example basic usage
* ```ts
* @example Usage
* ```ts no-assert
* import { fn, expect } from "@std/expect";
*
* Deno.test("example", () => {

2
expect/mod.ts
View File

@ -72,7 +72,7 @@
* This module is largely inspired by
* {@link https://github.com/allain/expect | x/expect} module by Allain Lalonde.
*
* ```ts
* ```ts no-assert
* import { expect } from "@std/expect";
*
* const x = 6 * 7;

60
fmt/bytes.ts
View File

@ -59,32 +59,46 @@ export interface FormatOptions {
*
* This module is browser compatible.
*
* @example Usage
* ```ts
* import { format } from "@std/fmt/bytes";
*
* format(1337);
* //=> '1.34 kB'
*
* format(100);
* //=> '100 B'
*
* // Display with units of bits
* format(1337, { bits: true });
* //=> '1.34 kbit'
*
* // Display file size differences
* format(42, { signed: true });
* //=> '+42 B'
*
* // Localized output using German locale
* format(1337, { locale: "de" });
* //=> '1,34 kB'
* ```
*
* @param num The bytes value to format
* @param options The options for formatting
* @returns The formatted string
*
* @example Basic usage
* ```ts
* import { format } from "@std/fmt/bytes";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(format(1337), "1.34 kB");
* assertEquals(format(100), "100 B");
* ```
*
* @example Include bits representation
*
* ```ts
* import { format } from "@std/fmt/bytes";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(format(1337, { bits: true }), "1.34 kbit");
* ```
*
* @example Include sign
*
* ```ts
* import { format } from "@std/fmt/bytes";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(format(42, { signed: true }), "+42 B");
* assertEquals(format(-42, { signed: true }), "-42 B");
* ```
*
* @example Change locale
*
* ```ts
* import { format } from "@std/fmt/bytes";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(format(1337, { locale: "de" }), "1,34 kB");
* ```
*/
export function format(
num: number,

100
fmt/colors.ts
View File

@ -11,7 +11,7 @@
* This module supports `NO_COLOR` environmental variable disabling any coloring
* if `NO_COLOR` is set.
*
* ```ts
* ```ts no-assert
* import {
* bgBlue,
* bgRgb24,
@ -81,7 +81,7 @@ let enabled = !noColor;
* doesn't work.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { setColorEnabled } from "@std/fmt/colors";
*
* // Disable text color
@ -105,7 +105,7 @@ export function setColorEnabled(value: boolean) {
* Get whether text color change is enabled or disabled.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { getColorEnabled } from "@std/fmt/colors";
*
* console.log(getColorEnabled()); // true if enabled, false if disabled
@ -144,7 +144,7 @@ function run(str: string, code: Code): string {
* Reset the text modified.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { reset } from "@std/fmt/colors";
*
* console.log(reset("Hello, world!"));
@ -161,7 +161,7 @@ export function reset(str: string): string {
* Make the text bold.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bold } from "@std/fmt/colors";
*
* console.log(bold("Hello, world!"));
@ -178,7 +178,7 @@ export function bold(str: string): string {
* The text emits only a small amount of light.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { dim } from "@std/fmt/colors";
*
* console.log(dim("Hello, world!"));
@ -198,7 +198,7 @@ export function dim(str: string): string {
* Make the text italic.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { italic } from "@std/fmt/colors";
*
* console.log(italic("Hello, world!"));
@ -215,7 +215,7 @@ export function italic(str: string): string {
* Make the text underline.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { underline } from "@std/fmt/colors";
*
* console.log(underline("Hello, world!"));
@ -232,7 +232,7 @@ export function underline(str: string): string {
* Invert background color and text color.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { inverse } from "@std/fmt/colors";
*
* console.log(inverse("Hello, world!"));
@ -249,7 +249,7 @@ export function inverse(str: string): string {
* Make the text hidden.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { hidden } from "@std/fmt/colors";
*
* console.log(hidden("Hello, world!"));
@ -266,7 +266,7 @@ export function hidden(str: string): string {
* Put horizontal line through the center of the text.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { strikethrough } from "@std/fmt/colors";
*
* console.log(strikethrough("Hello, world!"));
@ -283,7 +283,7 @@ export function strikethrough(str: string): string {
* Set text color to black.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { black } from "@std/fmt/colors";
*
* console.log(black("Hello, world!"));
@ -300,7 +300,7 @@ export function black(str: string): string {
* Set text color to red.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { red } from "@std/fmt/colors";
*
* console.log(red("Hello, world!"));
@ -317,7 +317,7 @@ export function red(str: string): string {
* Set text color to green.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { green } from "@std/fmt/colors";
*
* console.log(green("Hello, world!"));
@ -334,7 +334,7 @@ export function green(str: string): string {
* Set text color to yellow.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { yellow } from "@std/fmt/colors";
*
* console.log(yellow("Hello, world!"));
@ -351,7 +351,7 @@ export function yellow(str: string): string {
* Set text color to blue.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { blue } from "@std/fmt/colors";
*
* console.log(blue("Hello, world!"));
@ -368,7 +368,7 @@ export function blue(str: string): string {
* Set text color to magenta.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { magenta } from "@std/fmt/colors";
*
* console.log(magenta("Hello, world!"));
@ -385,7 +385,7 @@ export function magenta(str: string): string {
* Set text color to cyan.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { cyan } from "@std/fmt/colors";
*
* console.log(cyan("Hello, world!"));
@ -402,7 +402,7 @@ export function cyan(str: string): string {
* Set text color to white.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { white } from "@std/fmt/colors";
*
* console.log(white("Hello, world!"));
@ -419,7 +419,7 @@ export function white(str: string): string {
* Set text color to gray.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { gray } from "@std/fmt/colors";
*
* console.log(gray("Hello, world!"));
@ -436,7 +436,7 @@ export function gray(str: string): string {
* Set text color to bright black.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightBlack } from "@std/fmt/colors";
*
* console.log(brightBlack("Hello, world!"));
@ -453,7 +453,7 @@ export function brightBlack(str: string): string {
* Set text color to bright red.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightRed } from "@std/fmt/colors";
*
* console.log(brightRed("Hello, world!"));
@ -470,7 +470,7 @@ export function brightRed(str: string): string {
* Set text color to bright green.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightGreen } from "@std/fmt/colors";
*
* console.log(brightGreen("Hello, world!"));
@ -487,7 +487,7 @@ export function brightGreen(str: string): string {
* Set text color to bright yellow.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightYellow } from "@std/fmt/colors";
*
* console.log(brightYellow("Hello, world!"));
@ -504,7 +504,7 @@ export function brightYellow(str: string): string {
* Set text color to bright blue.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightBlue } from "@std/fmt/colors";
*
* console.log(brightBlue("Hello, world!"));
@ -521,7 +521,7 @@ export function brightBlue(str: string): string {
* Set text color to bright magenta.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightMagenta } from "@std/fmt/colors";
*
* console.log(brightMagenta("Hello, world!"));
@ -538,7 +538,7 @@ export function brightMagenta(str: string): string {
* Set text color to bright cyan.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightCyan } from "@std/fmt/colors";
*
* console.log(brightCyan("Hello, world!"));
@ -555,7 +555,7 @@ export function brightCyan(str: string): string {
* Set text color to bright white.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightWhite } from "@std/fmt/colors";
*
* console.log(brightWhite("Hello, world!"));
@ -572,7 +572,7 @@ export function brightWhite(str: string): string {
* Set background color to black.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBlack } from "@std/fmt/colors";
*
* console.log(bgBlack("Hello, world!"));
@ -589,7 +589,7 @@ export function bgBlack(str: string): string {
* Set background color to red.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgRed } from "@std/fmt/colors";
*
* console.log(bgRed("Hello, world!"));
@ -606,7 +606,7 @@ export function bgRed(str: string): string {
* Set background color to green.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgGreen } from "@std/fmt/colors";
*
* console.log(bgGreen("Hello, world!"));
@ -623,7 +623,7 @@ export function bgGreen(str: string): string {
* Set background color to yellow.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgYellow } from "@std/fmt/colors";
*
* console.log(bgYellow("Hello, world!"));
@ -640,7 +640,7 @@ export function bgYellow(str: string): string {
* Set background color to blue.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBlue } from "@std/fmt/colors";
*
* console.log(bgBlue("Hello, world!"));
@ -657,7 +657,7 @@ export function bgBlue(str: string): string {
* Set background color to magenta.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgMagenta } from "@std/fmt/colors";
*
* console.log(bgMagenta("Hello, world!"));
@ -674,7 +674,7 @@ export function bgMagenta(str: string): string {
* Set background color to cyan.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgCyan } from "@std/fmt/colors";
*
* console.log(bgCyan("Hello, world!"));
@ -691,7 +691,7 @@ export function bgCyan(str: string): string {
* Set background color to white.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgWhite } from "@std/fmt/colors";
*
* console.log(bgWhite("Hello, world!"));
@ -708,7 +708,7 @@ export function bgWhite(str: string): string {
* Set background color to bright black.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightBlack } from "@std/fmt/colors";
*
* console.log(bgBrightBlack("Hello, world!"));
@ -725,7 +725,7 @@ export function bgBrightBlack(str: string): string {
* Set background color to bright red.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightRed } from "@std/fmt/colors";
*
* console.log(bgBrightRed("Hello, world!"));
@ -742,7 +742,7 @@ export function bgBrightRed(str: string): string {
* Set background color to bright green.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightGreen } from "@std/fmt/colors";
*
* console.log(bgBrightGreen("Hello, world!"));
@ -759,7 +759,7 @@ export function bgBrightGreen(str: string): string {
* Set background color to bright yellow.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightYellow } from "@std/fmt/colors";
*
* console.log(bgBrightYellow("Hello, world!"));
@ -776,7 +776,7 @@ export function bgBrightYellow(str: string): string {
* Set background color to bright blue.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightBlue } from "@std/fmt/colors";
*
* console.log(bgBrightBlue("Hello, world!"));
@ -793,7 +793,7 @@ export function bgBrightBlue(str: string): string {
* Set background color to bright magenta.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightMagenta } from "@std/fmt/colors";
*
* console.log(bgBrightMagenta("Hello, world!"));
@ -810,7 +810,7 @@ export function bgBrightMagenta(str: string): string {
* Set background color to bright cyan.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightCyan } from "@std/fmt/colors";
*
* console.log(bgBrightCyan("Hello, world!"));
@ -827,7 +827,7 @@ export function bgBrightCyan(str: string): string {
* Set background color to bright white.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgBrightWhite } from "@std/fmt/colors";
*
* console.log(bgBrightWhite("Hello, world!"));
@ -857,7 +857,7 @@ function clampAndTruncate(n: number, max = 255, min = 0): number {
* https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
*
* @example Usage
* ```ts
* ```ts no-assert
* import { rgb8 } from "@std/fmt/colors";
*
* console.log(rgb8("Hello, world!", 42));
@ -876,7 +876,7 @@ export function rgb8(str: string, color: number): string {
* https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgRgb8 } from "@std/fmt/colors";
*
* console.log(bgRgb8("Hello, world!", 42));
@ -896,7 +896,7 @@ export function bgRgb8(str: string, color: number): string {
* an `Rgb`.
*
* @example To produce the color magenta:
* ```ts
* ```ts no-assert
* import { rgb24 } from "@std/fmt/colors";
*
* rgb24("foo", 0xff00ff);
@ -937,7 +937,7 @@ export function rgb24(str: string, color: number | Rgb): string {
* an `Rgb`.
*
* @example To produce the color magenta:
* ```ts
* ```ts no-assert
* import { bgRgb24 } from "@std/fmt/colors";
*
* bgRgb24("foo", 0xff00ff);
@ -985,7 +985,7 @@ const ANSI_PATTERN = new RegExp(
* Remove ANSI escape codes from the string.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { stripColor, red } from "@std/fmt/colors";
*
* console.log(stripColor(red("Hello, world!")));
@ -1004,7 +1004,7 @@ export function stripColor(string: string): string {
* Remove ANSI escape codes from the string.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { stripAnsiCode, red } from "@std/fmt/colors";
*
* console.log(stripAnsiCode(red("Hello, world!")));

25
fmt/duration.ts
View File

@ -6,18 +6,15 @@
*
* ```ts
* import { format } from "@std/fmt/duration";
* import { assertEquals } from "@std/assert/assert-equals";
*
* // "00:00:01:39:674:000:000"
* format(99674, { style: "digital" });
* assertEquals(format(99674, { style: "digital" }), "00:00:01:39:674:000:000");
*
* // "0d 0h 1m 39s 674ms 0µs 0ns"
* format(99674);
* assertEquals(format(99674), "0d 0h 1m 39s 674ms 0µs 0ns");
*
* // "1m 39s 674ms"
* format(99674, { ignoreZero: true });
* assertEquals(format(99674, { ignoreZero: true }), "1m 39s 674ms");
*
* // "1 minutes, 39 seconds, 674 milliseconds"
* format(99674, { style: "full", ignoreZero: true });
* assertEquals(format(99674, { style: "full", ignoreZero: true }), "1 minutes, 39 seconds, 674 milliseconds");
* ```
* @module
*/
@ -98,11 +95,15 @@ export interface PrettyDurationOptions {
* @example Usage
* ```ts
* import { format } from "@std/fmt/duration";
* import { assertEquals } from "@std/assert/assert-equals";
*
* format(99674, { style: "digital" }); // "00:00:01:39:674:000:000"
* format(99674); // "0d 0h 1m 39s 674ms 0µs 0ns"
* format(99674, { ignoreZero: true }); // "1m 39s 674ms"
* format(99674, { style: "full", ignoreZero: true }); // "1 minutes, 39 seconds, 674 milliseconds"
* assertEquals(format(99674, { style: "digital" }), "00:00:01:39:674:000:000");
*
* assertEquals(format(99674), "0d 0h 1m 39s 674ms 0µs 0ns");
*
* assertEquals(format(99674, { ignoreZero: true }), "1m 39s 674ms");
*
* assertEquals(format(99674, { style: "full", ignoreZero: true }), "1 minutes, 39 seconds, 674 milliseconds");
* ```
*
* @param ms The milliseconds value to format

18
fmt/printf.ts
View File

@ -934,11 +934,14 @@ class Printf {
* @example Usage
* ```ts
* import { sprintf } from "@std/fmt/printf";
* import { assertEquals } from "@std/assert"
* import { assertEquals } from "@std/assert";
*
* assertEquals(sprintf("%d", 9), "9");
*
* assertEquals(sprintf("%o", 9), "11");
*
* assertEquals(sprintf("%f", 4), "4.000000");
*
* assertEquals(sprintf("%.3f", 0.9999), "1.000");
* ```
*
@ -958,13 +961,16 @@ export function sprintf(format: string, ...args: unknown[]): string {
* See the module documentation for the available format strings.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { printf } from "@std/fmt/printf";
*
* printf("%d", 9); // prints "9"
* printf("%o", 9); // prints "11"
* printf("%f", 4); // prints "4.000000"
* printf("%.3f", 0.9999); // prints "1.000"
* printf("%d", 9); // Prints "9"
*
* printf("%o", 9); // Prints "11"
*
* printf("%f", 4); // Prints "4.000000"
*
* printf("%.3f", 0.9999); // Prints "1.000"
* ```
*
* @param format The format string to use

26
html/entities.ts
View File

@ -28,12 +28,13 @@ const rawRe = new RegExp(`[${[...rawToEntity.keys()].join("")}]`, "g");
* @example Usage
* ```ts
* import { escape } from "@std/html/entities";
* import { assertEquals } from "@std/assert/assert-equals";
*
* escape("<>'&AA"); // "&lt;&gt;&#39;&amp;AA"
* assertEquals(escape("<>'&AA"), "&lt;&gt;&#39;&amp;AA");
*
* // Characters that don't need to be escaped will be left alone,
* // even if named HTML entities exist for them.
* escape("þð"); // "þð"
* assertEquals(escape("þð"), "þð");
* ```
*
* @param str The string to escape.
@ -60,18 +61,27 @@ const entityListRegexCache = new WeakMap<EntityList, RegExp>();
/**
* Unescapes HTML entities in text.
*
* @example Usage
* Default options only handle `&<>'"` and numeric entities.
*
* @example Basic usage
* ```ts
* import { unescape } from "@std/html/entities";
* import { assertEquals } from "@std/assert/assert-equals";
*
* // Default options (only handles &<>'" and numeric entities)
* unescape("&lt;&gt;&apos;&amp;&#65;&#x41;"); // "<>'&AA"
* unescape("&thorn;&eth;"); // "&thorn;&eth;"
* assertEquals(unescape("&lt;&gt;&#39;&amp;AA"), "<>'&AA");
* assertEquals(unescape("&thorn;&eth;"), "&thorn;&eth;");
* ```
*
* // Using the full named entity list from the HTML spec (~47K un-minified)
* @example Using a custom entity list
*
* This uses the full named entity list from the HTML spec (~47K un-minified)
*
* ```ts
* import { unescape } from "@std/html/entities";
* import entityList from "@std/html/named-entity-list.json" with { type: "json" };
* import { assertEquals } from "@std/assert/assert-equals";
*
* unescape("&thorn;&eth;", { entityList }); // "þð"
* assertEquals(unescape("&lt;&gt;&#39;&amp;AA", { entityList }), "<>'&AA");
* ```
*
* @param str The string to unescape.

10
html/mod.ts
View File

@ -5,13 +5,11 @@
* Functions for HTML tasks such as escaping or unescaping HTML entities.
*
* ```ts
* import { escape } from "@std/html/entities";
* import { unescape } from "@std/html/entities";
* import { assertEquals } from "@std/assert/assert-equals";
*
* escape("<>'&AA"); // "&lt;&gt;&#39;&amp;AA"
*
* // Characters that don't need to be escaped will be left alone,
* // even if named HTML entities exist for them.
* escape("þð"); // "þð"
* assertEquals(unescape("&lt;&gt;&#39;&amp;AA"), "<>'&AA");
* assertEquals(unescape("&thorn;&eth;"), "&thorn;&eth;");
* ```
*
* @module

25
http/cookie.ts
View File

@ -197,12 +197,13 @@ function validateDomain(domain: string) {
* @example Usage
* ```ts
* import { getCookies } from "@std/http/cookie";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const headers = new Headers();
* headers.set("Cookie", "full=of; tasty=chocolate");
*
* const cookies = getCookies(headers);
* console.log(cookies); // { full: "of", tasty: "chocolate" }
* assertEquals(cookies, { full: "of", tasty: "chocolate" });
* ```
*
* @param headers The headers instance to get cookies from
@ -229,17 +230,16 @@ export function getCookies(headers: Headers): Record<string, string> {
*
* @example Usage
* ```ts
* import {
* Cookie,
* setCookie,
* } from "@std/http/cookie";
* import { Cookie, setCookie } from "@std/http/cookie";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const headers = new Headers();
* const cookie: Cookie = { name: "Space", value: "Cat" };
* setCookie(headers, cookie);
*
* const cookieHeader = headers.get("set-cookie");
* console.log(cookieHeader); // Space=Cat
*
* assertEquals(cookieHeader, "Space=Cat");
* ```
*
* @param headers The headers instance to set the cookie to
@ -263,12 +263,14 @@ export function setCookie(headers: Headers, cookie: Cookie) {
* @example Usage
* ```ts
* import { deleteCookie } from "@std/http/cookie";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const headers = new Headers();
* deleteCookie(headers, "deno");
*
* const cookieHeader = headers.get("set-cookie");
* console.log(cookieHeader); // deno=; Expires=Thus, 01 Jan 1970 00:00:00 GMT
*
* assertEquals(cookieHeader, "deno=; Expires=Thu, 01 Jan 1970 00:00:00 GMT");
* ```
*
* @param headers The headers instance to delete the cookie from
@ -379,6 +381,7 @@ function parseSetCookie(value: string): Cookie | null {
* @example Usage
* ```ts
* import { getSetCookies } from "@std/http/cookie";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const headers = new Headers([
* ["Set-Cookie", "lulu=meow; Secure; Max-Age=3600"],
@ -386,7 +389,13 @@ function parseSetCookie(value: string): Cookie | null {
* ]);
*
* const cookies = getSetCookies(headers);
* console.log(cookies); // [{ name: "lulu", value: "meow", secure: true, maxAge: 3600 }, { name: "booya", value: "kahsa", httpOnly: true, path: "/ }]
*
* assertEquals(cookies[0], {
* name: "lulu",
* value: "meow",
* secure: true,
* maxAge: 3600
* });
* ```
*
* @param headers The headers instance to get set-cookies from

2
http/etag.ts
View File

@ -98,7 +98,7 @@ async function calcFileInfo(
* @example Usage
* ```ts
* import { calculate } from "@std/http/etag";
* import { assert } from "@std/assert/assert"
* import { assert } from "@std/assert/assert";
*
* const body = "hello deno!";
*

47
http/negotiation.ts
View File

@ -27,22 +27,22 @@ export type Request = {
* @example Usage
* ```ts
* import { accepts } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: {
* "accept":
* accept:
* "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, *\/*;q=0.8",
* },
* });
*
* console.log(accepts(req));
* // [
* // "text/html",
* // "application/xhtml+xml",
* // "image/webp",
* // "application/xml",
* // "*\/*",
* // ]
* assertEquals(accepts(request), [
* "text/html",
* "application/xhtml+xml",
* "image/webp",
* "application/xml",
* "*\/*",
* ]);
* ```
*
* @param request The request to get the acceptable media types for.
@ -56,15 +56,16 @@ export function accepts(request: Request): string[];
* @example Usage
* ```ts
* import { accepts } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: {
* "accept":
* accept:
* "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, *\/*;q=0.8",
* },
* });
*
* accepts(req, "text/html", "image/webp"); // "text/html";
* assertEquals(accepts(request, "text/html", "image/webp"), "text/html");
* ```
*
* @param request The request to get the acceptable media types for.
@ -95,12 +96,13 @@ export function accepts(
* @example Usage
* ```ts
* import { acceptsEncodings } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: { "accept-encoding": "deflate, gzip;q=1.0, *;q=0.5" },
* });
*
* acceptsEncodings(req); // ["deflate", "gzip", "*"]
* assertEquals(acceptsEncodings(request), ["deflate", "gzip", "*"]);
* ```
*
* @param request The request to get the acceptable content encodings for.
@ -119,12 +121,13 @@ export function acceptsEncodings(request: Request): string[];
* @example Usage
* ```ts
* import { acceptsEncodings } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: { "accept-encoding": "deflate, gzip;q=1.0, *;q=0.5" },
* });
*
* acceptsEncodings(req, "gzip", "identity"); // "gzip"
* assertEquals(acceptsEncodings(request, "gzip", "identity"), "gzip");
* ```
*
* @param request The request to get the acceptable content encodings for.
@ -157,14 +160,15 @@ export function acceptsEncodings(
* @example Usage
* ```ts
* import { acceptsLanguages } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: {
* "accept-language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5",
* },
* });
*
* acceptsLanguages(req); // ["fr-CH", "fr", "en", "de", "*"]
* assertEquals(acceptsLanguages(request), ["fr-CH", "fr", "en", "de", "*"]);
* ```
*
* @param request The request to get the acceptable languages for.
@ -178,14 +182,15 @@ export function acceptsLanguages(request: Request): string[];
* @example Usage
* ```ts
* import { acceptsLanguages } from "@std/http/negotiation";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const req = new Request("https://example.com/", {
* const request = new Request("https://example.com/", {
* headers: {
* "accept-language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5",
* },
* });
*
* acceptsLanguages(req, "en-gb", "en-us", "en"); // "en"
* assertEquals(acceptsLanguages(request, "en-gb", "en-us", "en"), "en");
* ```
*
* @param request The request to get the acceptable language for.

2
http/server_sent_event_stream.ts
View File

@ -62,7 +62,7 @@ function stringify(message: ServerSentEventMessage): Uint8Array {
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events}
*
* @example Usage
* ```ts
* ```ts no-assert
* import {
* type ServerSentEventMessage,
* ServerSentEventStream,

21
http/status.ts
View File

@ -319,8 +319,9 @@ export type ErrorStatus = ClientErrorStatus | ServerErrorStatus;
* @example Usage
* ```ts
* import { isStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isStatus(404)); // Returns true
* assert(isStatus(404));
* ```
*
* @param status The status to assert against.
@ -336,8 +337,9 @@ export function isStatus(status: number): status is StatusCode {
* @example Usage
* ```ts
* import { isInformationalStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isInformationalStatus(404)); // Returns false
* assert(isInformationalStatus(100));
* ```
*
* @param status The status to assert against.
@ -355,8 +357,9 @@ export function isInformationalStatus(
* @example Usage
* ```ts
* import { isSuccessfulStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isSuccessfulStatus(404)); // Returns false
* assert(isSuccessfulStatus(200));
* ```
*
* @param status The status to assert against.
@ -374,8 +377,9 @@ export function isSuccessfulStatus(
* @example Usage
* ```ts
* import { isRedirectStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isRedirectStatus(302)); // Returns true
* assert(isRedirectStatus(302));
* ```
*
* @param status The status to assert against.
@ -391,8 +395,9 @@ export function isRedirectStatus(status: number): status is RedirectStatus {
* @example Usage
* ```ts
* import { isClientErrorStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isClientErrorStatus(404)); // Returns true
* assert(isClientErrorStatus(404));
* ```
*
* @param status The status to assert against.
@ -410,8 +415,9 @@ export function isClientErrorStatus(
* @example Usage
* ```ts
* import { isServerErrorStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isServerErrorStatus(502)); // Returns true
* assert(isServerErrorStatus(502));
* ```
*
* @param status The status to assert against.
@ -429,8 +435,9 @@ export function isServerErrorStatus(
* @example Usage
* ```ts
* import { isErrorStatus } from "@std/http/status";
* import { assert } from "@std/assert/assert";
*
* console.log(isErrorStatus(502)); // Returns true
* assert(isErrorStatus(502));
* ```
*
* @param status The status to assert against.

6
http/unstable_signed_cookie.ts
View File

@ -16,7 +16,7 @@ function splitByLast(value: string, separator: string): [string, string] {
* key.
*
* @example Usage
* ```ts
* ```ts no-eval no-assert
* import { signCookie } from "@std/http/unstable-signed-cookie";
* import { setCookie } from "@std/http/cookie";
*
@ -54,7 +54,7 @@ export async function signCookie(
* Returns a promise of a boolean indicating whether the signed cookie is valid.
*
* @example Usage
* ```ts
* ```ts no-eval no-assert
* import { verifyCookie } from "@std/http/unstable-signed-cookie";
* import { getCookies } from "@std/http/cookie";
*
@ -95,7 +95,7 @@ export async function verifyCookie(
* Important: always verify the cookie using {@linkcode verifyCookie} first.
*
* @example Usage
* ```ts
* ```ts no-eval no-assert
* import { verifyCookie, parseSignedCookie } from "@std/http/unstable-signed-cookie";
* import { getCookies } from "@std/http/cookie";
*

2
internal/build_message.ts
View File

@ -88,7 +88,7 @@ export interface BuildMessageOptions {
* @returns An array of strings representing the built message.
*
* @example Usage
* ```ts
* ```ts no-assert
* import { diffStr, buildMessage } from "@std/internal";
*
* const diffResult = diffStr("Hello, world!", "Hello, world");

20
internal/styles.ts
View File

@ -43,7 +43,7 @@ function run(str: string, code: Code): string {
* @returns Bold text for printing
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bold } from "@std/internal/styles";
*
* console.log(bold("Hello, world!")); // Prints "Hello, world!" in bold
@ -63,7 +63,7 @@ export function bold(str: string): string {
* @returns Red text for printing
*
* @example Usage
* ```ts
* ```ts no-assert
* import { red } from "@std/internal/styles";
*
* console.log(red("Hello, world!")); // Prints "Hello, world!" in red
@ -83,7 +83,7 @@ export function red(str: string): string {
* @returns Green text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { green } from "@std/internal/styles";
*
* console.log(green("Hello, world!")); // Prints "Hello, world!" in green
@ -103,7 +103,7 @@ export function green(str: string): string {
* @returns Yellow text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { yellow } from "@std/internal/styles";
*
* console.log(yellow("Hello, world!")); // Prints "Hello, world!" in yellow
@ -121,7 +121,7 @@ export function yellow(str: string): string {
* @returns White text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { white } from "@std/internal/styles";
*
* console.log(white("Hello, world!")); // Prints "Hello, world!" in white
@ -139,7 +139,7 @@ export function white(str: string): string {
* @returns Gray text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { gray } from "@std/internal/styles";
*
* console.log(gray("Hello, world!")); // Prints "Hello, world!" in gray
@ -157,7 +157,7 @@ export function gray(str: string): string {
* @returns Bright-black text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { brightBlack } from "@std/internal/styles";
*
* console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black
@ -175,7 +175,7 @@ export function brightBlack(str: string): string {
* @returns Red background text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgRed } from "@std/internal/styles";
*
* console.log(bgRed("Hello, world!")); // Prints "Hello, world!" with red background
@ -193,7 +193,7 @@ export function bgRed(str: string): string {
* @returns Green background text for print
*
* @example Usage
* ```ts
* ```ts no-assert
* import { bgGreen } from "@std/internal/styles";
*
* console.log(bgGreen("Hello, world!")); // Prints "Hello, world!" with green background
@ -220,7 +220,7 @@ const ANSI_PATTERN = new RegExp(
* @returns Text without ANSI escape codes
*
* @example Usage
* ```ts
* ```ts no-assert
* import { red, stripAnsiCode } from "@std/internal/styles";
*
* console.log(stripAnsiCode(red("Hello, world!"))); // Prints "Hello, world!"

14
jsonc/mod.ts
View File

@ -10,12 +10,16 @@
*
* ```ts
* import { parse } from "@std/jsonc";
* import { assertEquals } from "@std/assert/assert-equals";
*
* parse('{"foo": "bar", } // comment'); // { foo: "bar" }
* parse('{"foo": "bar", } /* comment *\/'); // { foo: "bar" }
* parse('{"foo": "bar" } // comment', {
* allowTrailingComma: false,
* }); // { foo: "bar" }
* assertEquals(parse('{"foo": "bar", } // comment'), { foo: "bar" });
*
* assertEquals(parse('{"foo": "bar", } /* comment *\/'), { foo: "bar" });
*
* assertEquals(
* parse('{"foo": "bar" } // comment', { allowTrailingComma: false }),
* { foo: "bar" }
* );
* ```
*
* @module

10
jsonc/parse.ts
View File

@ -32,12 +32,12 @@ export interface ParseOptions {
* @example Usage
* ```ts
* import { parse } from "@std/jsonc";
* import { assertEquals } from "@std/assert";
*
* parse('{"foo": "bar", } // comment'); // { foo: "bar" }
* parse('{"foo": "bar", } /* comment *\/'); // { foo: "bar" }
* parse('{"foo": "bar" } // comment', {
* allowTrailingComma: false,
* }); // { foo: "bar" }
* assertEquals(parse('{"foo": "bar"}'), { foo: "bar" });
* assertEquals(parse('{"foo": "bar", }'), { foo: "bar" });
* assertEquals(parse('{"foo": "bar", } /* comment *\/'), { foo: "bar" });
* assertEquals(parse('{"foo": "bar" } // comment', { allowTrailingComma: false }), { foo: "bar" });
* ```
*
* @param text A valid JSONC string.

14
path/mod.ts
View File

@ -13,20 +13,22 @@
* To use functions for a specific path style regardless of the current OS
* import the modules from the platform sub directory instead.
*
* Example, for `posix`:
* Example, for POSIX:
*
* ```ts
* import { fromFileUrl } from "@std/path/posix/from-file-url";
* const p = fromFileUrl("file:///home/foo");
* console.log(p); // "/home/foo"
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(fromFileUrl("file:///home/foo"), "/home/foo");
* ```
*
* or, for `windows`:
* Or, for Windows:
*
* ```ts
* import { fromFileUrl } from "@std/path/windows/from-file-url";
* const p = fromFileUrl("file:///home/foo");
* console.log(p); // "\\home\\foo"
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(fromFileUrl("file:///home/foo"), "\\home\\foo");
* ```
*
* This module is browser compatible.

5
path/posix/glob_to_regexp.ts
View File

@ -76,9 +76,10 @@ const constants: GlobConstants = {
*
* @example Usage
* ```ts
* import { globToRegExp } from "@std/path/glob-to-regexp";
* import { globToRegExp } from "@std/path/posix/glob-to-regexp";
* import { assertEquals } from "@std/assert/assert-equals";
*
* globToRegExp("*.js"); // /^[^/]*\.js\/*$/;
* assertEquals(globToRegExp("*.js"), /^[^/]*\.js\/*$/);
* ```
*
* @param glob Glob string to convert.

10
path/posix/mod.ts
View File

@ -9,12 +9,12 @@
* Codes in the examples uses POSIX path but it automatically use Windows path
* on Windows. Use methods under `posix` or `win32` object instead to handle non
* platform specific path like:
*
* ```ts
* import { posix, win32 } from "@std/path";
* const p1 = posix.fromFileUrl("file:///home/foo");
* const p2 = win32.fromFileUrl("file:///home/foo");
* console.log(p1); // "/home/foo"
* console.log(p2); // "\\home\\foo"
* import { fromFileUrl } from "@std/path/posix";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(fromFileUrl("file:///home/foo"), "/home/foo");
* ```
*
* This module is browser compatible.

3
path/windows/glob_to_regexp.ts
View File

@ -75,8 +75,9 @@ const constants: GlobConstants = {
* @example Usage
* ```ts
* import { globToRegExp } from "@std/path/windows/glob-to-regexp";
* import { assertEquals } from "@std/assert/assert-equals";
*
* globToRegExp("*.js"); // /^[^\\]*\.js\/*$/;
* assertEquals(globToRegExp("*.js"), /^[^\\/]*\.js(?:\\|\/)*$/);
* ```
*
* @param glob Glob string to convert.

10
path/windows/mod.ts
View File

@ -9,12 +9,12 @@
* Codes in the examples uses POSIX path but it automatically use Windows path
* on Windows. Use methods under `posix` or `win32` object instead to handle non
* platform specific path like:
*
* ```ts
* import { posix, win32 } from "@std/path";
* const p1 = posix.fromFileUrl("file:///home/foo");
* const p2 = win32.fromFileUrl("file:///home/foo");
* console.log(p1); // "/home/foo"
* console.log(p2); // "\\home\\foo"
* import { fromFileUrl } from "@std/path/windows";
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(fromFileUrl("file:///home/foo"), "\\home\\foo");
* ```
*
* This module is browser compatible.

16
semver/mod.ts
View File

@ -15,16 +15,26 @@
* lessThan,
* format
* } from "@std/semver";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const semver = parse("1.2.3");
* assertEquals(semver, {
* major: 1,
* minor: 2,
* patch: 3,
* prerelease: [],
* build: []
* });
*
* assertEquals(format(semver), "1.2.3");
*
* const range = parseRange("1.x || >=2.5.0 || 5.0.0 - 7.2.3");
*
* const s0 = parse("1.2.3");
* const s1 = parse("9.8.7");
* greaterThan(s0, s1); // false
* lessThan(s0, s1); // true
*
* format(semver) // "1.2.3"
* assertEquals(greaterThan(s0, s1), false);
* assertEquals(lessThan(s0, s1), true);
* ```
*
* ## Versions

10
streams/buffer.ts
View File

@ -93,7 +93,7 @@ export class Buffer {
* @returns A `ReadableStream` of the buffer.
*
* @example Read the content out of the buffer to stdout
* ```ts
* ```ts no-assert
* import { Buffer } from "@std/streams/buffer";
*
* const buf = new Buffer();
@ -117,7 +117,7 @@ export class Buffer {
* @returns A `WritableStream` of the buffer.
*
* @example Write the data from stdin to the buffer
* ```ts
* ```ts no-assert
* import { Buffer } from "@std/streams/buffer";
*
* const buf = new Buffer();
@ -134,14 +134,14 @@ export class Buffer {
* @param ab An optional buffer to use as the initial buffer.
*
* @example No initial buffer provided
* ```ts
* ```ts no-assert
* import { Buffer } from "@std/streams/buffer";
*
* const buf = new Buffer();
* ```
*
* @example With a pre-allocated buffer
* ```ts
* ```ts no-assert
* import { Buffer } from "@std/streams/buffer";
*
* const arrayBuffer = new ArrayBuffer(8);
@ -149,7 +149,7 @@ export class Buffer {
* ```
*
* @example From Uint8Array
* ```ts
* ```ts no-assert
* import { Buffer } from "@std/streams/buffer";
*
* const array = new Uint8Array([0, 1, 2]);

4
streams/byte_slice_stream.ts
View File

@ -47,14 +47,14 @@ export class ByteSliceStream extends TransformStream<Uint8Array, Uint8Array> {
* @param end The zero-indexed byte index to stop reading at. Inclusive.
*
* @example No parameters
* ```ts
* ```ts no-assert
* import { ByteSliceStream } from "@std/streams/byte-slice-stream";
*
* const byteSliceStream = new ByteSliceStream();
* ```
*
* @example start = 4, end = 11
* ```ts
* ```ts no-assert
* import { ByteSliceStream } from "@std/streams/byte-slice-stream";
*
* const byteSliceStream = new ByteSliceStream(4, 11);

4
streams/delimiter_stream.ts
View File

@ -76,14 +76,14 @@ export class DelimiterStream extends TransformStream<Uint8Array, Uint8Array> {
* @param options Options for the delimiter stream.
*
* @example comma as a delimiter
* ```ts
* ```ts no-assert
* import { DelimiterStream } from "@std/streams/delimiter-stream";
*
* const delimiterStream = new DelimiterStream(new TextEncoder().encode(","));
* ```
*
* @example semicolon as a delimiter, and disposition set to `"suffix"`
* ```ts
* ```ts no-assert
* import { DelimiterStream } from "@std/streams/delimiter-stream";
*
* const delimiterStream = new DelimiterStream(new TextEncoder().encode(";"), {

8
streams/iterate_reader.ts
View File

@ -17,7 +17,7 @@ export type { Reader, ReaderSync };
* @returns An async iterator that yields Uint8Array.
*
* @example Convert a `Deno.FsFile` into an async iterator and iterate over it
* ```ts
* ```ts no-assert no-eval
* import { iterateReader } from "@std/streams/iterate-reader";
*
* using f = await Deno.open("./README.md");
@ -27,7 +27,7 @@ export type { Reader, ReaderSync };
* ```
*
* @example Specify a buffer size of 1MiB
* ```ts
* ```ts no-assert no-eval
* import { iterateReader } from "@std/streams/iterate-reader";
*
* using f = await Deno.open("./README.md");
@ -59,7 +59,7 @@ export function iterateReader(
* @returns An iterator that yields Uint8Array.
*
* @example Convert a `Deno.FsFile` into an iterator and iterate over it
* ```ts
* ```ts no-eval no-assert
* import { iterateReaderSync } from "@std/streams/iterate-reader";
*
* using f = Deno.openSync("./README.md");
@ -69,7 +69,7 @@ export function iterateReader(
* ```
*
* @example Specify a buffer size of 1MiB
* ```ts
* ```ts no-eval no-assert
* import { iterateReaderSync } from "@std/streams/iterate-reader";
*
* using f = await Deno.open("./README.md");

4
streams/limited_bytes_transform_stream.ts
View File

@ -99,14 +99,14 @@ export class LimitedBytesTransformStream
* @param options Options for the stream.
*
* @example size = 42
* ```ts
* ```ts no-assert
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
*
* const limitedBytesTransformStream = new LimitedBytesTransformStream(42);
* ```
*
* @example size = 42, error = true
* ```ts
* ```ts no-assert
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
*
* const limitedBytesTransformStream = new LimitedBytesTransformStream(42, { error: true });

4
streams/limited_transform_stream.ts
View File

@ -81,14 +81,14 @@ export class LimitedTransformStream<T> extends TransformStream<T, T> {
* @param options Options for the stream.
*
* @example size = 42
* ```ts
* ```ts no-assert
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
*
* const limitedTransformStream = new LimitedTransformStream(42);
* ```
*
* @example size = 42, error = true
* ```ts
* ```ts no-assert
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
*
* const limitedTransformStream = new LimitedTransformStream(42, { error: true });

2
streams/readable_stream_from_reader.ts
View File

@ -39,7 +39,7 @@ export interface ReadableStreamFromReaderOptions {
* @returns A `ReadableStream` of `Uint8Array`s.
*
* @example Convert a `Deno.FsFile` into a readable stream:
* ```ts
* ```ts no-eval no-assert
* import { readableStreamFromReader } from "@std/streams/readable-stream-from-reader";
*
* using file = await Deno.open("./README.md", { read: true });

2
streams/reader_from_iterable.ts
View File

@ -12,7 +12,7 @@ import type { Reader } from "@std/io/types";
* @returns A `Reader` that reads from the iterable.
*
* @example Write `Deno.build` information to the blackhole 3 times every second
* ```ts
* ```ts no-eval no-assert
* import { readerFromIterable } from "@std/streams/reader-from-iterable";
* import { copy } from "@std/io/copy";
* import { delay } from "@std/async/delay";

2
streams/reader_from_stream_reader.ts
View File

@ -11,7 +11,7 @@ import type { Reader } from "@std/io/types";
* @returns A `Reader` that reads from the `streamReader`.
*
* @example Copy the response body of a fetch request to the blackhole
* ```ts
* ```ts no-eval no-assert
* import { copy } from "@std/io/copy";
* import { readerFromStreamReader } from "@std/streams/reader-from-stream-reader";
* import { devNull } from "node:os";

8
streams/text_delimiter_stream.ts
View File

@ -68,15 +68,15 @@ export class TextDelimiterStream extends TransformStream<string, string> {
* @param delimiter A delimiter to split the stream by.
* @param options Options for the stream.
*
* @example comma as a delimiter
* ```ts
* @example Comma as a delimiter
* ```ts no-assert
* import { TextDelimiterStream } from "@std/streams/text-delimiter-stream";
*
* const delimiterStream = new TextDelimiterStream(",");
* ```
*
* @example semicolon as a delimiter, and disposition set to `"suffix"`
* ```ts
* @example Semicolon as a delimiter, and disposition set to `"suffix"`
* ```ts no-assert
* import { TextDelimiterStream } from "@std/streams/text-delimiter-stream";
*
* const delimiterStream = new TextDelimiterStream(",", {

35
streams/text_line_stream.ts
View File

@ -48,7 +48,8 @@ export interface TextLineStreamOptions {
* );
* ```
*
* @example allowCR: true
* @example Allow splitting by `\r`
*
* ```ts
* import { TextLineStream } from "@std/streams/text-line-stream";
* import { assertEquals } from "@std/assert/assert-equals";
@ -56,14 +57,11 @@ export interface TextLineStreamOptions {
* const stream = ReadableStream.from([
* "CR\rLF",
* "\nCRLF\r\ndone",
* ]);
* ]).pipeThrough(new TextLineStream({ allowCR: true }));
*
* const lineStream = stream.pipeThrough(new TextLineStream({ allowCR: true }));
* const lines = await Array.fromAsync(stream);
*
* assertEquals(
* await Array.fromAsync(lineStream),
* ["CR", "LF", "CRLF", "done"],
* );
* assertEquals(lines, ["CR", "LF", "CRLF", "done"]);
* ```
*/
export class TextLineStream extends TransformStream<string, string> {
@ -77,15 +75,32 @@ export class TextLineStream extends TransformStream<string, string> {
* @example No parameters
* ```ts
* import { TextLineStream } from "@std/streams/text-line-stream";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const textLineStream = new TextLineStream();
* const stream = ReadableStream.from([
* "Hello,\n",
* "world!\n",
* ]).pipeThrough(new TextLineStream());
*
* const lines = await Array.fromAsync(stream);
*
* assertEquals(lines, ["Hello,", "world!"]);
* ```
*
* @example allowCR = true
* @example Allow splitting by `\r`
*
* ```ts
* import { TextLineStream } from "@std/streams/text-line-stream";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const textLineStream = new TextLineStream({ allowCR: true });
* const stream = ReadableStream.from([
* "CR\rLF",
* "\nCRLF\r\ndone",
* ]).pipeThrough(new TextLineStream({ allowCR: true }));
*
* const lines = await Array.fromAsync(stream);
*
* assertEquals(lines, ["CR", "LF", "CRLF", "done"]);
* ```
*/
constructor(options: TextLineStreamOptions = { allowCR: false }) {

2
streams/writable_stream_from_writer.ts
View File

@ -27,7 +27,7 @@ export interface WritableStreamFromWriterOptions {
* @returns A `WritableStream` of `Uint8Array`s.
*
* @example Convert `Deno.stdout` into a writable stream
* ```ts
* ```ts no-eval no-assert
* // Note that you can directly get the writer from `Deno.stdout` by
* // `Deno.stdout.writable`. This example is just for demonstration purposes;
* // definitely not a recommended way.

2
streams/writer_from_stream_writer.ts
View File

@ -12,7 +12,7 @@ export type { Writer };
* @returns A `Writer` that writes to the `WritableStreamDefaultWriter`.
*
* @example Read from a file and write to stdout using a writable stream
* ```ts
* ```ts no-eval no-assert
* import { copy } from "@std/io/copy";
* import { writerFromStreamWriter } from "@std/streams/writer-from-stream-writer";
*

13
text/case.ts
View File

@ -9,8 +9,9 @@ import { capitalizeWord, splitToWords } from "./_util.ts";
* @example Usage
* ```ts
* import { toCamelCase } from "@std/text/case";
* import { assertEquals } from "@std/assert/assert-equals";
*
* toCamelCase("deno is awesome"); // "denoIsAwesome"
* assertEquals(toCamelCase("deno is awesome"),"denoIsAwesome");
* ```
*
* @param input The string that is going to be converted into camelCase
@ -28,8 +29,9 @@ export function toCamelCase(input: string): string {
* @example Usage
* ```ts
* import { toKebabCase } from "@std/text/case";
* import { assertEquals } from "@std/assert/assert-equals";
*
* toKebabCase("deno is awesome"); // "deno-is-awesome"
* assertEquals(toKebabCase("deno is awesome"), "deno-is-awesome");
* ```
*
* @param input The string that is going to be converted into kebab-case
@ -46,8 +48,9 @@ export function toKebabCase(input: string): string {
* @example Usage
* ```ts
* import { toPascalCase } from "@std/text/case";
* import { assertEquals } from "@std/assert/assert-equals";
*
* toPascalCase("deno is awesome"); // "DenoIsAwesome"
* assertEquals(toPascalCase("deno is awesome"), "DenoIsAwesome");
* ```
*
* @param input The string that is going to be converted into PascalCase
@ -64,7 +67,9 @@ export function toPascalCase(input: string): string {
* @example Usage
* ```ts
* import { toSnakeCase } from "@std/text/case";
* toSnakeCase("deno is awesome"); // "deno_is_awesome"
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(toSnakeCase("deno is awesome"), "deno_is_awesome");
* ```
*
* @param input The string that is going to be converted into snake_case

9
text/closest_string.ts
View File

@ -7,16 +7,17 @@ import { assert } from "@std/assert/assert";
const getWordDistance = levenshteinDistance;
/**
* get most-similar word
* The the most similar string from an array of strings.
*
* @example Usage
* ```ts
* import { closestString } from "@std/text/closest-string";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const possibleWords: string[] = ["length", "size", "blah", "help"];
* const possibleWords = ["length", "size", "blah", "help"];
* const suggestion = closestString("hep", possibleWords);
*
* // case-insensitive by default
* const word = closestString("hep", possibleWords);
* assertEquals(suggestion, "help");
* ```
*
* @param givenWord The string to measure distance against

13
text/compare_similarity.ts
View File

@ -6,7 +6,7 @@ import { levenshteinDistance } from "./levenshtein_distance.ts";
const getWordDistance = levenshteinDistance;
/**
* Sort based on word similarity
* Sort based on word similarity.
*
* @param givenWord The string to measure distance against.
* @param options An options bag containing a `caseSensitive` flag indicating
@ -16,12 +16,17 @@ const getWordDistance = levenshteinDistance;
* similar, or `0` if they are equally similar.
*
* @example Usage
*
* Most-similar words will be at the start of the array.
*
* ```ts
* import { compareSimilarity } from "@std/text/compare-similarity";
* const words = ["hi", "hello", "help"];
* import { assertEquals } from "@std/assert/assert-equals";
*
* // words most-similar to "hep" will be at the front
* words.sort(compareSimilarity("hep"));
* const words = ["hi", "hello", "help"];
* const sortedWords = words.sort(compareSimilarity("hep"));
*
* assertEquals(sortedWords, ["help", "hi", "hello"]);
* ```
* @note
* the ordering of words may change with version-updates

4
text/levenshtein_distance.ts
View File

@ -7,7 +7,9 @@
* @example Usage
* ```ts
* import { levenshteinDistance } from "@std/text/levenshtein-distance";
* levenshteinDistance("aa", "bb"); // 2
* import { assertEquals } from "@std/assert/assert-equals";
*
* assertEquals(levenshteinDistance("aa", "bb"), 2);
* ```
* @param str1 - The first string.
* @param str2 - The second string.

3
text/mod.ts
View File

@ -8,8 +8,9 @@
*
* ```ts
* import { toCamelCase } from "@std/text/case";
* import { assertEquals } from "@std/assert/assert-equals";
*
* console.log(toCamelCase("snake_case")); // "snakeCase"
* assertEquals(toCamelCase("snake_case"), "snakeCase");
* ```
*
* Or for comparing strings:

15
text/word_similarity_sort.ts
View File

@ -3,26 +3,27 @@
import { compareSimilarity } from "./compare_similarity.ts";
/**
* Sorts a string-array by similarity to a given string
* Sorts a string-array by similarity to a given string.
*
* @example Basic usage
*
* This function is case-insensitive by default.
*
* @example Usage
* ```ts
* import { wordSimilaritySort } from "@std/text/word-similarity-sort";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const possibleWords = ["length", "size", "blah", "help"];
*
* // case-insensitive by default
* const suggestions = wordSimilaritySort("hep", possibleWords).join(", ");
*
* // force case sensitive
* wordSimilaritySort("hep", possibleWords, { caseSensitive: true });
* assertEquals(suggestions, "help, size, blah, length");
* ```
*
* @param givenWord - The string to measure distance against
* @param possibleWords - The string-array that will be sorted
* @param options An options bag containing a `caseSensitive` flag indicating
* whether the distance should include case. Default is false.
* @returns {string[]} A sorted copy of possibleWords
* @returns A sorted copy of possibleWords
*/
export function wordSimilaritySort(
givenWord: string,

42
toml/mod.ts
View File

@ -91,10 +91,9 @@
* This module is browser compatible.
*
* ```ts
* import {
* parse,
* stringify,
* } from "@std/toml";
* import { parse, stringify } from "@std/toml";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const obj = {
* bin: [
* { name: "deno", path: "cli/main.rs" },
@ -102,33 +101,24 @@
* ],
* nib: [{ name: "node", path: "not_found" }],
* };
*
* const tomlString = stringify(obj);
* console.log(tomlString);
* assertEquals(tomlString, `
* [[bin]]
* name = "deno"
* path = "cli/main.rs"
*
* // =>
* // [[bin]]
* // name = "deno"
* // path = "cli/main.rs"
* [[bin]]
* name = "deno_core"
* path = "src/foo.rs"
*
* // [[bin]]
* // name = "deno_core"
* // path = "src/foo.rs"
*
* // [[nib]]
* // name = "node"
* // path = "not_found"
* [[nib]]
* name = "node"
* path = "not_found"
* `);
*
* const tomlObject = parse(tomlString);
* console.log(tomlObject);
*
* // =>
* // {
* // bin: [
* // { name: "deno", path: "cli/main.rs" },
* // { name: "deno_core", path: "src/foo.rs" }
* // ],
* // nib: [ { name: "node", path: "not_found" } ]
* // }
* assertEquals(tomlObject, obj);
* ```
*
* @module

30
ulid/mod.ts
View File

@ -10,7 +10,7 @@
* To generate a ULID use the {@linkcode ulid} function. This will generate a
* ULID based on the current time.
*
* ```ts
* ```ts no-assert
* import { ulid } from "@std/ulid";
*
* ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
@ -21,7 +21,7 @@
* will be strictly increasing, even for the same current time, use the
* {@linkcode monotonicUlid} function.
*
* ```ts
* ```ts no-assert
* import { monotonicUlid } from "@std/ulid";
*
* monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
@ -33,9 +33,12 @@
*
* ```ts
* import { decodeTime, ulid } from "@std/ulid";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const x = ulid(150000);
* decodeTime(x); // 150000
* const timestamp = 150_000;
* const ulidString = ulid(timestamp);
*
* assertEquals(decodeTime(ulidString), timestamp);
* ```
*
* @module
@ -58,10 +61,13 @@ import {
*
* @example Decode the time from a ULID
* ```ts
* import { ulid, decodeTime } from "@std/ulid";
* import { decodeTime, ulid } from "@std/ulid";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const x = ulid(150000);
* decodeTime(x); // 150000
* const timestamp = 150_000;
* const ulidString = ulid(timestamp);
*
* assertEquals(decodeTime(ulidString), timestamp);
* ```
*
* @param ulid The ULID to extract the timestamp from.
@ -102,15 +108,16 @@ const defaultMonotonicUlid = monotonicFactory();
* previous ULIDs for that same seed time.
*
* @example Generate a monotonic ULID
* ```ts
* ```ts no-assert
* import { monotonicUlid } from "@std/ulid";
*
* monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
* monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
* monotonicUlid(); // 01HYFKHHX8H4BRY8BYHAV1BZ2T
* ```
*
* @example Generate a monotonic ULID with a seed time
* ```ts
* ```ts no-assert
* import { monotonicUlid } from "@std/ulid";
*
* // Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
@ -144,15 +151,16 @@ export function monotonicUlid(seedTime: number = Date.now()): string {
* same. For that, use the {@linkcode monotonicUlid} function.
*
* @example Generate a ULID
* ```ts
* ```ts no-assert
* import { ulid } from "@std/ulid";
*
* ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
* ulid(); // 01HYFKMDF3D2P7G502B9Z2VKV0
* ulid(); // 01HYFKMDZQ7JD17CRKDXQSZ3Z4
* ```
*
* @example Generate a ULID with a seed time
* ```ts
* ```ts no-assert
* import { ulid } from "@std/ulid";
*
* ulid(150000); // 0000004JFG3EKDRE04TVVDJW7K

10
webgpu/describe_texture_format.ts
View File

@ -33,8 +33,16 @@ const allFlags = GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST |
* @example Basic usage
* ```ts
* import { describeTextureFormat } from "@std/webgpu/describe-texture-format";
* import { assertEquals } from "@std/assert/assert-equals";
*
* describeTextureFormat("rgba8unorm-srgb");
* assertEquals(describeTextureFormat("rgba8unorm"), {
* requiredFeature: undefined,
* sampleType: "float",
* allowedUsages: 31,
* blockDimensions: [1, 1],
* blockSize: 4,
* components: 4,
* });
* ```
*
* @param format The format to get the information about.

11
webgpu/row_padding.ts
View File

@ -16,15 +16,17 @@ export const COPY_BYTES_PER_ROW_ALIGNMENT = 256;
export const BYTES_PER_PIXEL = 4;
/**
* Calculates the number of bytes including necessary padding when passing a {@linkcode GPUImageCopyBuffer}.
* Calculates the number of bytes including necessary padding when passing a
* {@linkcode GPUImageCopyBuffer}.
*
* Ref: https://en.wikipedia.org/wiki/Data_structure_alignment#Computing_padding
*
* @example Usage
* ```ts
* import { getRowPadding } from "@std/webgpu/row-padding";
* import { assertEquals } from "@std/assert/assert-equals";
*
* getRowPadding(2); // { unpadded: 8, padded: 256 }
* assertEquals(getRowPadding(1), { unpadded: 4, padded: 256 });
* ```
*
* @param width The width to get the padding for
@ -55,9 +57,12 @@ export function getRowPadding(width: number): Padding {
* @example Usage
* ```ts
* import { resliceBufferWithPadding } from "@std/webgpu/row-padding";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const input = new Uint8Array([0, 255, 0, 255, 120, 120, 120]);
* resliceBufferWithPadding(input, 1, 1); // Uint8Array(4) [ 0, 255, 0, 255 ]
* const result = resliceBufferWithPadding(input, 1, 1);
*
* assertEquals(result, new Uint8Array([0, 255, 0, 255]));
* ```
*
* @param buffer The buffer to reslice.