Fixed a bunch of small issues and some general improvements found by Claude Code. Updated to version 0.9.3.

Author: FoolRunning

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Build Commands
+
+```bash
+dotnet restore                    # Restore dependencies
+dotnet build --no-restore         # Build solution
+dotnet test --no-build            # Run tests
+dotnet test --verbosity normal    # Run tests with detailed output
+```
+
+The solution targets .NET Standard 2.0 (library) and .NET 8.0 (tests). Tests use MSTest framework.
+
+## Architecture Overview
+
+UnicodeHelper is a .NET library that provides Unicode property access and enhanced string handling for characters beyond the Basic Multilingual Plane (codepoints > U+FFFF). It supports Unicode 17.0.0.
+
+### Core Types
+
+**UCodepoint** (`UnicodeHelper/UCodepoint.cs`) - Readonly struct representing a single Unicode codepoint (0x0000-0x10FFFF). Primary API for querying Unicode properties. Implicitly converts from `char` for BMP characters.
+
+**UString** (`UnicodeHelper/UString.cs`) - Sealed class representing a sequence of Unicode codepoints. Unlike .NET strings, treats upper-plane characters (emoji, etc.) as single units rather than surrogate pairs. Work-in-progress; not all methods fully implemented.
+
+**UStringBuilder** (`UnicodeHelper/UStringBuilder.cs`) - Efficient builder for constructing UStrings. Uses ArrayPool for buffer management; must be disposed.
+
+### Unicode Data Classes
+
+**UnicodeData** (`UnicodeHelper/UnicodeData.cs`) - Core Unicode property data: categories, bidirectional classes, numeric values, case mappings, composition/decomposition mappings.
+
+**UnicodeProperties** (`UnicodeHelper/UnicodeProperties.cs`) - Advanced Unicode properties from PropList.txt and DerivedCoreProperties.txt.
+
+**UnicodeNames** (`UnicodeHelper/UnicodeNames.cs`) - Character names and aliases from DerivedName.txt and NameAliases.txt.
+
+**UnicodeBlocks** (`UnicodeHelper/UnicodeBlocks.cs`) - Maps codepoints to Unicode blocks.
+
+### Extension Methods
+
+**DotNetStringExtensions** - Extends .NET strings with `Codepoints()` iterator and `DetermineDirection()` for text direction (implements Unicode TR9).
+
+### Internal Components
+
+Located in `UnicodeHelper/Internal/`:
+- **DataHelper** - Reads embedded Unicode data from Resources.zip
+- **NormalizationEngine** - Unicode normalization (NFC, NFD, NFKC, NFKD), includes Hangul handling
+- **HelperUtils** - Text direction algorithm implementation
+
+### Embedded Resources
+
+All Unicode data files are embedded in `UnicodeHelper/Resources/Resources.zip` for offline use. Data is loaded lazily on first access via static constructors.
+
+## Testing Approach
+
+Every implemented method should be extensively tested. Tests compare behavior against .NET's built-in Unicode support where applicable. The `UnicodeHelper.Tests/TestData/NormalizationTest.txt` contains normalization test cases. Data-driven tests use `[DynamicData]` attributes.

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+@AGENTS.md

UnicodeHelper.Tests/UStringTests.cs

@@ -309,12 +309,13 @@ public void IndexOf_UCodepoint(string testString, UCodepoint codePoint, int star
         #region LastIndexOf_UCodepoint tests
         private static IEnumerable<object[]> UCodepointLastIndexOfExceptionTestData =>
         [
+            ["", 0, 0, typeof(ArgumentOutOfRangeException)],
             ["", 0, 1, typeof(ArgumentOutOfRangeException)],
             ["", 1, 0, typeof(ArgumentOutOfRangeException)],
-            ["This", -1, 2, typeof(ArgumentException)],
+            ["This", -1, 2, typeof(ArgumentOutOfRangeException)],
             ["This", 3, 5, typeof(ArgumentException)],
             ["This", 3, -1, typeof(ArgumentOutOfRangeException)],
-            ["This", -1, 1, typeof(ArgumentException)],
+            ["This", -1, 1, typeof(ArgumentOutOfRangeException)],
             ["😁🤔😮", 1, 3, typeof(ArgumentException)],
             ["😁🤔😮", 3, 1, typeof(ArgumentOutOfRangeException)]
         ];
@@ -330,11 +331,10 @@ public void LastIndexOf_UCodepoint_InvalidParameters(string testString, int star
 
         private static IEnumerable<object[]> UCodepointLastIndexOfTestData =>
         [
-            ["", (UCodepoint)'A', -1, 0, -1],
             ["This is\r\na test!", (UCodepoint)'\r', 8, 6, 7],
             ["This is\r\na test!", (UCodepoint)'i', 15, 16, 5],
             ["This is\r\na test!", (UCodepoint)'T', 8, 6, -1],
-            ["This", (UCodepoint)'T', -1, 0, -1],
+            ["This", (UCodepoint)'T', 0, 0, -1],
             ["This", (UCodepoint)'s', 3, 0, -1],
             ["This", (UCodepoint)'i', 2, 0, -1],
             ["العربية", (UCodepoint)'ا', 6, 7, 0],

UnicodeHelper.Tests/UnicodeDataTests.cs

@@ -6,7 +6,7 @@ public class UnicodeDataTests
         [TestMethod]
         public void Version()
         {
-            Assert.AreEqual(new Version(16, 0, 0), UnicodeData.UnicodeVersion);
+            Assert.AreEqual(new Version(17, 0, 0), UnicodeData.UnicodeVersion);
         }
     }
 }

UnicodeHelper/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Module Purpose
+
+This is the core library implementing Unicode property access and codepoint-aware string handling. It abstracts away .NET's UTF-16 surrogate pair complexity by treating all Unicode codepoints (including upper-plane characters like emoji) as single units.
+
+## Architectural Decisions
+
+### Data Storage Strategy
+Unicode property data uses large arrays indexed directly by codepoint value (0-0x10FFFF = 1,114,112 entries). This trades memory for O(1) lookup performance:
+- `UnicodeData.categories[]` - byte array for UnicodeCategory
+- `UnicodeData.bidiClasses[]` - enum array for bidirectional class
+- `UnicodeProperties.props[]` - UnicodeProperty flags array
+- Dictionary lookups only for sparse data (numeric values, case mappings, decomposition mappings)
+
+### Lazy Initialization Pattern
+All static data classes (`UnicodeData`, `UnicodeProperties`, `UnicodeNames`, `UnicodeBlocks`) use static constructors that load from embedded resources on first access. Each provides an empty `Init()` method to allow explicit initialization timing (e.g., during splash screen).
+
+### Substring Sharing
+`UString` instances share their backing `UCodepoint[]` array. Substrings store `_startIndex` and `Length` offsets into the parent array rather than copying. This makes substring operations O(1) but means the parent array stays in memory as long as any substring exists.
+
+### Memory Pooling
+`UStringBuilder` uses `ArrayPool<UCodepoint>.Shared` for buffer management. **Must be disposed** to return buffers to the pool. The finalizer also returns the buffer, but relying on it is inefficient.
+
+## Design Patterns
+
+### Facade Pattern
+`UCodepoint` acts as a facade for Unicode property lookups. Static methods like `GetUnicodeCategory()`, `IsWhiteSpace()`, `ToUpper()` delegate to `UnicodeData` or `UnicodeProperties` internally.
+
+### Value Type Wrapper
+`UCodepoint` is a readonly struct wrapping a single `int _value`. Provides implicit conversion from `char` (for BMP characters) and explicit conversions to/from `int`. Operator overloads allow direct comparison with integers and chars.
+
+### Internal Namespace Separation
+`UnicodeHelper.Internal` contains implementation helpers not part of the public API:
+- `DataHelper` - Resource loading and CSV parsing configuration
+- `NormalizationEngine` - Unicode normalization (ported from W3C reference)
+- `HelperUtils` - Canonical sorting, text direction algorithm
+- `UnicodeConversion` - String-to-enum conversions for Unicode data files
+
+## Key Implementation Details
+
+### Unicode Data File Format
+Uses CsvHelper with semicolon delimiter (`Delimiter = ";"`) to parse Unicode Consortium data files. Comment character is `#`. Configuration in `DataHelper.CsvConfiguration`.
+
+### Normalization Implementation
+`NormalizationEngine` is ported from the W3C reference implementation. Handles Hangul syllable decomposition/composition separately using algorithmic approach (constants `SBase`, `LBase`, `VBase`, `TBase`). Decomposition mappings are pre-expanded fully during initialization.
+
+### Bidi Default Values
+`UnicodeData.Init()` sets default bidirectional classes by range before loading actual data. Ranges follow DerivedBidiClass.txt specification (e.g., 0x0590-0x05FF defaults to RightToLeft).
+
+### Combining Key Encoding
+Composition/decomposition lookups use packed keys:
+- Decomposition: `(compatMapping << 21) | codepoint` as `int`
+- Composition: `(compatMapping << 42) | (base << 21) | combining` as `long`
+
+## Work-in-Progress Methods
+
+These `UString` methods throw `NotImplementedException`:
+- `IndexOf(UString, ...)` - substring search
+- `LastIndexOf(UString, ...)`
+- `StartsWith(UString, ...)`
+- `EndsWith(UString, ...)`
+- `Contains(...)`
+
+## Gotchas
+
+1. **UStringBuilder disposal**: Failure to dispose leaks pooled arrays. Always use `using` statement.
+
+2. **CharLength vs Length**: `UString.Length` counts codepoints; `CharLength` counts UTF-16 chars (different for upper-plane characters).
+
+3. **Initialization time**: First access to `UnicodeData` takes ~300ms, `UnicodeProperties` ~150ms. Consider calling `Init()` during app startup.
+
+4. **Explicit cast required**: Converting `UCodepoint` to `int` or `char` requires explicit cast: `(int)uc`, `(char)uc`.

UnicodeHelper/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+@AGENTS.md

UnicodeHelper/Internal/UnicodeConversion.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.Globalization;
 
@@ -155,28 +156,31 @@ internal static class UnicodeConversion
 
         public static UnicodeCategory ConvertCategory(string categoryStr)
         {
-            return strToCategoryMap[categoryStr];
+            return strToCategoryMap.TryGetValue(categoryStr, out UnicodeCategory cat) ? cat : 
+                throw new ArgumentException("Unknown category " + categoryStr);
         }
 
         public static UnicodeBidiClass ConvertBidiClass(string bidiClassStr)
         {
-            return strToBidiClassMap[bidiClassStr];
+            return strToBidiClassMap.TryGetValue(bidiClassStr, out UnicodeBidiClass bidiClass) ? bidiClass : 
+                throw new ArgumentException("Unknown bi-di class " + bidiClassStr);
         }
 
         public static UnicodeProperty ConvertProperty(string propertyStr)
         {
-            return strToPropertyMap[propertyStr];
+            return strToPropertyMap.TryGetValue(propertyStr, out UnicodeProperty prop) ? prop : 
+                throw new ArgumentException("Unknown property " + propertyStr);
         }
 
         public static double ConvertNumeric(string numericStr)
         {
             string[] numbers = numericStr.Split('/');
-            double value = double.Parse(numbers[0]);
+            double value = double.Parse(numbers[0], CultureInfo.InvariantCulture);
             if (numbers.Length == 1) 
                 return value;
 
             Debug.Assert(numbers.Length == 2);
-            double bottom = double.Parse(numbers[1]);
+            double bottom = double.Parse(numbers[1], CultureInfo.InvariantCulture);
             return value / bottom;
         }
     }

UnicodeHelper/NameInfo.cs

@@ -6,7 +6,7 @@ namespace UnicodeHelper
     /// Contains name information about a character
     /// </summary>
     [PublicAPI]
-    public sealed class NameInfo
+    public readonly struct NameInfo
     {
         internal NameInfo(string name, NameType nameType)
         {

UnicodeHelper/UCodepoint.cs

@@ -68,12 +68,12 @@ public static UCodepoint FromChar(char c)
             return new UCodepoint(c);
         }
 
-        internal UCodepoint(char value)
+        private UCodepoint(char value)
         {
             _value = value;
         }
 
-        internal UCodepoint(int value)
+        private UCodepoint(int value)
         {
             _value = value;
         }

UnicodeHelper/UString.cs

@@ -2,6 +2,7 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Text;
 using UnicodeHelper.Internal;
@@ -14,7 +15,7 @@ namespace UnicodeHelper
     [PublicAPI]
     public sealed class UString : 
         IEquatable<UString>, 
-        IEnumerable<UCodepoint>,
+        IReadOnlyList<UCodepoint>,
         ICloneable,
         IComparable,
         IComparable<UString>
@@ -29,7 +30,7 @@ public sealed class UString :
         /// <summary>Index of the codepoint in the array where this string starts (for a substring)</summary>
         private readonly int _startIndex;
 
-        private int _cachedHash;
+        private int? _cachedHash;
         #endregion
 
         #region Constructors
@@ -87,20 +88,36 @@ public UString(string dotNetString, int startIndex, int count)
             if (startIndex + count > dotNetString.Length)
                 throw new ArgumentException("startIndex and count must reside in the string");
 
-            UCodepoint[] codepoints = new UCodepoint[count];
-            int index = 0;
+            // Memory allocation and copying is slow enough that it's slightly faster to calculate the correct size
+            // than it is to guess and resize when finished.
             int end = startIndex + count;
+            int totalCodePointCount = 0;
+            for (int i = startIndex; i < end; i++)
+            {
+                totalCodePointCount++;
+                if (char.IsHighSurrogate(dotNetString[i]))
+                {
+                    int nextIndex = i + 1;
+                    if (nextIndex < end && char.IsLowSurrogate(dotNetString[nextIndex]))
+                        i++; // Step over low surrogate
+                }
+            }
+
+            UCodepoint[] codepoints = new UCodepoint[totalCodePointCount];
+            int codePointIndex = 0;
             for (int i = startIndex; i < end; i++)
             {
                 UCodepoint uc = UCodepoint.ReadFromStr(dotNetString, i);
-                codepoints[index++] = uc;
+                codepoints[codePointIndex++] = uc;
                 if (uc > 0xFFFF)
                     i++; // Step over low surrogate
             }
 
+            Debug.Assert(totalCodePointCount == codePointIndex, "Precalculation of size was incorrect");
+
             _codepoints = codepoints;
             _startIndex = 0;
-            Length = index;
+            Length = totalCodePointCount;
         }
 
         internal UString(int start, int length, UCodepoint[] codepoints)
@@ -138,6 +155,13 @@ public int CharLength
                 return charCount;
             }
         }
+        #endregion
+
+        #region Implementation of IReadOnlyList
+        /// <summary>
+        /// Gets the number of Unicode codepoints that make up this Unicode string
+        /// </summary>
+        public int Count => Length;
 
         /// <summary>
         /// Gets the Unicode codepoint at the specified index in this Unicode string
@@ -440,7 +464,7 @@ public int IndexOf(UCodepoint value, int startIndex, int count)
         /// </summary>
         public int LastIndexOf(UCodepoint value)
         {
-            return LastIndexOf(value, Length - 1, Length);
+            return Length == 0 ? -1 : LastIndexOf(value, Length - 1, Length);
         }
 
         /// <summary>
@@ -464,6 +488,8 @@ public int LastIndexOf(UCodepoint value, int startIndex, int count)
                 throw new ArgumentOutOfRangeException(nameof(count), "count is less than zero");
             if (startIndex >= Length)
                 throw new ArgumentOutOfRangeException(nameof(startIndex), "startIndex must be less than the length of the string");
+            if (startIndex < 0)
+                throw new ArgumentOutOfRangeException(nameof(startIndex), "startIndex must be greater than zero");
             if (startIndex - count + 1 < 0)
                 throw new ArgumentException("StartIndex and count must reside in the string");
 
@@ -782,15 +808,17 @@ public TextDirection DetermineDirection()
         public override int GetHashCode()
         {
             // TODO: Write tests for this method
-            if (_cachedHash != 0)
-                return _cachedHash;
-            
-            HashCode hc = new HashCode();
-            int end = _startIndex + Length;
-            for (int i = _startIndex; i < end; i++)
-                hc.Add(_codepoints[i]);
+            if (_cachedHash == null)
+            {
+                HashCode hc = new HashCode();
+                int end = _startIndex + Length;
+                for (int i = _startIndex; i < end; i++)
+                    hc.Add(_codepoints[i]);
+
+                _cachedHash = hc.ToHashCode();
+            }
 
-            return _cachedHash = hc.ToHashCode();
+            return _cachedHash.Value;
         }
 
         /// <inheritdoc />