Resolve name ambiguity

Author: manuelbl

CONTEXT.md

@@ -26,7 +26,7 @@ The union of all fixed-pattern footprints — every module the payload must not
 
 **Payload-area map**:
 The complement of the reserved modules: the modules the payload zig-zag is allowed
-to fill. This is what `GetDataMask` returns.
+to fill. This is what `GetPayloadAreaMap` returns.
 _Avoid_: "data mask" — see Flagged ambiguities.
 
 **Mask pattern**:
@@ -52,11 +52,3 @@ lowest penalty score. Exposed as `QrCode.Mask`.
 > emits both: it stamps the dark **modules** and reserves the **footprint** in the same
 > place. You can't infer reserved from drawn, because a footprint reserves light modules
 > too."
-
-## Flagged ambiguities
-
-- **"data mask"** was used for two distinct things: (1) the **payload-area map**
-  returned by `GetDataMask` / `DataMaskCache`, and (2) a **mask pattern** (the 8 XOR
-  patterns), as in `GetDataMaskPattern`. Resolved: prefer **payload-area map** for (1)
-  and **mask pattern** for (2). The existing `GetDataMask` method name is retained for
-  compatibility but denotes the payload-area map.

QrCodeGenerator/FixedPatterns.cs

@@ -42,16 +42,16 @@ internal static class FixedPatterns
         // inverted reserved mask (the modules the payload zig-zag may fill). Both are
         // computed by a single BuildFixedPatterns walk and cached together.
         // The cached instances are shared and must not be mutated (CreateWithFixedPatterns
-        // hands out a Copy; GetDataMask's result is treated as read-only by callers).
-        private static readonly ConcurrentDictionary<int, (BitMatrix Drawn, BitMatrix DataMask)> Cache
+        // hands out a Copy; GetPayloadAreaMap's result is treated as read-only by callers).
+        private static readonly ConcurrentDictionary<int, (BitMatrix Drawn, BitMatrix PayloadAreaMap)> Cache
             = new ConcurrentDictionary<int, (BitMatrix, BitMatrix)>();
 
-        private static (BitMatrix Drawn, BitMatrix DataMask) GetCached(int version)
+        private static (BitMatrix Drawn, BitMatrix PayloadAreaMap) GetCached(int version)
         {
             return Cache.GetOrAdd(version, ComputeCached);
         }
 
-        private static (BitMatrix Drawn, BitMatrix DataMask) ComputeCached(int version)
+        private static (BitMatrix Drawn, BitMatrix PayloadAreaMap) ComputeCached(int version)
         {
             var (drawn, reserved) = BuildFixedPatterns(version);
             // Turn the reserved mask into the payload-area map (where data goes).
@@ -84,9 +84,9 @@ internal static BitMatrix CreateWithFixedPatterns(int version)
         /// </summary>
         /// <param name="version">The QR code version.</param>
         /// <returns>A shared <see cref="BitMatrix"/> instance.</returns>
-        internal static BitMatrix GetDataMask(int version)
+        internal static BitMatrix GetPayloadAreaMap(int version)
         {
-            return GetCached(version).DataMask;
+            return GetCached(version).PayloadAreaMap;
         }
 
         #endregion

QrCodeGenerator/QrCodeBuilder.cs

@@ -296,7 +296,7 @@ private static void SetFormatBit(BitMatrix modules, BitMatrix transposed, int x,
         [SuppressMessage("csharpsquid", "S127")]
         internal static void FillPayload(BitMatrix modules, byte[] codewords, int version)
         {
-            var dataMask = FixedPatterns.GetDataMask(version);
+            var payloadArea = FixedPatterns.GetPayloadAreaMap(version);
 
             // zigzag up and down with a 2-wide stride, starting in the right bottom corner
             var size = modules.Size;
@@ -322,7 +322,7 @@ internal static void FillPayload(BitMatrix modules, byte[] codewords, int versio
                     // alternate between the 2 columns
                     for (var x = h; x > h - 2; x -= 1)
                     {
-                        if (!dataMask.Get(x, y))
+                        if (!payloadArea.Get(x, y))
                         {
                             // skip modules not intended for payload
                             continue;
@@ -358,7 +358,7 @@ private static BitMatrix GetDataMaskPattern(int patternIndex, int version)
         private static BitMatrix CreateDataMaskPattern((int patternIndex, int version) key)
         {
             var pattern = CreatePattern(key.patternIndex, key.version);
-            pattern.And(FixedPatterns.GetDataMask(key.version));
+            pattern.And(FixedPatterns.GetPayloadAreaMap(key.version));
             return pattern;
         }
 

QrCodeGeneratorTest/QrCodeBuilderTest.cs

@@ -176,15 +176,15 @@ public void FillPayload([CombinatorialRange(1, 40)] int version)
             }
 
             var modules = FixedPatterns.CreateWithFixedPatterns(version);
-            var dataMask = FixedPatterns.GetDataMask(version);
+            var payloadArea = FixedPatterns.GetPayloadAreaMap(version);
             var size = modules.Size;
-            Assert.Equal(0, CountDarkDataModules(modules, dataMask));
+            Assert.Equal(0, CountDarkDataModules(modules, payloadArea));
 
             QrCodeBuilder.FillPayload(modules, codewords, version);
 
-            var darkModules = CountDarkDataModules(modules, dataMask);
+            var darkModules = CountDarkDataModules(modules, payloadArea);
             Assert.Equal(codewords.Length * 8, darkModules);
-            var lightModules = CountLightDataModules(modules, dataMask);
+            var lightModules = CountLightDataModules(modules, payloadArea);
             Assert.InRange(lightModules, 0, 7);
 
             // assert that all light modules are near the bottom left corner
@@ -196,7 +196,7 @@ public void FillPayload([CombinatorialRange(1, 40)] int version)
                 {
                     for (var y = size - 12 - versionInfoOffset; y < size - 8 - versionInfoOffset; y += 1)
                     {
-                        if (!modules.Get(x, y) && dataMask.Get(x, y))
+                        if (!modules.Get(x, y) && payloadArea.Get(x, y))
                         {
                             count += 1;
                         }
@@ -321,15 +321,15 @@ private static void AssertMirrored(BitMatrix matrix)
             }
         }
 
-        private static int CountDarkDataModules(BitMatrix modules, BitMatrix dataMask)
+        private static int CountDarkDataModules(BitMatrix modules, BitMatrix payloadArea)
         {
             var sum = 0;
             var size = modules.Size;
             for (var x = 0; x < size; x += 1)
             {
                 for (var y = 0; y < size; y += 1)
                 {
-                    if (modules.Get(x, y) && dataMask.Get(x, y))
+                    if (modules.Get(x, y) && payloadArea.Get(x, y))
                     {
                         sum += 1;
                     }
@@ -338,15 +338,15 @@ private static int CountDarkDataModules(BitMatrix modules, BitMatrix dataMask)
             return sum;
         }
 
-        private static int CountLightDataModules(BitMatrix modules, BitMatrix dataMask)
+        private static int CountLightDataModules(BitMatrix modules, BitMatrix payloadArea)
         {
             var sum = 0;
             var size = modules.Size;
             for (var x = 0; x < size; x += 1)
             {
                 for (var y = 0; y < size; y += 1)
                 {
-                    if (!modules.Get(x, y) && dataMask.Get(x, y))
+                    if (!modules.Get(x, y) && payloadArea.Get(x, y))
                     {
                         sum += 1;
                     }