feat(fjl): add charRange generator

packages/fjl/src/string/charRange.ts

@@ -0,0 +1,37 @@
+import {numRange} from "../number/numRange";
+
+const toCodePoint = (char: string): number => {
+  if (typeof char !== 'string' || Array.from(char).length !== 1) {
+    throw new Error(`Expected a single character.  Received: ${JSON.stringify(char)}`);
+  }
+  return char.codePointAt(0);
+};
+
+export const
+
+  /**
+   * Generator for the characters in a range (inclusive), stepping by code point.  Same semantics
+   * as `numRange`:  `step` is normalized to the range's direction, and `0` is an error.
+   *
+   * ```javascript
+   * Array.from(charRange('a', 'e'));    // ['a', 'b', 'c', 'd', 'e']
+   * Array.from(charRange('a', 'e', 2)); // ['a', 'c', 'e']
+   * Array.from(charRange('c', 'a'));    // ['c', 'b', 'a']
+   * ```
+   *
+   * @throws {Error} If `start` or `end` isn't a single character, or if `step` is `0`.
+   */
+  charRange = function* (start: string, end: string, step = 1): Generator<string, void> {
+    for (const codePoint of numRange(toCodePoint(start), toCodePoint(end), step)) {
+      yield String.fromCodePoint(codePoint);
+    }
+  },
+
+  /**
+   * Curried version of `charRange`.
+   */
+  $charRange = (start: string) =>
+    (end: string, step = 1): Generator<string, void> =>
+      charRange(start, end, step)
+
+;

packages/fjl/src/string/index.ts

@@ -8,6 +8,7 @@ import {randNatNum} from "../number";
 import {id} from "../function/id";
 
 export {split, $split};
+export * from './charRange';
 
 const newLineRegex = /[\n\r]/gm,
   spaceRegex = /[ \t]/gm,

packages/fjl/tests/string/test-charRange.ts

@@ -0,0 +1,47 @@
+import {charRange} from "../../src";
+
+const {stringify} = JSON;
+
+describe('#charRange', () => {
+  (<[Parameters<typeof charRange>, string[]][]>[
+    [['a', 'e'], ['a', 'b', 'c', 'd', 'e']],
+    [['a', 'e', 2], ['a', 'c', 'e']],
+    [['a', 'd', 2], ['a', 'c']],
+    [['c', 'a'], ['c', 'b', 'a']],
+    [['e', 'a', 2], ['e', 'c', 'a']],
+    [['e', 'a', -2], ['e', 'c', 'a']],
+    [['a', 'c', -1], ['a', 'b', 'c']],
+    [['a', 'a'], ['a']],
+    [['0', '3'], ['0', '1', '2', '3']],
+    [['😀', '😂'], ['😀', '😁', '😂']]
+  ])
+    .forEach(([args, expected]) => {
+      it(`charRange(${stringify(args)}) collects to ${stringify(expected)}`, () => {
+        expect(Array.from(charRange(...args))).toEqual(expected);
+      });
+    });
+
+  it('should be lazy', () => {
+    const gen = charRange('a', '\u{10FFFF}');
+    expect(gen.next().value).toEqual('a');
+    expect(gen.next().value).toEqual('b');
+  });
+
+  ([
+    ['', 'a'],
+    ['a', ''],
+    ['ab', 'c'],
+    ['a', 'bc'],
+    [null, 'a'],
+    ['a', undefined]
+  ] as [string, string][])
+    .forEach(([start, end]) => {
+      it(`should throw when given charRange(${stringify(start)}, ${stringify(end)})`, () => {
+        expect(() => Array.from(charRange(start, end))).toThrow();
+      });
+    });
+
+  it('should throw when `step` is `0`', () => {
+    expect(() => Array.from(charRange('a', 'c', 0))).toThrow();
+  });
+});

packages/fjl/tests/test-currying.ts

@@ -132,6 +132,7 @@ const
     },
 
     // string / _platform.string
+    $charRange: {cases: [{args: fixed('a', 'e'), finalize: takeFromGen(3)}]},
     $split: {cases: [{args: fixed(',', 'a,b,c')}]},
 
     // _platform.object