nmx.sudokugen.library 1.1.0 → 1.2.0

package/README.md

@@ -1,3 +1,5 @@
+![Sudoku Gen](https://raw.githubusercontent.com/newmediaxp/sudokugen/main/icon.png)
+
 # Sudoku Gen Library
 
 `sudoku` `javascript` `typescript` `library` `npm`
@@ -99,8 +101,31 @@ A square that is rule-clean but still wrong (`board[i] !== solution[i]`) returns
 
 | Function        | Signature                                         | Description                                                                                             |
 |-----------------|---------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| `getPuzzleCode` | `getPuzzleCode(grid: ArrayLike<number>): string`  | Encodes a grid as a puzzle code: one char per square (`0` blank, `1`-`9`, `A` = 10…), `.` between rows. |
-| `getPuzzleArr`  | `getPuzzleArr(code: string): number[]`            | Parses a puzzle code back into a grid array; unrecognised characters are ignored.                       |
+| `getPuzzleCode` | `getPuzzleCode(grid: ArrayLike<number>, encoding?: EncodingOption): string` | Encodes a grid as a puzzle code: one char per square (`0` blank, `1`-`9`, `A` = 10…), `.` between rows. With an `encoding`, writes in that one instead (default `All`). Throws a `RangeError` if a value doesn't fit the encoding. |
+| `getPuzzleArr`  | `getPuzzleArr(code: string, encoding?: EncodingOption): number[]` | Parses a puzzle code back into a grid array; unrecognised characters are ignored. The encoding can't be detected from the code, so pass the one it was written in (default `All`). |
+| `getSymbol`     | `getSymbol(value: number, encoding: EncodingOption): string` | The character one square value is written as.                                                 |
+| `maxRank`       | `maxRank(encoding: EncodingOption): number`       | The highest rank the encoding can write.                                                                |
+
+### `EncodingOption`
+
+Frozen character sets for puzzle codes. Blank is `0` in every one. Letters read in either case.
+
+| Value               | Values written as                              | Max rank |
+|---------------------|------------------------------------------------|----------|
+| `All`               | `1`-`9`, then `A`-`Z` (`A` = 10). The default. | 5        |
+| `AllMinusO`         | `1`-`9`, then `A`-`Z` without `O`              | 5        |
+| `DigitsOnly`        | `1`-`9`                                        | 3        |
+| `LettersOnly`       | `A`-`Z` (`A` = 1)                              | 5        |
+| `LettersOnlyMinusO` | `A`-`Z` without `O` (`A` = 1)                  | 5        |
+
+The minus-O sets skip `O` so it can't be misread as the blank `0`.
+
+```js
+import { EncodingOption, getPuzzleArr, getPuzzleCode } from "nmx.sudokugen.library";
+
+const a_letters = getPuzzleCode(a_sudoku.puzzle, EncodingOption.LettersOnly); // e.g. "CI0EF00BG.00AH0I0DE...."
+const a_grid    = getPuzzleArr(a_letters, EncodingOption.LettersOnly);       // read it back in the same encoding
+```
 
 ### Notes
 
@@ -132,6 +157,10 @@ A square that is rule-clean but still wrong (`board[i] !== solution[i]`) returns
 
     * None. Needs an ES2022 runtime: current browsers, Node.js 20 or later, Deno, Bun.
 
+* Used in
+
+    * Sudoku Gen web app [(link)](https://www.newmediaxp.com/app/sudokugen)
+
 * Other languages
 
     * C# library: [NMX.SudokuGen.Library](https://www.nuget.org/packages/NMX.SudokuGen.Library)
@@ -142,7 +171,7 @@ A square that is rule-clean but still wrong (`board[i] !== solution[i]`) returns
 
 * Source
 
-    * [GitHub](https://github.com/newmediaxp/sudokugen/tree/main/js/nmx.sudokugen.library)
+    * [GitHub](https://github.com/newmediaxp/sudokugen/tree/main/javascript/nmx.sudokugen.library)
 
 ---
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { Conflict, Sudoku } from "./sudoku.ts";
 export type { CreateOptions } from "./sudoku.ts";
-export { getPuzzleArr, getPuzzleCode } from "./utility.ts";
+export { EncodingOption, getPuzzleArr, getPuzzleCode, getSymbol, maxRank } from "./utility.ts";

package/dist/index.js

@@ -1,3 +1,3 @@
 // Copyright (c) 2024-2026 New Media XP. Licensed under the MIT License.
 export { Conflict, Sudoku } from "./sudoku.js";
-export { getPuzzleArr, getPuzzleCode } from "./utility.js";
+export { EncodingOption, getPuzzleArr, getPuzzleCode, getSymbol, maxRank } from "./utility.js";

package/dist/utility.d.ts

@@ -1,19 +1,61 @@
 import type { Random } from "./random.ts";
 /**
- * Encodes a grid as one character per square, row by row: 0 = blank, 1-9 as digits,
- * 10 and above as letters ('A' = 10), '.' between rows.
- * Values above 35 ('Z') are unrepresentable, so rank 5 (25x25) at most.
+ * Character sets a puzzle code can be written in. Blank (0) is '0' in every one of them.
+ */
+export declare const EncodingOption: Readonly<{
+    /** 1 to 9 as digits, then 10 to 35 as A to Z. Fits every rank. */
+    readonly All: 0;
+    /** 1 to 9 as digits, then 10 to 34 as A to Z without O, so it can't be misread as blank '0'. Fits every rank. */
+    readonly AllMinusO: 1;
+    /** 1 to 9 as digits only. Fits rank 3 and below. */
+    readonly DigitsOnly: 2;
+    /** 1 to 26 as A to Z. Fits every rank. */
+    readonly LettersOnly: 3;
+    /** 1 to 25 as A to Z without O, so it can't be misread as blank '0'. Fits every rank. */
+    readonly LettersOnlyMinusO: 4;
+}>;
+/** One of the {@link EncodingOption} values. */
+export type EncodingOption = (typeof EncodingOption)[keyof typeof EncodingOption];
+/**
+ * The highest rank whose grids an encoding can write; a rank r grid holds values up to r^2.
+ * Never above Sudoku.maxRank, since no encoding writes past 35.
+ * @param p_encoding The character set to check.
+ * @returns 3 for {@link EncodingOption.DigitsOnly}, 5 for every other encoding.
+ * @throws {RangeError} The encoding is not an {@link EncodingOption} value.
+ */
+export declare function maxRank(p_encoding: EncodingOption): number;
+/**
+ * The character an encoding writes for one square value; blank (0) is '0' in every encoding.
+ * @param p_value The square value, from 0 (blank) up to what the encoding can write.
+ * @param p_encoding The character set to write it in.
+ * @returns A single character.
+ * @throws {RangeError} The value is not an integer within 0 and what the encoding can write,
+ * or the encoding is not an {@link EncodingOption} value.
+ */
+export declare function getSymbol(p_value: number, p_encoding: EncodingOption): string;
+/**
+ * Encodes a grid as one character per square, row by row, '.' between rows.
+ * By default ({@link EncodingOption.All}): 0 = blank, 1-9 as digits, 10 and above as letters ('A' = 10).
+ * Values above 35 ('Z') are unrepresentable and throw, so rank 5 (25x25) at most.
  * @param p_puzz The grid to encode, row by row.
- * @returns The puzzle code, e.g. "0012.3400...".
+ * @param p_encoding The character set to write; {@link maxRank} gives the ranks it fits.
+ * Blank (0) is '0' in every encoding.
+ * @returns The puzzle code, e.g. "0012.3400..." by default or in {@link EncodingOption.All},
+ * or "00AB.CD00..." in {@link EncodingOption.LettersOnly}.
+ * @throws {RangeError} A value is not an integer within 0 and what the encoding can write,
+ * or the encoding is not an {@link EncodingOption} value.
  */
-export declare function getPuzzleCode(p_puzz: ArrayLike<number>): string;
+export declare function getPuzzleCode(p_puzz: ArrayLike<number>, p_encoding?: EncodingOption): string;
 /**
  * Parses a puzzle code back into a grid array.
- * @param p_code Text containing the grid as digits and letters ('A' or 'a' = 10);
- * every other character is ignored.
+ * The encoding can't be told from the code itself (a code without 'O' may or may not be a minus-O one), so it is given.
+ * @param p_code Text containing the grid, '0' = blank, letters in either case ('A' or 'a' = 10 by default);
+ * every character the encoding doesn't use is ignored, including 'O' in the minus-O encodings.
+ * @param p_encoding The character set the code was written in; the default reads it as {@link EncodingOption.All}.
  * @returns One element per recognised character, in order.
+ * @throws {RangeError} The encoding is not an {@link EncodingOption} value.
  */
-export declare function getPuzzleArr(p_code: string): number[];
+export declare function getPuzzleArr(p_code: string, p_encoding?: EncodingOption): number[];
 export declare function count(p_arr: ArrayLike<number>, p_num: number): number;
 /**
  * Fills an array block-wise so that every consecutive block ends up a random permutation of the same value range.

package/dist/utility.js

@@ -1,40 +1,133 @@
 // Copyright (c) 2024-2026 New Media XP. Licensed under the MIT License.
 /**
- * Encodes a grid as one character per square, row by row: 0 = blank, 1-9 as digits,
- * 10 and above as letters ('A' = 10), '.' between rows.
- * Values above 35 ('Z') are unrepresentable, so rank 5 (25x25) at most.
+ * Character sets a puzzle code can be written in. Blank (0) is '0' in every one of them.
+ */
+export const EncodingOption = Object.freeze({
+    /** 1 to 9 as digits, then 10 to 35 as A to Z. Fits every rank. */
+    All: 0,
+    /** 1 to 9 as digits, then 10 to 34 as A to Z without O, so it can't be misread as blank '0'. Fits every rank. */
+    AllMinusO: 1,
+    /** 1 to 9 as digits only. Fits rank 3 and below. */
+    DigitsOnly: 2,
+    /** 1 to 26 as A to Z. Fits every rank. */
+    LettersOnly: 3,
+    /** 1 to 25 as A to Z without O, so it can't be misread as blank '0'. Fits every rank. */
+    LettersOnlyMinusO: 4,
+});
+// the highest square value each encoding can write, indexed by EncodingOption; blank (0) is '0' on top of these
+const maxValues = [35, 34, 9, 26, 25];
+const encodingNames = Object.keys(EncodingOption);
+function maxValue(p_encoding) {
+    const a_maxValue = Number.isInteger(p_encoding) ? maxValues[p_encoding] : undefined;
+    if (a_maxValue === undefined)
+        throw new RangeError(`unknown encoding ${p_encoding}`);
+    return a_maxValue;
+}
+/**
+ * The highest rank whose grids an encoding can write; a rank r grid holds values up to r^2.
+ * Never above Sudoku.maxRank, since no encoding writes past 35.
+ * @param p_encoding The character set to check.
+ * @returns 3 for {@link EncodingOption.DigitsOnly}, 5 for every other encoding.
+ * @throws {RangeError} The encoding is not an {@link EncodingOption} value.
+ */
+export function maxRank(p_encoding) {
+    return Math.trunc(Math.sqrt(maxValue(p_encoding)));
+}
+// the letter at index p_letterIdx of A to Z with O skipped; 'A' = 65, 'O' - 'A' = 14
+function letterMinusO(p_letterIdx) {
+    return String.fromCharCode(65 + (p_letterIdx < 14 ? p_letterIdx : p_letterIdx + 1));
+}
+/**
+ * The character an encoding writes for one square value; blank (0) is '0' in every encoding.
+ * @param p_value The square value, from 0 (blank) up to what the encoding can write.
+ * @param p_encoding The character set to write it in.
+ * @returns A single character.
+ * @throws {RangeError} The value is not an integer within 0 and what the encoding can write,
+ * or the encoding is not an {@link EncodingOption} value.
+ */
+export function getSymbol(p_value, p_encoding) {
+    const a_maxValue = maxValue(p_encoding);
+    if (!Number.isInteger(p_value) || p_value < 0 || p_value > a_maxValue)
+        throw new RangeError(`value ${p_value} is outside 0..${a_maxValue} for ${encodingNames[p_encoding]} encoding`);
+    if (p_value === 0)
+        return "0";
+    // '0' = 48, 'A' - 10 = 55, 'A' - 1 = 64
+    switch (p_encoding) {
+        case EncodingOption.All:
+            return String.fromCharCode(p_value <= 9 ? 48 + p_value : 55 + p_value);
+        case EncodingOption.AllMinusO:
+            return p_value <= 9 ? String.fromCharCode(48 + p_value) : letterMinusO(p_value - 10);
+        case EncodingOption.DigitsOnly:
+            return String.fromCharCode(48 + p_value);
+        case EncodingOption.LettersOnly:
+            return String.fromCharCode(64 + p_value);
+        case EncodingOption.LettersOnlyMinusO:
+            return letterMinusO(p_value - 1);
+    }
+}
+// the value one character code stands for under p_encoding, or -1 when the encoding doesn't use that character
+function getValue(p_char, p_encoding) {
+    // '0'..'9' = 48..57, 'A'..'Z' = 65..90, 'a'..'z' = 97..122, 'O' = 79
+    if (p_char === 48)
+        return 0;
+    // ASCII-only case fold; toUpperCase would also turn 'ı' and 'ſ' into letters
+    const a_upper = p_char >= 97 && p_char <= 122 ? p_char - 32 : p_char;
+    const a_digit = a_upper >= 49 && a_upper <= 57 ? a_upper - 48 : -1;
+    const a_letter = a_upper >= 65 && a_upper <= 90 ? a_upper - 65 : -1;
+    // O is not a symbol of the minus-O encodings, so it is ignored like any other unused character
+    const a_letterMinusO = a_letter < 0 || a_upper === 79 ? -1 : a_upper < 79 ? a_letter : a_letter - 1;
+    switch (p_encoding) {
+        case EncodingOption.All:
+            return a_digit > 0 ? a_digit : a_letter >= 0 ? a_letter + 10 : -1;
+        case EncodingOption.AllMinusO:
+            return a_digit > 0 ? a_digit : a_letterMinusO >= 0 ? a_letterMinusO + 10 : -1;
+        case EncodingOption.DigitsOnly:
+            return a_digit;
+        case EncodingOption.LettersOnly:
+            return a_letter >= 0 ? a_letter + 1 : -1;
+        case EncodingOption.LettersOnlyMinusO:
+            return a_letterMinusO >= 0 ? a_letterMinusO + 1 : -1;
+    }
+}
+/**
+ * Encodes a grid as one character per square, row by row, '.' between rows.
+ * By default ({@link EncodingOption.All}): 0 = blank, 1-9 as digits, 10 and above as letters ('A' = 10).
+ * Values above 35 ('Z') are unrepresentable and throw, so rank 5 (25x25) at most.
  * @param p_puzz The grid to encode, row by row.
- * @returns The puzzle code, e.g. "0012.3400...".
+ * @param p_encoding The character set to write; {@link maxRank} gives the ranks it fits.
+ * Blank (0) is '0' in every encoding.
+ * @returns The puzzle code, e.g. "0012.3400..." by default or in {@link EncodingOption.All},
+ * or "00AB.CD00..." in {@link EncodingOption.LettersOnly}.
+ * @throws {RangeError} A value is not an integer within 0 and what the encoding can write,
+ * or the encoding is not an {@link EncodingOption} value.
  */
-export function getPuzzleCode(p_puzz) {
+export function getPuzzleCode(p_puzz, p_encoding = EncodingOption.All) {
+    maxValue(p_encoding);
     const a_rows = Math.trunc(Math.sqrt(p_puzz.length));
     let a_puzzleCode = "";
     for (let i = 0; i < p_puzz.length; ++i) {
         if (i > 0 && i % a_rows === 0)
             a_puzzleCode += ".";
-        const a_value = p_puzz[i];
-        // 'A' - 10 = 55, '0' = 48
-        a_puzzleCode += String.fromCharCode(a_value > 9 ? 55 + a_value : 48 + a_value);
+        a_puzzleCode += getSymbol(p_puzz[i], p_encoding);
     }
     return a_puzzleCode;
 }
 /**
  * Parses a puzzle code back into a grid array.
- * @param p_code Text containing the grid as digits and letters ('A' or 'a' = 10);
- * every other character is ignored.
+ * The encoding can't be told from the code itself (a code without 'O' may or may not be a minus-O one), so it is given.
+ * @param p_code Text containing the grid, '0' = blank, letters in either case ('A' or 'a' = 10 by default);
+ * every character the encoding doesn't use is ignored, including 'O' in the minus-O encodings.
+ * @param p_encoding The character set the code was written in; the default reads it as {@link EncodingOption.All}.
  * @returns One element per recognised character, in order.
+ * @throws {RangeError} The encoding is not an {@link EncodingOption} value.
  */
-export function getPuzzleArr(p_code) {
+export function getPuzzleArr(p_code, p_encoding = EncodingOption.All) {
+    maxValue(p_encoding);
     const a_puzzle = [];
     for (let i = 0; i < p_code.length; ++i) {
-        const c = p_code.charCodeAt(i);
-        // '0'..'9' = 48..57, 'A'..'Z' = 65..90, 'a'..'z' = 97..122
-        if (c >= 48 && c <= 57)
-            a_puzzle.push(c - 48);
-        else if (c >= 65 && c <= 90)
-            a_puzzle.push(c - 55);
-        else if (c >= 97 && c <= 122)
-            a_puzzle.push(c - 87);
+        const a_value = getValue(p_code.charCodeAt(i), p_encoding);
+        if (a_value !== -1)
+            a_puzzle.push(a_value);
     }
     return a_puzzle;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "nmx.sudokugen.library",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Sudoku generator and solver: unique-solution puzzle creation (optionally seeded), solving, validation, conflict reporting and isomorphic shuffling.",
     "keywords": [
         "sudoku",
@@ -8,14 +8,14 @@
         "solver",
         "generator"
     ],
-    "homepage": "https://github.com/newmediaxp/sudokugen/tree/main/js/nmx.sudokugen.library#readme",
+    "homepage": "https://github.com/newmediaxp/sudokugen/tree/main/javascript/nmx.sudokugen.library#readme",
     "bugs": {
         "url": "https://github.com/newmediaxp/sudokugen/issues"
     },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/newmediaxp/sudokugen.git",
-        "directory": "js/nmx.sudokugen.library"
+        "directory": "javascript/nmx.sudokugen.library"
     },
     "license": "MIT",
     "author": "New Media XP <contact@newmediaxp.com> (https://www.newmediaxp.com)",