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

docs(bytes): polish documentation (#4594)

Browse Source
This commit is contained in:
Asher Gomez 2024-04-16 16:59:52 +10:00 committed by GitHub
parent 2584aa7d5c
commit 3da310774d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 304 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
bytes/concat.ts
View File

@ -2,14 +2,17 @@
// This module is browser compatible.
/**
* Concatenate an array of {@linkcode Uint8Array}s.
* Concatenate an array of byte slices into a single slice.
*
* @example
* @param buf Array of byte slices to concatenate.
*
* @example Basic usage
* ```ts
* import { concat } from "https://deno.land/std@$STD_VERSION/bytes/concat.ts";
*
* const a = new Uint8Array([0, 1, 2]);
* const b = new Uint8Array([3, 4, 5]);
*
* concat([a, b]); // Uint8Array(6) [ 0, 1, 2, 3, 4, 5 ]
* ```
*/

34
bytes/copy.ts
View File

@ -1,38 +1,48 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Copy bytes from the `src` array to the `dst` array. Returns the number of
/**
* Copy bytes from the `src` array to the `dst` array and returns the number of
* bytes copied.
*
* If the `src` array is larger than what the `dst` array can hold, only the
* amount of bytes that fit in the `dst` array are copied.
*
* An offset can be specified as the third argument that begins the copy at
* that given index in the `dst` array. The offset defaults to the beginning of
* the array.
* @param src Source array to copy from.
* @param dst Destination array to copy to.
* @param offset Offset in the destination array to start copying to. Defaults
* to 0.
*
* @example Basic usage
* ```ts
* import { copy } from "https://deno.land/std@$STD_VERSION/bytes/copy.ts";
*
* const src = new Uint8Array([9, 8, 7]);
* const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);
* console.log(copy(src, dst)); // 3
* console.log(dst); // [9, 8, 7, 3, 4, 5]
*
* copy(src, dst); // 3
* dst; // Uint8Array(6) [9, 8, 7, 3, 4, 5]
* ```
*
* @example Copy with offset
* ```ts
* import { copy } from "https://deno.land/std@$STD_VERSION/bytes/copy.ts";
*
* const src = new Uint8Array([1, 1, 1, 1]);
* const dst = new Uint8Array([0, 0, 0, 0]);
* console.log(copy(src, dst, 1)); // 3
* console.log(dst); // [0, 1, 1, 1]
*
* copy(src, dst, 1); // 3
* dst; // Uint8Array(4) [0, 1, 1, 1]
* ```
* Defining an offset will start copying at the specified index in the
* destination array.
*/
export function copy(src: Uint8Array, dst: Uint8Array, off = 0): number {
off = Math.max(0, Math.min(off, dst.byteLength));
const dstBytesAvailable = dst.byteLength - off;
export function copy(src: Uint8Array, dst: Uint8Array, offset = 0): number {
offset = Math.max(0, Math.min(offset, dst.byteLength));
const dstBytesAvailable = dst.byteLength - offset;
if (src.byteLength > dstBytesAvailable) {
src = src.subarray(0, dstBytesAvailable);
}
dst.set(src, off);
dst.set(src, offset);
return src.byteLength;
}

17
bytes/ends_with.ts
View File

@ -1,16 +1,25 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Returns true if the suffix array appears at the end of the source array,
* false otherwise.
/**
* Returns `true` if the suffix array appears at the end of the source array,
* `false` otherwise.
*
* The complexity of this function is O(suffix.length).
* The complexity of this function is `O(suffix.length)`.
*
* @param source Source array to check.
* @param suffix Suffix array to check for.
* @returns `true` if the suffix array appears at the end of the source array,
* `false` otherwise.
*
* @example Basic usage
* ```ts
* import { endsWith } from "https://deno.land/std@$STD_VERSION/bytes/ends_with.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const suffix = new Uint8Array([1, 2, 3]);
* console.log(endsWith(source, suffix)); // true
*
* endsWith(source, suffix); // true
* ```
*/
export function endsWith(source: Uint8Array, suffix: Uint8Array): boolean {

40
bytes/equals.ts
View File

@ -1,10 +1,14 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Check whether binary arrays are equal to each other using 8-bit comparisons.
/**
* Check whether byte slices are equal to each other using 8-bit comparisons.
*
* @param a First array to check equality
* @param b Second array to check equality
* @returns `true` if the arrays are equal, `false` otherwise
*
* @private
* @param a first array to check equality
* @param b second array to check equality
*/
function equalsNaive(a: Uint8Array, b: Uint8Array): boolean {
for (let i = 0; i < b.length; i++) {
@ -13,10 +17,13 @@ function equalsNaive(a: Uint8Array, b: Uint8Array): boolean {
return true;
}
/** Check whether binary arrays are equal to each other using 32-bit comparisons.
/** Check whether byte slices are equal to each other using 32-bit comparisons.
*
* @param a First array to check equality.
* @param b Second array to check equality.
* @returns `true` if the arrays are equal, `false` otherwise.
*
* @private
* @param a first array to check equality
* @param b second array to check equality
*/
function equals32Bit(a: Uint8Array, b: Uint8Array): boolean {
const len = a.length;
@ -32,9 +39,24 @@ function equals32Bit(a: Uint8Array, b: Uint8Array): boolean {
return true;
}
/** Check whether binary arrays are equal to each other.
* @param a first array to check equality
* @param b second array to check equality
/**
* Check whether byte slices are equal to each other.
*
* @param a First array to check equality.
* @param b Second array to check equality.
* @returns `true` if the arrays are equal, `false` otherwise.
*
* @example Basic usage
* ```ts
* import { equals } from "https://deno.land/std@$STD_VERSION/bytes/equals.ts";
*
* const a = new Uint8Array([1, 2, 3]);
* const b = new Uint8Array([1, 2, 3]);
* const c = new Uint8Array([4, 5, 6]);
*
* equals(a, b); // true
* equals(b, c); // false
* ```
*/
export function equals(a: Uint8Array, b: Uint8Array): boolean {
if (a.length !== b.length) {

30
bytes/includes_needle.ts
View File

@ -3,20 +3,38 @@
import { indexOfNeedle } from "./index_of_needle.ts";
/** Returns true if the source array contains the needle array, false otherwise.
/**
* Determines whether the source array contains the needle array.
*
* A start index can be specified as the third argument that begins the search
* at that given index. The start index defaults to the beginning of the array.
* The complexity of this function is `O(source.length * needle.length)`.
*
* The complexity of this function is O(source.length * needle.length).
* @param source Source array to check.
* @param needle Needle array to check for.
* @param start Start index in the source array to begin the search. Defaults to
* 0.
* @returns `true` if the source array contains the needle array, `false`
* otherwise.
*
* @example Basic usage
* ```ts
* import { includesNeedle } from "https://deno.land/std@$STD_VERSION/bytes/includes_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
* console.log(includesNeedle(source, needle)); // true
* console.log(includesNeedle(source, needle, 6)); // false
*
* includesNeedle(source, needle); // true
* ```
*
* @example Start index
* ```ts
* import { includesNeedle } from "https://deno.land/std@$STD_VERSION/bytes/includes_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
*
* includesNeedle(source, needle, 6); // false
* ```
* The search will start at the specified index in the source array.
*/
export function includesNeedle(
source: Uint8Array,

31
bytes/index_of_needle.ts
View File

@ -1,21 +1,44 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Returns the index of the first occurrence of the needle array in the source
/**
* Returns the index of the first occurrence of the needle array in the source
* array, or -1 if it is not present.
*
* A start index can be specified as the third argument that begins the search
* at that given index. The start index defaults to the start of the array.
*
* The complexity of this function is O(source.length * needle.length).
* The complexity of this function is `O(source.length * needle.length)`.
*
* @param source Source array to check.
* @param needle Needle array to check for.
* @param start Start index in the source array to begin the search. Defaults to
* 0.
*
* @example Basic usage
* ```ts
* import { indexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
* console.log(indexOfNeedle(source, needle)); // 1
* console.log(indexOfNeedle(source, needle, 2)); // 3
* const notNeedle = new Uint8Array([5, 0]);
*
* indexOfNeedle(source, needle); // 1
* indexOfNeedle(source, notNeedle); // -1
* ```
*
* @example Start index
* ```ts
* import { indexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
*
* indexOfNeedle(source, needle, 2); // 3
* indexOfNeedle(source, needle, 6); // -1
* ```
* Defining a start index will begin the search at the specified index in the
* source array.
*/
export function indexOfNeedle(
source: Uint8Array,

32
bytes/last_index_of_needle.ts
View File

@ -1,21 +1,41 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Returns the index of the last occurrence of the needle array in the source
/**
* Returns the index of the last occurrence of the needle array in the source
* array, or -1 if it is not present.
*
* A start index can be specified as the third argument that begins the search
* at that given index. The start index defaults to the end of the array.
* The complexity of this function is `O(source.length * needle.length)`.
*
* The complexity of this function is O(source.length * needle.length).
* @param source Source array to check.
* @param needle Needle array to check for.
* @param start Start index in the source array to begin the search. Defaults to
* the end of the array.
*
* @example Basic usage
* ```ts
* import { lastIndexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/last_index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
* console.log(lastIndexOfNeedle(source, needle)); // 5
* console.log(lastIndexOfNeedle(source, needle, 4)); // 3
* const notNeedle = new Uint8Array([5, 0]);
*
* lastIndexOfNeedle(source, needle); // 5
* lastIndexOfNeedle(source, notNeedle); // -1
* ```
*
* @example Start index
* ```ts
* import { lastIndexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/last_index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
*
* lastIndexOfNeedle(source, needle, 2); // 1
* lastIndexOfNeedle(source, needle, 6); // 3
* ```
* Defining a start index will begin the search at the specified index in the
* source array.
*/
export function lastIndexOfNeedle(
source: Uint8Array,

130
bytes/mod.ts
View File

@ -2,8 +2,13 @@
// This module is browser compatible.
/**
* Provides helper functions to manipulate `Uint8Array` byte slices that are not
* included on the `Uint8Array` prototype.
* Helper functions for working with
* {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array | Uint8Array}
* byte slices.
*
* ## Concatenate byte slices
*
* {@linkcode concat} concatenates an array of byte slices into a single slice.
*
* ```ts
* import { concat } from "https://deno.land/std@$STD_VERSION/bytes/concat.ts";
@ -13,6 +18,127 @@
* concat([a, b]); // Uint8Array(6) [ 0, 1, 2, 3, 4, 5 ]
* ```
*
* ## Copy byte slices
*
* {@linkcode copy} copies bytes from the `src` array to the `dst` array and
* returns the number of bytes copied.
*
* ```ts
* import { copy } from "https://deno.land/std@$STD_VERSION/bytes/copy.ts";
*
* const src = new Uint8Array([9, 8, 7]);
* const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);
*
* copy(src, dst); // 3
* dst; // Uint8Array(6) [9, 8, 7, 3, 4, 5]
* ```
*
* ## Check if a byte slice ends with another byte slice
*
* {@linkcode endsWith} returns `true` if the suffix array appears at the end of
* the source array, `false` otherwise.
*
* ```ts
* import { endsWith } from "https://deno.land/std@$STD_VERSION/bytes/ends_with.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const suffix = new Uint8Array([1, 2, 3]);
*
* endsWith(source, suffix); // true
* ```
*
* ## Check if two byte slices are equal
*
* {@linkcode equals} checks whether byte slices are equal to each other.
*
* ```ts
* import { equals } from "https://deno.land/std@$STD_VERSION/bytes/equals.ts";
*
* const a = new Uint8Array([1, 2, 3]);
* const b = new Uint8Array([1, 2, 3]);
* const c = new Uint8Array([4, 5, 6]);
*
* equals(a, b); // true
* equals(b, c); // false
* ```
*
* ## Check if a byte slice includes another byte slice
*
* {@linkcode includesNeedle} determines whether the source array contains the
* needle array.
*
* ```ts
* import { includesNeedle } from "https://deno.land/std@$STD_VERSION/bytes/includes_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
*
* includesNeedle(source, needle); // true
* ```
*
* ## Find the index of a byte slice in another byte slice
*
* {@linkcode indexOfNeedle} returns the index of the first occurrence of the
* needle array in the source array, or -1 if it is not present.
*
* ```ts
* import { indexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
* const notNeedle = new Uint8Array([5, 0]);
*
* indexOfNeedle(source, needle); // 1
* indexOfNeedle(source, notNeedle); // -1
* ```
*
* ## Find the last index of a byte slice in another byte slice
*
* {@linkcode lastIndexOfNeedle} returns the index of the last occurrence of the
* needle array in the source array, or -1 if it is not present.
*
* ```ts
* import { lastIndexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/last_index_of_needle.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const needle = new Uint8Array([1, 2]);
* const notNeedle = new Uint8Array([5, 0]);
*
* lastIndexOfNeedle(source, needle); // 5
* lastIndexOfNeedle(source, notNeedle); // -1
* ```
*
* ## Repeat a byte slice
*
* {@linkcode repeat} returns a new byte slice composed of `count` repetitions
* of the `source` array.
*
* ```ts
* import { repeat } from "https://deno.land/std@$STD_VERSION/bytes/repeat.ts";
*
* const source = new Uint8Array([0, 1, 2]);
*
* repeat(source, 3); // Uint8Array(9) [0, 1, 2, 0, 1, 2, 0, 1, 2]
*
* repeat(source, 0); // Uint8Array(0) []
*
* repeat(source, -1); // Throws `RangeError`
* ```
*
* ## Check if a byte slice starts with another byte slice
*
* {@linkcode startsWith} returns `true` if the prefix array appears at the start
* of the source array, `false` otherwise.
*
* ```ts
* import { startsWith } from "https://deno.land/std@$STD_VERSION/bytes/starts_with.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const prefix = new Uint8Array([0, 1, 2]);
*
* startsWith(source, prefix); // true
* ```
*
* @module
*/

19
bytes/repeat.ts
View File

@ -2,17 +2,28 @@
// This module is browser compatible.
import { copy } from "./copy.ts";
/** Returns a new Uint8Array composed of `count` repetitions of the `source`
/**
* Returns a new byte slice composed of `count` repetitions of the `source`
* array.
*
* If `count` is negative, a `RangeError` is thrown.
*
* @param source Source array to repeat.
* @param count Number of times to repeat the source array.
* @returns A new byte slice composed of `count` repetitions of the `source`
* array.
*
* @example Basic usage
* ```ts
* import { repeat } from "https://deno.land/std@$STD_VERSION/bytes/repeat.ts";
*
* const source = new Uint8Array([0, 1, 2]);
* console.log(repeat(source, 3)); // [0, 1, 2, 0, 1, 2, 0, 1, 2]
* console.log(repeat(source, 0)); // []
* console.log(repeat(source, -1)); // RangeError
*
* repeat(source, 3); // Uint8Array(9) [0, 1, 2, 0, 1, 2, 0, 1, 2]
*
* repeat(source, 0); // Uint8Array(0) []
*
* repeat(source, -1); // Throws `RangeError`
* ```
*/
export function repeat(source: Uint8Array, count: number): Uint8Array {

17
bytes/starts_with.ts
View File

@ -1,16 +1,25 @@
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
// This module is browser compatible.
/** Returns true if the prefix array appears at the start of the source array,
* false otherwise.
/**
* Returns `true` if the prefix array appears at the start of the source array,
* `false` otherwise.
*
* The complexity of this function is O(prefix.length).
* The complexity of this function is `O(prefix.length)`.
*
* @param source Source array to check.
* @param prefix Prefix array to check for.
* @returns `true` if the prefix array appears at the start of the source array,
* `false` otherwise.
*
* @example Basic usage
* ```ts
* import { startsWith } from "https://deno.land/std@$STD_VERSION/bytes/starts_with.ts";
*
* const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
* const prefix = new Uint8Array([0, 1, 2]);
* console.log(startsWith(source, prefix)); // true
*
* startsWith(source, prefix); // true
* ```
*/
export function startsWith(source: Uint8Array, prefix: Uint8Array): boolean {