Unify iterate functions

Author: smikitky

api-reference.md

@@ -25,7 +25,6 @@
 - [`stringify()`](#function-stringify)
 - [`flatten()`](#function-flatten)
 - [`iterate()`](#function-iterate)
-- [`iterateDesc()`](#function-iteratedesc)
 
 ---
 
@@ -469,12 +468,16 @@ flatten([[-1, 1], [7, 9]]); // [-1, 0, 1, 7, 8, 9]
 ## function: `iterate`
 
 ```ts
-iterate(data: MultiIntegerRange): Iterable<number>
+iterate(
+  data: MultiIntegerRange,
+  options: IterateOptions = {}
+): Iterable<number>
 ```
 
 | Param | Description |
 |-|-|
 | `data` | The normalized MultiIntegerRange to iterate over. |
+| `options` | Pass `{ descending: true }` to iterate in descending order. |
 | Returns | An Iterable object. |
 
 Returns an Iterable with which you can use `for-of` or the spread syntax.
@@ -483,27 +486,6 @@ Returns an Iterable with which you can use `for-of` or the spread syntax.
 
 ```ts
 Array.from(iterate([[1, 3], [7, 9]])); // [1, 2, 3, 7, 8, 9]
-[...iterate([[-1, 1]])]; // [-1, 0, 1]
-```
-
----
-
-## function: `iterateDesc`
-
-```ts
-iterateDesc(data: MultiIntegerRange): Iterable<number>
-```
-
-| Param | Description |
-|-|-|
-| `data` | The normalized MultiIntegerRange to iterate over. |
-| Returns | An Iterable object. |
-
-Like `iterate`, but iterates in descending order.
-
-### Example
-
-```ts
-Array.from(iterateDesc([[1, 3], [7, 9]])); // [9, 8, 7, 3, 2, 1]
-[...iterateDesc([[-1, 1]])]; // [1, 0, -1]
+Array.from(iterate([[1, 3], [7, 9]], { descending: true })); // [9, 8, 7, 3, 2, 1]
+[...iterate([[-1, 2]])]; // [-1, 0, 1, 2]
 ```

src/fp.test.ts

@@ -456,19 +456,16 @@ test('flatten', () => {
 });
 
 test('iterate', () => {
-  expect([...mr.iterate([[1, 5]])]).toEqual([1, 2, 3, 4, 5]);
-  expect(Array.from(mr.iterate(parseAll('(-8)-(-6),2,5-7')))).toEqual([
-    -8, -7, -6, 2, 5, 6, 7
-  ]);
-  expect([...mr.iterate([])]).toEqual([]);
-  expect(() => mr.iterate(parseAll('3-'))).toThrow(RangeError);
-});
+  expect([...mr.iterate([[1, 3]])]).toEqual([1, 2, 3]);
+  expect([...mr.iterate([[1, 3]], { descending: true })]).toEqual([3, 2, 1]);
 
-test('iterateDesc', () => {
-  expect([...mr.iterateDesc([[1, 5]])]).toEqual([5, 4, 3, 2, 1]);
-  expect(Array.from(mr.iterateDesc(parseAll('(-8)-(-6),2,5-7')))).toEqual([
+  const r = parseAll('(-8)-(-6),2,5-7');
+  expect(Array.from(mr.iterate(r))).toEqual([-8, -7, -6, 2, 5, 6, 7]);
+  expect(Array.from(mr.iterate(r, { descending: true }))).toEqual([
     7, 6, 5, 2, -6, -7, -8
   ]);
-  expect([...mr.iterateDesc([])]).toEqual([]);
-  expect(() => mr.iterateDesc(parseAll('3-'))).toThrow(RangeError);
+
+  expect([...mr.iterate([])]).toEqual([]);
+  expect([...mr.iterate([], { descending: true })]).toEqual([]);
+  expect(() => mr.iterate(parseAll('3-'))).toThrow(RangeError);
 });

src/fp.ts

@@ -545,64 +545,41 @@ export const flatten = (data: MIR): number[] => {
   return result;
 };
 
+export interface IterateOptions {
+  readonly descending?: boolean;
+}
+
 /**
  * Returns an Iterable with which you can use `for-of` or the spread syntax.
  * @param data - The normalized MultiIntegerRange to iterate over.
+ * @param options - Pass `{ descending: true }` to iterate in descending order.
  * @returns An Iterable object.
  * @example
  * Array.from(iterate([[1, 3], [7, 9]])); // [1, 2, 3, 7, 8, 9]
- * [...iterate([[-1, 1]])]; // [-1, 0, 1]
+ * Array.from(iterate([[1, 3], [7, 9]], { descending: true })); // [9, 8, 7, 3, 2, 1]
+ * [...iterate([[-1, 2]])]; // [-1, 0, 1, 2]
  */
-export const iterate = (data: MIR): Iterable<number> => {
-  if (isUnbounded(data)) {
+export const iterate = (
+  data: MIR,
+  options: IterateOptions = {}
+): Iterable<number> => {
+  const { descending = false } = options;
+  if (isUnbounded(data))
     throw new RangeError('Unbounded ranges cannot be iterated over');
-  }
-  return {
-    [Symbol.iterator]: () => {
-      let i = 0,
-        curRange: Range = data[i],
-        j = curRange ? curRange[0] : undefined;
-      return {
-        next: () => {
-          if (!curRange || j === undefined)
-            return { done: true, value: undefined };
-          const ret = j;
-          if (++j > curRange[1]) {
-            curRange = data[++i];
-            j = curRange ? curRange[0] : undefined;
-          }
-          return { done: false, value: ret };
-        }
-      };
-    }
-  };
-};
 
-/**
- * Like `iterate`, but iterates in descending order.
- * @param data - The normalized MultiIntegerRange to iterate over.
- * @returns An Iterable object.
- * @example
- * Array.from(iterateDesc([[1, 3], [7, 9]])); // [9, 8, 7, 3, 2, 1]
- * [...iterateDesc([[-1, 1]])]; // [1, 0, -1]
- */
-export const iterateDesc = (data: MIR): Iterable<number> => {
-  if (isUnbounded(data)) {
-    throw new RangeError('Unbounded ranges cannot be iterated over');
-  }
   return {
     [Symbol.iterator]: () => {
-      let i = data.length - 1,
+      let i = descending ? data.length - 1 : 0,
         curRange: Range = data[i],
-        j = curRange ? curRange[1] : undefined;
+        j = curRange ? (descending ? curRange[1] : curRange[0]) : undefined;
       return {
         next: () => {
           if (!curRange || j === undefined)
             return { done: true, value: undefined };
           const ret = j;
-          if (--j < curRange[0]) {
-            curRange = data[--i];
-            j = curRange ? curRange[1] : undefined;
+          if (descending ? --j < curRange[0] : ++j > curRange[1]) {
+            curRange = data[descending ? --i : ++i];
+            j = curRange ? (descending ? curRange[1] : curRange[0]) : undefined;
           }
           return { done: false, value: ret };
         }