refactor(bytes): rename contains to includes with optional argume…

…nt `fromIndex` (#1133)

bytes/README.md

@@ -106,20 +106,20 @@ concat(
 ); // => returns Uint8Array(8) [ 1, 2, 3, 4, 5, 6, 7, 8 ]
 ```
 
-## contains
+## includes
 
-Checks that a given binary array contains a sequence corresponding to a pattern
+Checks that a given binary array includes a sequence corresponding to a pattern
 array.
 
 ```typescript
-import { contains } from "https://deno.land/std@$STD_VERSION/bytes/mod.ts";
+import { includes } from "https://deno.land/std@$STD_VERSION/bytes/mod.ts";
 
-contains(
+includes(
   new Uint8Array([1, 2, 0, 1, 2, 0, 2, 1, 3]),
   new Uint8Array([0, 1, 2]),
 ); // => returns true
 
-contains(
+includes(
   new Uint8Array([1, 2, 0, 1, 2, 0, 2, 1, 3]),
   new Uint8Array([2, 2]),
 ); // => returns false

bytes/mod.ts

@@ -1,35 +1,32 @@
 // Copyright 2018-2021 the Deno authors. All rights reserved. MIT license.
 
-/** Find first index of binary pattern from source. If not found, then return -1
- * @param source source array
- * @param pat pattern to find in source array
- * @param start the index to start looking in the source
- */
+/** Returns the index of the first occurrence of the pattern array in the source
+ * array, or -1 if it is not present. */
 export function indexOf(
   source: Uint8Array,
-  pat: Uint8Array,
-  start = 0,
+  pattern: Uint8Array,
+  fromIndex = 0,
 ): number {
-  if (start >= source.length) {
+  if (fromIndex >= source.length) {
     return -1;
   }
-  if (start < 0) {
-    start = 0;
+  if (fromIndex < 0) {
+    fromIndex = Math.max(0, source.length + fromIndex);
   }
-  const s = pat[0];
-  for (let i = start; i < source.length; i++) {
+  const s = pattern[0];
+  for (let i = fromIndex; i < source.length; i++) {
     if (source[i] !== s) continue;
     const pin = i;
     let matched = 1;
     let j = i;
-    while (matched < pat.length) {
+    while (matched < pattern.length) {
       j++;
-      if (source[j] !== pat[j - pin]) {
+      if (source[j] !== pattern[j - pin]) {
         break;
       }
       matched++;
     }
-    if (matched === pat.length) {
+    if (matched === pattern.length) {
       return pin;
     }
   }
@@ -162,12 +159,13 @@ export function concat(...buf: Uint8Array[]): Uint8Array {
   return output;
 }
 
-/** Check source array contains pattern array.
- * @param source source array
- * @param pat patter array
- */
-export function contains(source: Uint8Array, pat: Uint8Array): boolean {
-  return indexOf(source, pat) != -1;
+/** Determines whether the source array includes the pattern array. */
+export function includes(
+  source: Uint8Array,
+  pattern: Uint8Array,
+  fromIndex = 0,
+): boolean {
+  return indexOf(source, pattern, fromIndex) !== -1;
 }
 
 /**
@@ -188,3 +186,6 @@ export function copy(src: Uint8Array, dst: Uint8Array, off = 0): number {
   dst.set(src, off);
   return src.byteLength;
 }
+
+/** @deprecated */
+export { includes as contains };

bytes/test.ts

@@ -2,10 +2,10 @@
 
 import {
   concat,
-  contains,
   copy,
   endsWith,
   equals,
+  includes,
   indexOf,
   lastIndexOf,
   repeat,
@@ -55,6 +55,25 @@ Deno.test("[bytes] indexOf with start index 2", () => {
   assertEquals(i, -1);
 });
 
+Deno.test("[bytes] indexOf with start index < 0", () => {
+  assertEquals(
+    indexOf(
+      new Uint8Array([0, 1, 2, 0, 1, 2]),
+      new Uint8Array([0, 1]),
+      3,
+    ),
+    3,
+  );
+  assertEquals(
+    indexOf(
+      new Uint8Array([0, 1, 2, 1, 1, 2]),
+      new Uint8Array([0, 1]),
+      3,
+    ),
+    -1,
+  );
+});
+
 Deno.test("[bytes] lastIndexOf1", () => {
   const i = lastIndexOf(
     new Uint8Array([0, 1, 2, 0, 1, 2, 0, 1, 3]),
@@ -187,13 +206,16 @@ Deno.test("[bytes] concat multiple arrays", () => {
   assert(u2 !== joined);
 });
 
-Deno.test("[bytes] contains", () => {
+Deno.test("[bytes] includes", () => {
   const encoder = new TextEncoder();
   const source = encoder.encode("deno.land");
   const pattern = encoder.encode("deno");
-  assert(contains(source, pattern));
 
-  assert(contains(new Uint8Array([0, 1, 2, 3]), new Uint8Array([2, 3])));
+  assert(includes(source, pattern));
+  assert(includes(new Uint8Array([0, 1, 2, 3]), new Uint8Array([2, 3])));
+
+  assert(includes(source, pattern, -10));
+  assert(!includes(source, pattern, -1));
 });
 
 Deno.test("[bytes] copy", function (): void {