Implement cached sequence walkers for optimized isElement function calls

This commit implements cached versions of sequence walkers to optimize performance
by caching the results of isElement function calls, addressing issue #32.

## Changes:

### New Classes:
- `CachedSequenceWalkerBase<TLinkAddress>`: Abstract base class that extends
  `SequenceWalkerBase` with caching functionality for isElement calls
- `CachedLeftSequenceWalker<TLinkAddress>`: Cached version of LeftSequenceWalker
- `CachedRightSequenceWalker<TLinkAddress>`: Cached version of RightSequenceWalker
- `CachedLeveledSequenceWalker<TLinkAddress>`: Cached version of LeveledSequenceWalker

### Features:
- Dictionary-based caching to store isElement results per link address
- `ClearCache()` method to reset cache when needed
- `GetCacheSize()` method for cache inspection and debugging
- Same constructors as original walkers for drop-in compatibility
- All original functionality preserved with performance optimization

### Tests:
- `CachedWalkersTests`: Unit tests validating caching behavior and constructor functionality
- Tests verify that cached calls reduce isElement function invocations
- Tests ensure cache management methods work correctly

## Performance Benefits:
- Reduces repeated isElement function calls for the same link addresses
- Especially beneficial for sequence traversals that revisit elements
- Maintains identical behavior to original walkers while improving performance

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: konard

csharp/Platform.Data.Doublets.Sequences.Tests/CachedWalkersTests.cs

@@ -0,0 +1,89 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Numerics;
+using Xunit;
+using Platform.Collections;
+using Platform.Collections.Stacks;
+using Platform.Data.Doublets.Memory;
+using Platform.Data.Doublets.Memory.United.Generic;
+using Platform.Data.Doublets.Sequences.Walkers;
+using Platform.Memory;
+using TLinkAddress = System.UInt16;
+
+namespace Platform.Data.Doublets.Sequences.Tests
+{
+    public class CachedWalkersTests
+    {
+        [Fact]
+        public void CachedSequenceWalkerBaseTest()
+        {
+            var linksConstants = new LinksConstants<TLinkAddress>(enableExternalReferencesSupport: true);
+            var storageFileName = new IO.TemporaryFile().Filename;
+            var storageMemory = new FileMappedResizableDirectMemory(storageFileName);
+            var links = new UnitedMemoryLinks<TLinkAddress>(storageMemory, UnitedMemoryLinks<TLinkAddress>.DefaultLinksSizeStep, linksConstants, IndexTreeType.Default);
+            var stack = new DefaultStack<TLinkAddress>();
+            var isElementCallCount = 0;
+            
+            bool IsElement(TLinkAddress link)
+            {
+                isElementCallCount++;
+                return links.IsPartialPoint(link);
+            }
+
+            var cachedWalker = new CachedLeftSequenceWalker<TLinkAddress>(links, stack, IsElement);
+
+            // Create some test elements
+            var element1 = links.Create();
+
+            // Reset call count before testing
+            isElementCallCount = 0;
+
+            // Test caching by calling IsElement multiple times on same element through reflection
+            var isElementMethod = cachedWalker.GetType().GetMethod("IsElement", 
+                System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
+            
+            var result1 = isElementMethod?.Invoke(cachedWalker, new object[] { element1 });
+            var result2 = isElementMethod?.Invoke(cachedWalker, new object[] { element1 });
+
+            // Should have been called only once due to caching
+            Assert.Equal(1, isElementCallCount);
+            Assert.Equal(result1, result2);
+
+            // Cache should contain one element
+            Assert.Equal(1, cachedWalker.GetCacheSize());
+
+            // Clear cache
+            cachedWalker.ClearCache();
+            Assert.Equal(0, cachedWalker.GetCacheSize());
+
+            links.Dispose();
+        }
+
+        [Fact]
+        public void CachedWalkerConstructorTest()
+        {
+            var linksConstants = new LinksConstants<TLinkAddress>(enableExternalReferencesSupport: true);
+            var storageFileName = new IO.TemporaryFile().Filename;
+            var storageMemory = new FileMappedResizableDirectMemory(storageFileName);
+            var links = new UnitedMemoryLinks<TLinkAddress>(storageMemory, UnitedMemoryLinks<TLinkAddress>.DefaultLinksSizeStep, linksConstants, IndexTreeType.Default);
+            var stack = new DefaultStack<TLinkAddress>();
+            
+            // Test that constructors work without throwing exceptions
+            var cachedLeftWalker = new CachedLeftSequenceWalker<TLinkAddress>(links, stack);
+            var cachedRightWalker = new CachedRightSequenceWalker<TLinkAddress>(links, stack);
+            var cachedLeveledWalker = new CachedLeveledSequenceWalker<TLinkAddress>(links);
+
+            Assert.NotNull(cachedLeftWalker);
+            Assert.NotNull(cachedRightWalker);
+            Assert.NotNull(cachedLeveledWalker);
+
+            // All should start with empty cache
+            Assert.Equal(0, cachedLeftWalker.GetCacheSize());
+            Assert.Equal(0, cachedRightWalker.GetCacheSize());
+            Assert.Equal(0, cachedLeveledWalker.GetCacheSize());
+
+            links.Dispose();
+        }
+    }
+}

csharp/Platform.Data.Doublets.Sequences/Walkers/CachedLeftSequenceWalker.cs

@@ -0,0 +1,122 @@
+using System;
+using System.Collections.Generic;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using Platform.Collections.Stacks;
+
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
+
+namespace Platform.Data.Doublets.Sequences.Walkers
+{
+    /// <summary>
+    /// <para>
+    /// Represents the cached left sequence walker.
+    /// </para>
+    /// <para></para>
+    /// </summary>
+    /// <seealso cref="CachedSequenceWalkerBase{TLinkAddress}"/>
+    public class CachedLeftSequenceWalker<TLinkAddress> : CachedSequenceWalkerBase<TLinkAddress> where TLinkAddress : struct, IUnsignedNumber<TLinkAddress>, IComparisonOperators<TLinkAddress, TLinkAddress, bool>
+    {
+        /// <summary>
+        /// <para>
+        /// Initializes a new <see cref="CachedLeftSequenceWalker"/> instance.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="links">
+        /// <para>A links.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="stack">
+        /// <para>A stack.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="isElement">
+        /// <para>A is element.</para>
+        /// <para></para>
+        /// </param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public CachedLeftSequenceWalker(ILinks<TLinkAddress> links, IStack<TLinkAddress> stack, Func<TLinkAddress, bool> isElement) : base(links, stack, isElement) { }
+
+        /// <summary>
+        /// <para>
+        /// Initializes a new <see cref="CachedLeftSequenceWalker"/> instance.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="links">
+        /// <para>A links.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="stack">
+        /// <para>A stack.</para>
+        /// <para></para>
+        /// </param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public CachedLeftSequenceWalker(ILinks<TLinkAddress> links, IStack<TLinkAddress> stack) : base(links, stack, links.IsPartialPoint) { }
+
+        /// <summary>
+        /// <para>
+        /// Gets the next element after pop using the specified element.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="element">
+        /// <para>The element.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The link</para>
+        /// <para></para>
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        protected override TLinkAddress GetNextElementAfterPop(TLinkAddress element) => _links.GetSource(element);
+
+        /// <summary>
+        /// <para>
+        /// Gets the next element after push using the specified element.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="element">
+        /// <para>The element.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The link</para>
+        /// <para></para>
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        protected override TLinkAddress GetNextElementAfterPush(TLinkAddress element) => _links.GetTarget(element);
+
+        /// <summary>
+        /// <para>
+        /// Walks the contents using the specified element.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="element">
+        /// <para>The element.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>An enumerable of t link</para>
+        /// <para></para>
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        protected override IEnumerable<TLinkAddress> WalkContents(TLinkAddress element)
+        {
+            var links = _links;
+            var parts = links.GetLink(element);
+            var start = links.Constants.SourcePart;
+            for (var i = parts.Count - 1; i >= start; i--)
+            {
+                var part = parts[i];
+                if (IsElement(part))
+                {
+                    yield return part;
+                }
+            }
+        }
+    }
+}