Add zero-allocation Join enumerator with ZLinq ValueEnumerable

- Add StringSegmentJoinEnumerator implementing IValueEnumerator<StringSegment>
- Update Join() to return ValueEnumerable
- Update Replace/ReplaceAsSegments to return ValueEnumerable
- Fix ReplaceEach to use .ToArray() for yield boundary compatibility with .NET 10
- All 955 tests pass

Author: electricessence

BenchmarkDotNet.Artifacts/results/Open.Text.Benchmarks.SplitAsSegmentsBaselineBenchmark-report-github.md

@@ -205,28 +205,15 @@ public static ValueEnumerable<StringSegmentSequenceSplitEnumerator, StringSegmen
 	/// </summary>
 	/// <param name="source">The segments to join.</param>
 	/// <param name="between">The segment to place between each segment.</param>
-	/// <returns>An IEnumerable&lt;StringSegment&gt; of the segments.</returns>
+	/// <returns>A ValueEnumerable of the joined segments (zero-allocation when used with foreach or ZLinq).</returns>
 	/// <exception cref="System.ArgumentNullException">The source is null.</exception>
-	public static IEnumerable<StringSegment> Join(this IEnumerable<StringSegment> source, StringSegment between)
+	[CLSCompliant(false)]
+	public static ValueEnumerable<StringSegmentJoinEnumerator, StringSegment> Join(this IEnumerable<StringSegment> source, StringSegment between)
 	{
 		return source is null
 			? throw new ArgumentNullException(nameof(source))
-			: JoinCore(source, between);
-
-		static IEnumerable<StringSegment> JoinCore(IEnumerable<StringSegment> source, StringSegment between)
-		{
-			using IEnumerator<StringSegment> e = source.GetEnumerator();
-			bool ok = e.MoveNext();
-			Debug.Assert(ok);
-			StringSegment c = e.Current;
-			if (c.Length != 0) yield return c;
-			while (e.MoveNext())
-			{
-				if (between.HasValue) yield return between;
-				c = e.Current;
-				if (c.Length != 0) yield return c;
-			}
-		}
+			: new ValueEnumerable<StringSegmentJoinEnumerator, StringSegment>(
+				new StringSegmentJoinEnumerator(source, between));
 	}
 
 	/// <summary>
@@ -250,8 +237,10 @@ public static string JoinToString(this IEnumerable<StringSegment> source, String
 	/// <summary>
 	/// Splits a sequence and replaces the removed sequences with the replacement sequence.
 	/// </summary>
+	/// <returns>A ValueEnumerable of the segments (zero-allocation when used with foreach or ZLinq).</returns>
 	/// <inheritdoc cref="SplitAsSegments(string, string, StringSplitOptions, StringComparison)"/>
-	public static IEnumerable<StringSegment> Replace(
+	[CLSCompliant(false)]
+	public static ValueEnumerable<StringSegmentJoinEnumerator, StringSegment> Replace(
 		this StringSegment source,
 		StringSegment splitSequence,
 		StringSegment replacement,
@@ -267,14 +256,16 @@ public static string ReplaceToString(this StringSegment source,
 		=> JoinToString(SplitAsSegments(source, splitSequence, comparisonType: comparisonType).ToArray(), replacement);
 
 	/// <inheritdoc cref="Replace(StringSegment, StringSegment, StringSegment, StringComparison)"/>
-	public static IEnumerable<StringSegment> ReplaceAsSegments(
+	[CLSCompliant(false)]
+	public static ValueEnumerable<StringSegmentJoinEnumerator, StringSegment> ReplaceAsSegments(
 		this string source,
 		Regex splitSequence,
 		StringSegment replacement)
 		=> Join(SplitAsSegments(source, splitSequence), replacement);
 
 	/// <inheritdoc cref="Replace(StringSegment, StringSegment, StringSegment, StringComparison)"/>
-	public static IEnumerable<StringSegment> ReplaceAsSegments(
+	[CLSCompliant(false)]
+	public static ValueEnumerable<StringSegmentJoinEnumerator, StringSegment> ReplaceAsSegments(
 		this string source,
 		StringSegment splitSequence,
 		StringSegment replacement,
@@ -299,9 +290,10 @@ static IEnumerable<StringSegment> ReplaceEachCore(IEnumerable<StringSegment> sou
 		{
 			// Instead of source.SelectMany(s => s.Replace(splitSequence, replacement, comparisonType));
 			// we manually yield to reduce allocations.
+			// Note: We use ToArray() to materialize the ValueEnumerable because ref structs cannot be preserved across yield boundaries.
 			foreach (StringSegment s in source)
 			{
-				foreach (StringSegment e in Replace(s, splitSequence, replacement, comparisonType))
+				foreach (StringSegment e in Replace(s, splitSequence, replacement, comparisonType).ToArray())
 					yield return e;
 			}
 		}