feat: introduce operator overloads for Union, Intersect, and Except in RangeSet

Added `|`, `&`, and `-` operator overloads to simplify union, intersection, and difference operations on `RangeSet`. Updated `README.md` with examples of the new operator usage.

Author: CaffeinatedCoder

CodoMetis.ValueRanges/RangeSet.cs

@@ -164,6 +164,27 @@ public RangeSet<TRange, T> Union(RangeSet<TRange, T> other) =>
         other.Count == 0 ? this :
         Count       == 0 ? other : From(_elements.Concat(other._elements));
 
+    /// <summary>
+    /// Returns the union of <paramref name="left"/> and <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to add to.</param>
+    /// <param name="right">The range to add.</param>
+    /// <returns>
+    /// A normalized set containing every value of <paramref name="left"/> and of <paramref name="right"/>;
+    /// the range is merged into existing elements where it overlaps or is adjacent.
+    /// </returns>
+    public static RangeSet<TRange, T> operator |(RangeSet<TRange, T> left, TRange right) =>
+        left.Union(right);
+
+    /// <summary>
+    /// Returns the union of <paramref name="left"/> and <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to add to.</param>
+    /// <param name="right">The set to combine with.</param>
+    /// <returns>A normalized set containing every value of both sets.</returns>
+    public static RangeSet<TRange, T> operator |(RangeSet<TRange, T> left, RangeSet<TRange, T> right) =>
+        left.Union(right);
+
     /// <summary>
     /// Returns the intersection of this set with <paramref name="other"/>.
     /// </summary>
@@ -206,6 +227,27 @@ public RangeSet<TRange, T> Intersect(RangeSet<TRange, T> other)
         return From(results);
     }
 
+    /// <summary>
+    /// Returns the intersection of <paramref name="left"/> with <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to intersect.</param>
+    /// <param name="right">The range to intersect with.</param>
+    /// <returns>
+    /// A set containing, for each element of <paramref name="left"/>, its overlap with <paramref name="right"/>;
+    /// <see cref="Empty"/> when nothing overlaps.
+    /// </returns>
+    public static RangeSet<TRange, T> operator &(RangeSet<TRange, T> left, TRange right) =>
+        left.Intersect(right);
+
+    /// <summary>
+    /// Returns the intersection of <paramref name="left"/> with <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to intersect.</param>
+    /// <param name="right">The set to intersect with.</param>
+    /// <returns>A normalized set containing the values common to both sets.</returns>
+    public static RangeSet<TRange, T> operator &(RangeSet<TRange, T> left, RangeSet<TRange, T> right) =>
+        left.Intersect(right);
+
     /// <summary>
     /// Returns what remains of this set after removing every value covered by <paramref name="other"/>.
     /// </summary>
@@ -233,6 +275,27 @@ public RangeSet<TRange, T> Except(TRange other)
     public RangeSet<TRange, T> Except(RangeSet<TRange, T> other) =>
         Enumerable.Aggregate(other._elements, this, (current, range) => current.Except(range));
 
+    /// <summary>
+    /// Returns what remains of <paramref name="left"/> after removing every value covered by <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to subtract from.</param>
+    /// <param name="right">The range to subtract.</param>
+    /// <returns>
+    /// A normalized set of the remaining pieces; an element split by
+    /// <paramref name="right"/> contributes both of its parts.
+    /// </returns>
+    public static RangeSet<TRange, T> operator -(RangeSet<TRange, T> left, TRange right) =>
+        left.Except(right);
+
+    /// <summary>
+    /// Returns what remains of <paramref name="left"/> after removing every value covered by <paramref name="right"/>.
+    /// </summary>
+    /// <param name="left">The set to subtract from.</param>
+    /// <param name="right">The set to subtract.</param>
+    /// <returns>A normalized set of the remaining pieces.</returns>
+    public static RangeSet<TRange, T> operator -(RangeSet<TRange, T> left, RangeSet<TRange, T> right) =>
+        left.Except(right);
+
     /// <summary>
     /// Returns the complement of this set — every value of the domain not covered by it.
     /// </summary>

README.md

@@ -241,10 +241,15 @@ set.Contains(7);                              // true
 set.Contains(Int32Range.CreateFinite(2, 8));  // true  — within a single element
 set.Overlaps(Int32Range.CreateFinite(15, 25)); // true
 
-// Set operations — single-range and bulk variants
-set.Union(Int32Range.CreateFinite(11, 19));   // { [1, 30] } — bridges the gap
+// Set operations — single-range and bulk variants, with operator aliases (|, &, -)
+set.Union(Int32Range.CreateFinite(11, 19));    // { [1, 30] } — bridges the gap
+set | Int32Range.CreateFinite(11, 19);         // { [1, 30] }
+
 set.Intersect(Int32Range.CreateFinite(5, 25)); // { [5, 10], [20, 25] }
+set & Int32Range.CreateFinite(5, 25);          // { [5, 10], [20, 25] }
+
 set.Except(Int32Range.CreateFinite(4, 6));     // { [1, 3], [7, 10], [20, 30] }
+set - Int32Range.CreateFinite(4, 6);           // { [1, 3], [7, 10], [20, 30] }
 
 // Complement — every value not covered by the set
 set.Complement();  // { (-∞, 0], [11, 19], [31, +∞) }