Rewrite of library, better standard compliance, 10x speedup

Author: manuelbl

.github/workflows/continuous-integration.yml

@@ -20,11 +20,11 @@ jobs:
     name: Build and run tests
     steps:
       - name: Checkout git repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-dotnet@v4
+      - uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
             6.x
@@ -40,7 +40,7 @@ jobs:
         run: dotnet test --no-build --verbosity normal
 
       - name: Upload test results
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: TestResults-${{ runner.os }}

.github/workflows/demos.yaml

@@ -16,11 +16,11 @@ jobs:
     name: Build demo projects
     steps:
       - name: Checkout git repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-dotnet@v4
+      - uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
             6.x
@@ -43,6 +43,9 @@ jobs:
           $pkg = Resolve-Path QrCodeGenerator\bin\Release\Net.Codecrete.QrCodeGenerator.*.nupkg
           nuget push $pkg -Source Local
 
+      - name: Build Basic-Example
+        run: dotnet build
+        working-directory: Basic-Example
       - name: Build Demo-ImageSharp
         run: dotnet build
         working-directory: Demo-ImageSharp
@@ -52,9 +55,6 @@ jobs:
       - name: Build Demo-ImageMagick
         run: dotnet build
         working-directory: Demo-ImageMagick
-      - name: Build Demo-QRCode-Variety
-        run: dotnet build
-        working-directory: Demo-QRCode-Variety
       - name: Build Demo-SkiaSharp
         run: dotnet build
         working-directory: Demo-SkiaSharp

.gitignore

@@ -21,3 +21,7 @@
 
 # Rider
 .idea/
+
+# Claude
+.claude/
+TestResults-*

…RCode-Variety/Demo-QRCode-Variety.csproj Basic-Example/Basic-Example.csprojDemo-QRCode-Variety/Demo-QRCode-Variety.csproj renamed to Basic-Example/Basic-Example.csproj Demo-QRCode-Variety/Demo-QRCode-Variety.csproj renamed to Basic-Example/Basic-Example.csproj

@@ -3,11 +3,11 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net8.0</TargetFramework>
-    <RootNamespace>Demo_Basic</RootNamespace>
+    <RootNamespace>Net.Codecrete.QrCodeGenerator.Demo</RootNamespace>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Net.Codecrete.QrCodeGenerator" Version="2.*" />
+    <PackageReference Include="Net.Codecrete.QrCodeGenerator" Version="3.*" />
   </ItemGroup>
 
 </Project>

…o-QRCode-Variety/Demo-QRCode-Variety.sln Basic-Example/Basic-Example.slnDemo-QRCode-Variety/Demo-QRCode-Variety.sln renamed to Basic-Example/Basic-Example.sln Demo-QRCode-Variety/Demo-QRCode-Variety.sln renamed to Basic-Example/Basic-Example.sln

@@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31903.59
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Demo-QRCode-Variety", "Demo-QRCode-Variety.csproj", "{CE334406-7A4A-4455-889B-200DEBB6C08C}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Basic-Example", "Basic-Example.csproj", "{CE334406-7A4A-4455-889B-200DEBB6C08C}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

Basic-Example/Program.cs

@@ -0,0 +1,123 @@
+/*
+ * QR code generator library (.NET)
+ *
+ * Copyright (c) Manuel Bleichenbacher (MIT License)
+ * https://github.com/manuelbl/QrCodeGenerator
+ */
+
+using System.IO;
+using System.Text;
+
+namespace Net.Codecrete.QrCodeGenerator.Demo
+{
+    internal class Program
+    {
+        // The main application program.
+        internal static void Main()
+        {
+            // Enable support for special encodings like Shift-JIS
+            Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
+
+            BasicQrCode();
+            AlphanumericText();
+            LongerText();
+            Emojis();
+            EmojisWithoutEci();
+            BinaryData();
+            GraphicsFormats();
+        }
+
+        // Creates a single QR code, then writes it to an SVG file.
+        private static void BasicQrCode()
+        {
+            const string text = "Hello, world!"; // Payload text
+            var errCorLvl = QrCode.Ecc.Low; // Minimal error correction level
+
+            var qrCode = QrCode.EncodeText(text, errCorLvl); // Create the QR code symbol
+            SaveAsSvg(qrCode, "hello-world-qr.svg"); // Save as SVG
+        }
+
+
+        // Creates QR code with digits and alphanumeric characters only.
+        private static void AlphanumericText()
+        {
+            // For digits, a more compact representation will automatically be chosen (3.33 bits per digit)
+            var qrCode = QrCode.EncodeText("27182818284590452353602874713526624977572470936999595749669676277240766",
+                QrCode.Ecc.Medium);
+            SaveAsSvg(qrCode, "digits-qr.svg");
+
+            // For an alphanumeric subset of characters (not including lower-case letters),
+            // a more compact representation will be automatically chosen (5.5 bits per character)
+            qrCode = QrCode.EncodeText("THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG", QrCode.Ecc.High);
+            SaveAsSvg(qrCode, "alphanumeric-qr.svg");
+        }
+
+        private static void LongerText()
+        {
+            // Moderately large QR code using longer text
+            var qrCode = QrCode.EncodeText(
+                "I was a Flower of the mountain yes when I put the rose in my hair like the Andalusian girls used " +
+                "or shall I wear a red yes and how he kissed me under the Moorish wall and I thought well as well " +
+                "him as another and then I asked him with my eyes to ask again yes and then he asked me would I " +
+                "yes to say yes my mountain flower and first I put my arms around him yes and drew him down to me " +
+                "so he could feel my breasts all perfume yes and his heart was going like mad and yes I said yes " +
+                "I will Yes.", QrCode.Ecc.High);
+            SaveAsSvg(qrCode, "joyce-qr.svg");
+        }
+        
+        private static void Emojis()
+        {
+            // The full Unicode character set is supported.
+            // By default, the library uses UTF-8 encoding and indicates this with an ECI designator.
+            var qrCode = QrCode.EncodeText("🎲 😇 🤒 🏌 ⏭ 🚍", QrCode.Ecc.Quartile);
+            SaveAsSvg(qrCode, "emojis-qr.svg");
+        }
+
+        private static void EmojisWithoutEci()
+        {
+            // Suppress the ECI designator.
+            // Most QR code readers will correctly guess the encoding.
+            // Some readers always ignore the ECI designator.
+            var qrCode = QrCode.EncodeTextAdvanced("🎲 😇 🤒 🏌 ⏭ 🚍", QrCode.Ecc.Quartile,
+                encoding: Encoding.UTF8, eci: ECI.None);
+            SaveAsSvg(qrCode, "emojis-no-eci-qr.svg");
+        }
+
+        private static void BinaryData()
+        {
+            // Encode binary data. An ECI designator will be added to indicate it.
+            // Exchanging binary data with QR codes usually works in closed systems only.
+            byte[] data = {
+                0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00,
+                0x01, 0x00, 0x80, 0x01, 0x00, 0xff, 0xff, 0xff,
+                0x00, 0x00, 0x00, 0x21, 0xf9, 0x04, 0x01, 0x0a,
+                0x00, 0x01, 0x00, 0x2c, 0x00, 0x00, 0x00, 0x00,
+                0x01, 0x00, 0x01, 0x00, 0x00, 0x02, 0x02, 0x4c,
+                0x01, 0x00, 0x3b
+            };
+            var qr = QrCode.EncodeBinary(data, QrCode.Ecc.Medium);
+            SaveAsSvg(qr, "binary.svg");
+        }
+
+        private static void GraphicsFormats()
+        {
+            // Save the QR code in various graphics formats, directly supported by the library.
+            // See the demo applications for further graphics format and displaying options.
+            var qrCode = QrCode.EncodeText(
+                "Ineluctable modality of the visible: at least that if no more, thought through my eyes. Signatures " +
+                "of all things I am here to read, seapawn and searack, the nearing tide, that rusty boot. Snotgreen, " +
+                "bluesilver, rust: colored signs. Limits of the diaphane.", QrCode.Ecc.Medium);
+
+            File.WriteAllBytes("qr-code.png", qrCode.ToPngBitmap(border: 4));
+
+            File.WriteAllBytes("qr-code.bmp", qrCode.ToBmpBitmap(border: 4));
+        }
+
+        private static void SaveAsSvg(QrCode qrCode, string filname)
+        {
+            string svg = qrCode.ToSvgString(4); // Convert to SVG XML code
+            File.WriteAllText(filname, svg, Encoding.UTF8); // Write image to file
+        }
+
+    }
+}

Basic-Example/README.md

@@ -0,0 +1,11 @@
+# Example code for generating QR codes
+
+This example program creates a series of QR code and saves them as SVG, PNG and BMP files.
+It is a simple console application without the need for any further libraries.
+It will run on any .NET platform compatible with .NET Standard 2.0.
+
+The examples demonstrate the use of:
+
+- different texxt encoding (short/long, digits, alphanumeric, full Unicode)
+- different error correction levels
+- encoding binary data

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+## Purpose
+
+QrCodeGenerator is a library to generate QR code. It is designed to be easy to use and performant.
+
+The library only supports limited graphics types and options in order to work without
+any graphics libraries, which might not run all platforms.
+The library can provide the QR code as a list of rectangles or as a two-dimensional array of pixels
+(called modules by the QR code standard). It is then up to the application to display the QR code.
+Many demo projects show how to use this approach for different graphics libraries and UI frameworks.
+
+The main target of the library is .NET Standard 2.0 so it runs in virtually any current .NET environment.
+
+
+## Commands
+
+```bash
+# Build
+dotnet build
+dotnet build --configuration Release
+
+# Test (all)
+dotnet test
+
+# Test (single class)
+dotnet test --filter "FullyQualifiedName~QrCodeTest"
+
+# Test (single method)
+dotnet test --filter "FullyQualifiedName=Net.Codecrete.QrCodeGenerator.Test.QrCodeTest.Constants"
+
+# Pack NuGet
+dotnet pack --no-build
+```
+
+## Build targets
+
+- **`QrCodeGenerator/`** (the library) targets `netstandard2.0;net6.0`. The `net6.0` target exists only to enable trimming (`IsTrimmable`). Keep public API and language usage compatible with netstandard2.0 — don't reach for newer BCL/`Span` APIs that aren't available there.
+- **`QrCodeGeneratorTest/`** (the unit tests) targets `net8.0;net10.0`, plus `net481` on Windows. `dotnet test` runs every target framework.
+- **`QrCodeGeneratorProfiling/`** targets `net10.0` (BenchmarkDotNet).
+- **`QrCodeAnalyzer/`** is a separate WPF tool in its own solution (`QrCodeAnalyzer/QrCodeAnalyzer.sln`), not part of `QrCodeGenerator.sln`.
+
+
+## Architecture
+
+`QrCode` is the only substantial public surface: factory methods create immutable `QrCode` instances. They can be rendered to
+sVG, PNG, BMP or a list of rectangles. It holds a single `BitMatrix` of modules. Almost all real work lives in `internal` types.
+
+
+### Encoding pipeline
+
+Text/bytes → segments → codewords → matrix, in this order:
+
+1. **`DataSegment.FromText` / `FromBinaryData`** — chooses the text encoding. For automatic ECI: tries Latin-1 (ISO-8859-1) and adds no ECI; falls back to UTF-8 with an ECI designator if Latin-1 is lossy. Segments retain the *original unencoded bytes* as an `ArraySegment` over the caller's array until the bit stream is built — **the source array must not be mutated** in the meantime.
+2. **`SegmentCompaction`** — picks the cheapest per-byte mode (numeric > alphanumeric > Kanji > binary), groups consecutive bytes into blocks, then greedily *merges* adjacent blocks when the mode-switch overhead outweighs the savings. Merge cost depends on `version` (count-indicator width changes at versions 1/10/27). This is what produces the "smallest possible QR code" claim.
+3. **`QrCodeBuilder.Build`** is a thin orchestrator that wires the remaining stages, each its own `internal static` module:
+   - **`VersionPlanner.Plan`** — smallest version that fits, then boost ECC level for free if it doesn't grow the version. Returns a named `(int Version, int Ecc)`.
+   - **`Codewords.BuildData`** — segments → `BitStream` → byte codewords + terminator + 0xEC/0x11 padding.
+   - **`Codewords.AddErrorCorrection`** — splits into blocks, computes Reed-Solomon ECC (`ReedSolomon`), interleaves data and ECC codewords per spec.
+   - **`MatrixEncoder.Encode`** — matrix layout then mask selection:
+     - `FixedPatterns.BuildFixedPatterns` deals with the fixed-pattern geometry of a version: one walk emits both the *drawn* matrix (finder/timing/alignment/version) and the *reserved-module* mask. The reserved mask, inverted, is the *payload-area map* (`GetPayloadAreaMap`). Then `FillPayload` zig-zags the codewords into the free modules.
+     - `ApplyBestPattern` — XORs each of the 8 mask patterns, scores it (`Penalty`), keeps the lowest, and draws the format information. `EncodingInfo.ForcedDataMask` can override the choice.
+
+   The ISO/IEC 18004 lookup tables these stages share live in **`QrCodeParameters`**.
+
+### `BitMatrix` and the transpose trick
+
+`BitMatrix` (`internal readonly struct`) is the central data structure: a square bit grid stored as 4 `ulong`s per row (256-bit rows regardless of size), in row-major order. It exposes fast whole-matrix `And`/`Xor`/`Invert`/`PopCount` and an in-place **64×64 block transpose**.
+
+The transpose is load-bearing, not a convenience: every penalty/format rule that operates on *columns* is implemented by transposing the matrix and reusing the *row*-wise algorithm. `ApplyBestPattern` keeps a `modules` and a `transposed` copy in lock-step, and `Penalty` takes both. `Penalty` itself is bit-parallel (operates on whole `ulong` words, not per-module) and has an early-stop path that bails once the running score exceeds the best-so-far.
+
+### Performance-tuned constants
+
+Two orderings are deliberately ordered by profiling data (see `QrCodeGeneratorProfiling/README.md`), not arbitrary: `MatrixEncoder.PatternEvaluationOrder` (evaluate likely-best masks first to tighten the early-stop bound) and the rule order inside `Penalty.CalculatePenalty`. Reordering them changes performance, not output. Per-version `BitMatrix` results are cached in `ConcurrentDictionary` instances — `FixedPatterns` caches the drawn fixed patterns and the payload-area map; `MatrixEncoder` caches the data-mask patterns. Cached `BitMatrix` instances are shared and must not be mutated (callers `Copy()` first).
+
+Everything is keyed by `version` (1–40) and `ecc` (0–3 = L/M/Q/H). The large `static readonly` lookup tables in `QrCodeParameters` (codeword capacity, block counts, alignment positions, format/version info bits) come straight from ISO/IEC 18004 tables — comments cite the table numbers.
+
+### Rendering and diagnostics
+
+- `RectangleBuilder` merges adjacent dark modules into the largest rectangles (greedy, non-overlapping, union == dark modules) to shrink output. It is the single source of truth for that geometry: `QrCode.ToRectangles` exposes the list publicly (as `QrRectangle`s, in `GetModule` coordinates with no border), and `SvgBuilder` (SVG document + SVG/XAML path) consumes the same list, adding the border at emit time. `BmpBuilder` (BMP) and `PngBuilder` (PNG) take the finished modules directly. `QrCode` delegates to all of them.
+- `StructuredAppend` splits long text across up to 16 linked QR codes (used by `EncodeTextInMultipleCodes`).
+- `EncodingInfo` / `PenaltyScore` are opt-in diagnostics: pass an `EncodingInfo` to capture per-mask penalty breakdowns and the chosen segments. This forces *full* penalty evaluation (disables early-stop), so it is slower — it exists for the `QrCodeAnalyzer` tool, not normal use.
+
+## Tests
+
+Uses **xUnit v3** with **Verify.XunitV3** for snapshot/approval testing and **Xunit.Combinatorial** for parameterized matrices.
+
+The test strategy is characterization + cross-validation, not just unit tests:
+
+- **`QrCodeDataProvider.cs`** is a large generated `[ClassData]` source feeding `QrCodeTest`. `TestQrCode` asserts the exact module layout, version, ECC, and mask for each case (golden tests).
+- **`VerifyWithZXing`** decodes every generated QR code with **ZXing.Net** and asserts the text round-trips with *zero* errors corrected. `CorruptedModule_IsCorrected_AndReportsErrorsCorrected` is a negative control that flips one module to prove that assertion has teeth. (Some ECI+Kanji combinations are skipped due to a ZXing 0.16.x decode bug — the QR is still valid.)
+- **`ReedSolomonTest`** cross-checks ECC against the **STH1123.ReedSolomon** package.
+- **Verify** snapshot tests cover rendered output (SVG/PNG/BMP). Snapshot `.verified.*` files live alongside the test source in `QrCodeGeneratorTest/`. When a snapshot changes intentionally, run `dotnet test` once — Verify fails and writes the new `.verified.*` file; accept it by replacing the old one (or via the Verify tooling).