Added more StringSegment methods.

Author: electricessence

Source/Extensions.StringSegment.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Diagnostics.Contracts;
+using System.Text.RegularExpressions;
 
 namespace Open.Text
 {
@@ -44,6 +45,26 @@ public static StringSegment First(this string source, string search, StringCompa
 			return i == -1 ? default : StringSegment.Create(source, i, search.Length);
 		}
 
+		/// <summary>
+		/// Finds the first instance of a pattern and returns a StringSegment for subsequent use.
+		/// </summary>
+		/// <param name="source">The source string to search.</param>
+		/// <param name="pattern">The pattern to look for.</param>
+		/// <returns>
+		/// The segment representing the found string.
+		/// If not found, the StringSegment.IsValid property will be false.
+		/// </returns>
+		/// <remarks>If the pattern is right-to-left, then it will return the first segment from the right.</remarks>
+		public static StringSegment First(this string source, Regex pattern)
+		{
+			if (source is null) throw new ArgumentNullException(nameof(source));
+			if (pattern is null) throw new ArgumentNullException(nameof(pattern));
+			Contract.EndContractBlock();
+
+			var match = pattern.Match(source);
+			return match.Success ? StringSegment.Create(source, match.Index, match.Length) : default;
+		}
+
 		/// <inheritdoc cref="First(string, string, StringComparison)" />
 		public static StringSegment First(this StringSegment source, in ReadOnlySpan<char> search, StringComparison comparisonType = StringComparison.Ordinal)
 		{
@@ -83,6 +104,23 @@ public static StringSegment Last(this string source, string search, StringCompar
 			return i == -1 ? default : StringSegment.Create(source, i, search.Length);
 		}
 
+		/// <inheritdoc cref="First(string, Regex)"/>
+		/// <summary>
+		/// Finds the last instance of a pattern and returns a StringSegment for subsequent use.
+		/// </summary>
+		/// <remarks>If the pattern is right-to-left, then it will return the last segment from the right (first segment from the left).</remarks>
+		public static StringSegment Last(this string source, Regex pattern)
+		{
+			if (source is null) throw new ArgumentNullException(nameof(source));
+			if (pattern is null) throw new ArgumentNullException(nameof(pattern));
+			Contract.EndContractBlock();
+
+			var matches = pattern.Matches(source);
+			if (matches.Count == 0) return default;
+			var match = matches[matches.Count - 1];
+			return StringSegment.Create(source, match.Index, match.Length);
+		}
+
 		/// <inheritdoc cref="Last(string, string, StringComparison)" />
 		public static StringSegment Last(this StringSegment source, in ReadOnlySpan<char> search, StringComparison comparisonType = StringComparison.Ordinal)
 		{

Source/Open.Text.csproj

@@ -17,7 +17,7 @@
 		<RepositoryUrl>https://github.com/Open-NET-Libraries/Open.Text</RepositoryUrl>
 		<RepositoryType>git</RepositoryType>
 		<PackageTags>dotnet, dotnetcore, string, span, readonlyspan, text, format, split, trim, first, last, preceding, following, stringbuilder, extensions</PackageTags>
-		<Version>3.0.1</Version>
+		<Version>3.1.0</Version>
 		<PackageReleaseNotes></PackageReleaseNotes>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>
 		<PublishRepositoryUrl>true</PublishRepositoryUrl>

Source/StringSegment.cs

@@ -84,6 +84,50 @@ public StringSegment Following(int maxCharacters)
 			return new(Source, start, Math.Min(maxCharacters, len - start));
 		}
 
+		/// <summary>
+		/// Creates a StringSegment that starts offset by the value provided.
+		/// </summary>
+		/// <param name="offset">The value (positive or negative) to move the index by and adjust the length.</param>
+		public StringSegment OffsetIndex(int offset)
+		{
+			if (!IsValid) return default;
+			var newIndex = Index + offset;
+			if (newIndex < 0) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot index less than the start of the string.");
+			if (offset>Length) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot index greater than the length of the segment.");
+			return new(Source, newIndex, Length - offset);
+		}
+
+		/// <summary>
+		/// Creates a StringSegment modifies the length by the value provided.
+		/// </summary>
+		/// <param name="offset">The value (positive or negative) to adjust the length.</param>
+		public StringSegment OffsetLength(int offset)
+		{
+			if (!IsValid) return default;
+			var newLength = Length + offset;
+			if (newLength < 0) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot shrink less than the start of the string.");
+			if (Index + newLength > Source.Length) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot expand greater than the length of the source.");
+			return new(Source, Index, newLength);
+		}
+
+		/// <summary>
+		/// Creates a StringSegment that starts offset by the value provided and extends by the length provided.
+		/// </summary>
+		/// <param name="offset">The value (positive or negative) to move the index by.</param>
+		/// <param name="length">The length desired.</param>
+		/// <param name="ignoreLengthBoundary">
+		///	If true, the length can exceed the segment length but not past the full length of the source string.
+		///	If false (default), an ArgumentOutOfRangeException will be thrown if the expected length exeeds the segment.
+		///	</param>
+		public StringSegment Slice(int offset, int length)
+		{
+			if (!IsValid) return default;
+			var newIndex = Index + offset;
+			if (Index + offset < 0) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot index less than the start of the string.");
+			if (offset > Length) throw new ArgumentOutOfRangeException(nameof(offset), offset, "Cannot index greater than the length of the segment.");
+			return new(Source, newIndex, Length - offset);
+		}
+
 		/// <summary>
 		/// Returns true if the other string segment values match.
 		/// </summary>

Tests/BeforeAfterTests.cs

@@ -56,5 +56,17 @@ public static void AfterLast(string source, string pattern, string? expected, St
 			if (expected is null) Assert.False(last.IsValid);
 			else Assert.Equal(expected, last.Following().ToString());
 		}
+
+		[Fact]
+		public static void Offsets()
+		{
+			var segment = "Hello well how are you".First("well how");
+			Assert.Equal("well", segment.OffsetLength(-4).ToString());
+			Assert.Equal("how", segment.OffsetIndex(+5).ToString());
+			Assert.Equal("well how are", segment.OffsetLength(+4).ToString());
+			Assert.Equal("Hello well how", segment.OffsetIndex(-6).ToString());
+			Assert.Throws<ArgumentOutOfRangeException>(() => segment.OffsetIndex(-7));
+			Assert.Throws<ArgumentOutOfRangeException>(() => segment.OffsetLength(9));
+		}
 	}
 }