feat(pkg:string): added API String.toChunksBackward

Author: fenying

packages/partials/string/src/Functions/ToChunks.test.ts

@@ -1,6 +1,6 @@
 import * as NodeTest from 'node:test';
 import * as NodeAssert from 'node:assert';
-import { toChunks} from './ToChunks';
+import { toChunks, toChunksBackward} from './ToChunks';
 
 NodeTest.describe('Function String.toChunks', () => {
 
@@ -26,5 +26,35 @@ NodeTest.describe('Function String.toChunks', () => {
         NodeAssert.deepStrictEqual(toChunks('abcdefghij', 5), ['abcde', 'fghij']);
         NodeAssert.deepStrictEqual(toChunks('abcdefghij', 10), ['abcdefghij']);
         NodeAssert.deepStrictEqual(toChunks('abcdefghi', 10), ['abcdefghi']);
+        NodeAssert.deepStrictEqual(toChunks('abcdefghij', 1), ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']);
+    });
+});
+
+NodeTest.describe('Function String.toChunksBackward', () => {
+
+    NodeTest.it('Should return empty if the string is empty', () => {
+
+        NodeAssert.deepStrictEqual(toChunksBackward('', 1), []);
+        NodeAssert.deepStrictEqual(toChunksBackward('', 1000), []);
+    });
+
+    NodeTest.it('Should throw exception if chunk size is not a positive integer', () => {
+
+        NodeAssert.throws(() => toChunksBackward('abc', 0), RangeError);
+        NodeAssert.throws(() => toChunksBackward('abc', -1), RangeError);
+        NodeAssert.throws(() => toChunksBackward('abc', 1.5), RangeError);
+        NodeAssert.throws(() => toChunksBackward('abc', NaN), RangeError);
+        NodeAssert.throws(() => toChunksBackward('abc', Infinity), RangeError);
+    });
+
+    NodeTest.it('Should return chunks of the specified size', () => {
+
+        NodeAssert.deepStrictEqual(toChunksBackward('abcde', 2), ['a', 'bc', 'de']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghij', 3), ['a', 'bcd', 'efg', 'hij']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghij', 5), ['abcde', 'fghij']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghij', 10), ['abcdefghij']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghi', 10), ['abcdefghi']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghij', 1), ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']);
+        NodeAssert.deepStrictEqual(toChunksBackward('abcdefghij', 11), ['abcdefghij']);
     });
 });

packages/partials/string/src/Functions/ToChunks.ts

@@ -23,11 +23,16 @@
  * @param chunkSize The size of each chunk. Must be a positive integer.
  *
  * @returns An array of strings, each representing a chunk of the original string.
- * @throws RangeError if the chunk size is not a positive integer.
- * @example `toChunks('abcdefghij', 3)` returns `['abc', 'def', 'ghi', 'j']`
+ * @throws `RangeError` if the chunk size is not a positive integer.
+ * @example `toChunks('abcdefghij', 3) -> ['abc', 'def', 'ghi', 'j']`
  */
 export function toChunks(text: string, chunkSize: number): string[] {
 
+    if (chunkSize === 1) {
+
+        return text.split('');
+    }
+
     if (chunkSize <= 0 || !Number.isSafeInteger(chunkSize)) {
 
         throw new RangeError('Chunk size must be a positive integer.');
@@ -42,3 +47,39 @@ export function toChunks(text: string, chunkSize: number): string[] {
 
     return chunks;
 }
+
+/**
+ * This function splits a string into chunks of specified size.
+ * Different from `toChunks`, this function reverses the order of the chunks,
+ * which means the first chunk will contain the last characters of the string,
+ * when the input string is not a multiple of the chunk size,
+ *
+ * @param text      The string to be split into chunks.
+ * @param chunkSize The size of each chunk. Must be a positive integer.
+ *
+ * @returns An array of strings, each representing a chunk of the original string.
+ * @throws `RangeError` if the chunk size is not a positive integer.
+ * @example `toChunksBackward('abcdefghij', 3) -> ['a', 'bcd', 'efg', 'hij']`
+ */
+export function toChunksBackward(text: string, chunkSize: number): string[] {
+
+    if (chunkSize === 1) {
+
+        return text.split('');
+    }
+
+    if (chunkSize <= 0 || !Number.isSafeInteger(chunkSize)) {
+
+        throw new RangeError('Chunk size must be a positive integer.');
+    }
+
+    const chunks: string[] = new Array<string>(Math.ceil(text.length / chunkSize));
+    const length = text.length;
+
+    for (let i = length, o = chunks.length; i > 0; i -= chunkSize) {
+
+        chunks[--o] = text.slice(Math.max(0, i - chunkSize), i);
+    }
+
+    return chunks;
+}