Feature: Refine documentation and logic in RangeData extensions for clarity and consistency

Author: Mykyta Zotov

README.md

@@ -1628,7 +1628,7 @@ public void ValidateCoordinates(double lat, double lon)
 
 - **Lazy evaluation:** `RangeData` builds **iterator graphs** using `IEnumerable`. Data is only materialized when iterated. Operations like `Skip`, `Take`, `Concat` do **not allocate new arrays or lists**.
 - **Domain-awareness:** Supports any discrete domain via `IRangeDomain<T>`. This allows flexible steps, custom metrics, and ensures consistent range arithmetic.
-- **Strict invariant:** The **range length always equals the data sequence length**. Operations that would violate this invariant are not allowed.
+- **Expected invariant/contract:** The **range length should equal the data sequence length**. `RangeData` and `RangeDataExtensions` do **not** enforce this at runtime for performance reasons; callers are responsible for providing consistent inputs or can validate them (for example with `IsValid`) when safety is more important than allocation/CPU overhead.
 - **Right-biased operations:** `Union` and `Intersect` always take **data from the right operand** in overlapping regions, ideal for cache updates or incremental data ingestion.
 - **Composable slices:** Supports trimming (`TrimStart`, `TrimEnd`) and projections while keeping laziness intact. You can work with a `RangeData` without ever iterating the data.
 - **Trade-offs:** Zero allocation is **not fully achievable** because `IEnumerable` is a reference type. Some intermediate enumerables may exist, but memory usage remains minimal.

src/Intervals.NET.Data/Extensions/EnumerableExtensions.cs

@@ -1,3 +1,4 @@
+using Intervals.NET;
 using Intervals.NET.Domain.Abstractions;
 
 namespace Intervals.NET.Data.Extensions;

src/Intervals.NET.Data/Extensions/RangeDataExtensions.cs

@@ -1,4 +1,5 @@
 using System.Runtime.CompilerServices;
+using Intervals.NET;
 using Intervals.NET.Domain.Abstractions;
 using Intervals.NET.Extensions;
 
@@ -23,7 +24,7 @@ namespace Intervals.NET.Data.Extensions;
 /// <list type="bullet">
 /// <item><description><strong>Immutability:</strong> All operations return new instances; no mutation occurs.</description></item>
 /// <item><description><strong>Domain-Agnostic:</strong> Operations work with any <see cref="IRangeDomain{T}"/> implementation.</description></item>
-/// <item><description><strong>Consistency Guarantee:</strong> Extensions never create RangeData with mismatched range/data lengths.</description></item>
+/// <item><description><strong>Consistency Guarantee:</strong> Extensions are designed not to create RangeData with mismatched range/data lengths when the input RangeData instances satisfy the invariant.</description></item>
 /// <item><description><strong>Lazy Evaluation:</strong> Data sequences use LINQ operators; materialization is deferred.</description></item>
 /// </list>
 /// 
@@ -377,7 +378,6 @@ static IEnumerable<TDataType> HandleStaleWrapsFresh(
     /// Trims the start of the range to a new start value, adjusting data accordingly.
     /// <para>
     /// Returns a new RangeData with the trimmed range and sliced data.
-    /// If trimming removes the entire range, returns null.
     /// </para>
     /// <para>
     /// ⚡ <strong>Performance:</strong> O(n) where n is the number of elements to skip.
@@ -394,8 +394,10 @@ static IEnumerable<TDataType> HandleStaleWrapsFresh(
     /// The type of the range domain that implements IRangeDomain&lt;TRangeType&gt;.
     /// </typeparam>
     /// <returns>
-    /// A new RangeData with the trimmed range and sliced data,
-    /// or null if the new start is not within the current range.
+    /// A new RangeData with the trimmed range and sliced data if the new start is within the current range;
+    /// <c>null</c> if the new start lies completely outside the original range;
+    /// a non-null RangeData with an empty range and empty data sequence if trimming results in a logically empty 
+    /// but still in-bounds range (for example, the start equals the end with at least one boundary exclusive).
     /// </returns>
     /// <remarks>
     /// <para><strong>Example:</strong></para>

tests/Intervals.NET.Data.Tests/Extensions/RangeDataExtensionsTests.cs

@@ -105,8 +105,8 @@ public void Intersect_WithOneRangeContainedInAnother_ReturnsSmaller()
     public void Union_WithAdjacentRanges_ReturnsUnion()
     {
         // Arrange
-        var data1 = new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; // [10, 20]
-        var data2 = new[] { 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 }; // (20, 30]
+        var data1 = new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; // [10, 20] - 11 elements
+        var data2 = new[] { 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 }; // (20, 30] - 10 elements
 
         var rd1 = new RangeData<int, int, IntegerFixedStepDomain>(
             Range.Closed<int>(10, 20), data1, _domain);
@@ -120,7 +120,7 @@ public void Union_WithAdjacentRanges_ReturnsUnion()
         Assert.NotNull(result);
         Assert.Equal(10, result.Range.Start.Value);
         Assert.Equal(30, result.Range.End.Value);
-        Assert.Equal(22, result.Data.Count()); // 11 + 11 elements
+        Assert.Equal(21, result.Data.Count()); // 11 + 10 elements
     }
 
     [Fact]