@visulima/bytes 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,287 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * Concatenate an array of byte slices into a single slice.
+ *
+ * @param buffers Array of byte slices to concatenate.
+ * @returns A new byte slice containing all the input slices concatenated.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { concat } from "@std/bytes/concat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = new Uint8Array([0, 1, 2]);
+ * const b = new Uint8Array([3, 4, 5]);
+ *
+ * assertEquals(concat([a, b]), new Uint8Array([0, 1, 2, 3, 4, 5]));
+ * ```
+ */ declare function concat(buffers: readonly Uint8Array[]): Uint8Array_;
+
+/**
+ * Copy bytes from the source array to the destination array and returns the
+ * number of bytes copied.
+ *
+ * If the source array is larger than what the `dst` array can hold, only the
+ * amount of bytes that fit in the `dst` array are copied.
+ *
+ * @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.
+ * @returns Number of bytes copied.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { copy } from "@std/bytes/copy";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const src = new Uint8Array([9, 8, 7]);
+ * const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);
+ *
+ * assertEquals(copy(src, dst), 3);
+ * assertEquals(dst, new Uint8Array([9, 8, 7, 3, 4, 5]));
+ * ```
+ *
+ * @example Copy with offset
+ * ```ts
+ * import { copy } from "@std/bytes/copy";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const src = new Uint8Array([1, 1, 1, 1]);
+ * const dst = new Uint8Array([0, 0, 0, 0]);
+ *
+ * assertEquals(copy(src, dst, 1), 3);
+ * assertEquals(dst, new Uint8Array([0, 1, 1, 1]));
+ * ```
+ * Defining an offset will start copying at the specified index in the
+ * destination array.
+ */ declare function copy(src: Uint8Array, dst: Uint8Array, offset?: number): number;
+
+/**
+ * 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)`.
+ *
+ * @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 "@std/bytes/ends-with";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const suffix = new Uint8Array([1, 2, 3]);
+ *
+ * assertEquals(endsWith(source, suffix), true);
+ * ```
+ */ declare function endsWith(source: Uint8Array, suffix: Uint8Array): boolean;
+
+/**
+ * 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 "@std/bytes/equals";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * const c = new Uint8Array([4, 5, 6]);
+ *
+ * assertEquals(equals(a, b), true);
+ * assertEquals(equals(a, c), false);
+ * ```
+ */ declare function equals(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Determines whether the source array contains the needle array.
+ *
+ * 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 "@std/bytes/includes-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(includesNeedle(source, needle), true);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { includesNeedle } from "@std/bytes/includes-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(includesNeedle(source, needle, 3), true);
+ * assertEquals(includesNeedle(source, needle, 6), false);
+ * ```
+ * The search will start at the specified index in the source array.
+ */ declare function includesNeedle(source: Uint8Array, needle: Uint8Array, start?: number): boolean;
+
+/**
+ * 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)`.
+ *
+ * @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 Index of the first occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { indexOfNeedle } from "@std/bytes/index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * assertEquals(indexOfNeedle(source, needle), 1);
+ * assertEquals(indexOfNeedle(source, notNeedle), -1);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { indexOfNeedle } from "@std/bytes/index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(indexOfNeedle(source, needle, 2), 3);
+ * assertEquals(indexOfNeedle(source, needle, 6), -1);
+ * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
+ */ declare function indexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
+
+/**
+ * Returns the index of the last occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * 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
+ * `source.length - 1`.
+ * @returns Index of the last occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { lastIndexOfNeedle } from "@std/bytes/last-index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * assertEquals(lastIndexOfNeedle(source, needle), 5);
+ * assertEquals(lastIndexOfNeedle(source, notNeedle), -1);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { lastIndexOfNeedle } from "@std/bytes/last-index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(lastIndexOfNeedle(source, needle, 2), 1);
+ * assertEquals(lastIndexOfNeedle(source, needle, 6), 5);
+ * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
+ */ declare function lastIndexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
+
+/**
+ * Returns a new byte slice composed of `count` repetitions of the `source`
+ * array.
+ *
+ * @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 "@std/bytes/repeat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(repeat(source, 3), new Uint8Array([0, 1, 2, 0, 1, 2, 0, 1, 2]));
+ * ```
+ *
+ * @example Zero count
+ * ```ts
+ * import { repeat } from "@std/bytes/repeat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(repeat(source, 0), new Uint8Array());
+ * ```
+ */ declare function repeat(source: Uint8Array, count: number): Uint8Array_;
+
+/**
+ * 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)`.
+ *
+ * @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 "@std/bytes/starts-with";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const prefix = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(startsWith(source, prefix), true);
+ * ```
+ */ declare function startsWith(source: Uint8Array, prefix: Uint8Array): boolean;
+
+declare const bufferToUint8Array: (buf: Buffer) => Uint8Array;
+declare const isUint8Array: (x: unknown) => x is Uint8Array;
+declare const asciiToUint8Array: (txt: TemplateStringsArray | string | [string]) => Uint8Array;
+declare const utf8ToUint8Array: (txt: TemplateStringsArray | [string] | string) => Uint8Array;
+declare const toUint8Array: (data: unknown) => Uint8Array;
+
+export { asciiToUint8Array, bufferToUint8Array, concat, copy, endsWith, equals, includesNeedle, indexOfNeedle, isUint8Array, lastIndexOfNeedle, repeat, startsWith, toUint8Array, utf8ToUint8Array };
+export type { Uint8Array_ };

package/dist/index.d.mts

@@ -0,0 +1,287 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * Concatenate an array of byte slices into a single slice.
+ *
+ * @param buffers Array of byte slices to concatenate.
+ * @returns A new byte slice containing all the input slices concatenated.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { concat } from "@std/bytes/concat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = new Uint8Array([0, 1, 2]);
+ * const b = new Uint8Array([3, 4, 5]);
+ *
+ * assertEquals(concat([a, b]), new Uint8Array([0, 1, 2, 3, 4, 5]));
+ * ```
+ */ declare function concat(buffers: readonly Uint8Array[]): Uint8Array_;
+
+/**
+ * Copy bytes from the source array to the destination array and returns the
+ * number of bytes copied.
+ *
+ * If the source array is larger than what the `dst` array can hold, only the
+ * amount of bytes that fit in the `dst` array are copied.
+ *
+ * @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.
+ * @returns Number of bytes copied.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { copy } from "@std/bytes/copy";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const src = new Uint8Array([9, 8, 7]);
+ * const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);
+ *
+ * assertEquals(copy(src, dst), 3);
+ * assertEquals(dst, new Uint8Array([9, 8, 7, 3, 4, 5]));
+ * ```
+ *
+ * @example Copy with offset
+ * ```ts
+ * import { copy } from "@std/bytes/copy";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const src = new Uint8Array([1, 1, 1, 1]);
+ * const dst = new Uint8Array([0, 0, 0, 0]);
+ *
+ * assertEquals(copy(src, dst, 1), 3);
+ * assertEquals(dst, new Uint8Array([0, 1, 1, 1]));
+ * ```
+ * Defining an offset will start copying at the specified index in the
+ * destination array.
+ */ declare function copy(src: Uint8Array, dst: Uint8Array, offset?: number): number;
+
+/**
+ * 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)`.
+ *
+ * @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 "@std/bytes/ends-with";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const suffix = new Uint8Array([1, 2, 3]);
+ *
+ * assertEquals(endsWith(source, suffix), true);
+ * ```
+ */ declare function endsWith(source: Uint8Array, suffix: Uint8Array): boolean;
+
+/**
+ * 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 "@std/bytes/equals";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * const c = new Uint8Array([4, 5, 6]);
+ *
+ * assertEquals(equals(a, b), true);
+ * assertEquals(equals(a, c), false);
+ * ```
+ */ declare function equals(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Determines whether the source array contains the needle array.
+ *
+ * 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 "@std/bytes/includes-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(includesNeedle(source, needle), true);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { includesNeedle } from "@std/bytes/includes-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(includesNeedle(source, needle, 3), true);
+ * assertEquals(includesNeedle(source, needle, 6), false);
+ * ```
+ * The search will start at the specified index in the source array.
+ */ declare function includesNeedle(source: Uint8Array, needle: Uint8Array, start?: number): boolean;
+
+/**
+ * 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)`.
+ *
+ * @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 Index of the first occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { indexOfNeedle } from "@std/bytes/index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * assertEquals(indexOfNeedle(source, needle), 1);
+ * assertEquals(indexOfNeedle(source, notNeedle), -1);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { indexOfNeedle } from "@std/bytes/index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(indexOfNeedle(source, needle, 2), 3);
+ * assertEquals(indexOfNeedle(source, needle, 6), -1);
+ * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
+ */ declare function indexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
+
+/**
+ * Returns the index of the last occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * 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
+ * `source.length - 1`.
+ * @returns Index of the last occurrence of the needle array in the source
+ * array, or -1 if it is not present.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { lastIndexOfNeedle } from "@std/bytes/last-index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * assertEquals(lastIndexOfNeedle(source, needle), 5);
+ * assertEquals(lastIndexOfNeedle(source, notNeedle), -1);
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { lastIndexOfNeedle } from "@std/bytes/last-index-of-needle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * assertEquals(lastIndexOfNeedle(source, needle, 2), 1);
+ * assertEquals(lastIndexOfNeedle(source, needle, 6), 5);
+ * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
+ */ declare function lastIndexOfNeedle(source: Uint8Array, needle: Uint8Array, start?: number): number;
+
+/**
+ * Returns a new byte slice composed of `count` repetitions of the `source`
+ * array.
+ *
+ * @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 "@std/bytes/repeat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(repeat(source, 3), new Uint8Array([0, 1, 2, 0, 1, 2, 0, 1, 2]));
+ * ```
+ *
+ * @example Zero count
+ * ```ts
+ * import { repeat } from "@std/bytes/repeat";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(repeat(source, 0), new Uint8Array());
+ * ```
+ */ declare function repeat(source: Uint8Array, count: number): Uint8Array_;
+
+/**
+ * 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)`.
+ *
+ * @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 "@std/bytes/starts-with";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const prefix = new Uint8Array([0, 1, 2]);
+ *
+ * assertEquals(startsWith(source, prefix), true);
+ * ```
+ */ declare function startsWith(source: Uint8Array, prefix: Uint8Array): boolean;
+
+declare const bufferToUint8Array: (buf: Buffer) => Uint8Array;
+declare const isUint8Array: (x: unknown) => x is Uint8Array;
+declare const asciiToUint8Array: (txt: TemplateStringsArray | string | [string]) => Uint8Array;
+declare const utf8ToUint8Array: (txt: TemplateStringsArray | [string] | string) => Uint8Array;
+declare const toUint8Array: (data: unknown) => Uint8Array;
+
+export { asciiToUint8Array, bufferToUint8Array, concat, copy, endsWith, equals, includesNeedle, indexOfNeedle, isUint8Array, lastIndexOfNeedle, repeat, startsWith, toUint8Array, utf8ToUint8Array };
+export type { Uint8Array_ };