Merge branch 'feature-Min-Max' into Span.Min

Author: dragon7307

.github/README.md

@@ -1,5 +1,7 @@
 # SpanExtensions
 
+[![NuGet Badge](https://buildstats.info/nuget/SpanExtensions.Net)](https://www.nuget.org/packages/SpanExtensions.Net)
+
 ## About
 **`ReadonlySpan<T>`** and **`Span<T>`** are great Types in _C#_, but unfortunately working with them can sometimes be sort of a hassle and some use cases seem straight up impossible, even though they are not.  
 
@@ -9,8 +11,6 @@ Never again switch back to using `string` instead of `ReadonlySpan<T>`, just bec
 
 **SpanExtensions.Net** provides alternatives for many missing Extension Methods for **`ReadonlySpan<T>`** and **`Span<T>`**, ranging from `string.Split()` over `Enumerable.Skip()` and `Enumerable.Take()` to an improved `ReadOnlySpan<T>.IndexOf()`.
 
-**SpanExtensions.Net** may also be found on [NuGet](https://www.nuget.org/packages/SpanExtensions.Net).   
-  
 ## Methods 
 The following **Extension Methods** are contained: 
 

.github/workflows/dotnet.yml

@@ -0,0 +1,29 @@
+
+name: .NET
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "dev" ]
+    paths:
+    - '**.cs'
+    - '**.csproj'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+        
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: 8.0.x
+    - name: Restore dependencies
+      run: dotnet restore
+    - name: Build
+      run: dotnet build --no-restore
+    - name: Test
+      run: dotnet test --no-build --verbosity normal

Changelog.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3] - 2024-1-25
+
+### Changed 
+
+- documentation comments to better reflect the dotnet style (https://github.com/draconware-dev/SpanExtensions.Net/pull/8)
+
 ## [1.2.1] - 2024-1-25
 
 ### Fixed 

src/CountExceedingBehaviour.cs

@@ -0,0 +1,17 @@
+namespace SpanExtensions
+{
+    /// <summary>
+    /// Defines the behaviour of a split operation when there are more split instances than there may be. 
+    /// </summary> 
+    public enum CountExceedingBehaviour
+    {
+        /// <summary>
+        /// The last element returned will be all the remaining elements appended as one.
+        /// </summary>
+        AppendLastElements,
+        /// <summary>
+        /// Every split instance more than permitted will not be returned. 
+        /// </summary> 
+        CutLastElements
+    }
+}

src/Enumerators/Split/SpanSplitEnumerator.cs

@@ -5,29 +5,34 @@ namespace SpanExtensions.Enumerators
     /// <summary>
     /// Supports iteration over a <see cref="ReadOnlySpan{T}"/> by splitting it at a specified delimiter of type <typeparamref name="T"/>.
     /// </summary>
-    /// <typeparam name="T">The type of elements in the enumerated <see cref="ReadOnlySpan{T}"/></typeparam>
+    /// <typeparam name="T">The type of elements in the enumerated <see cref="ReadOnlySpan{T}"/>.</typeparam>
     public ref struct SpanSplitEnumerator<T> where T : IEquatable<T>
     {
         ReadOnlySpan<T> Span;
         readonly T Delimiter;
+        bool enumerationDone;
 
         /// <summary>
-        /// Gets the element in the collection at the current position of the enumerator. 
+        /// Gets the element in the collection at the current position of the enumerator.
         /// </summary>
         public ReadOnlySpan<T> Current { get; internal set; }
 
         /// <summary>
-        /// Constructs a <see cref="SpanSplitEnumerator{T}"/> from a span and a delimiter. ONLY CONSUME THIS CLASS THROUGH <see cref="ReadOnlySpanExtensions.Split{T}(ReadOnlySpan{T}, T)"/>. 
+        /// Constructs a <see cref="SpanSplitEnumerator{T}"/> from a span and a delimiter. <strong>Only consume this class through <see cref="ReadOnlySpanExtensions.Split{T}(ReadOnlySpan{T}, T)"/></strong>.
         /// </summary>
-        /// <param name="source">The <see cref="ReadOnlySpan{T}"/> to be split.</param>  
-        /// <param name="delimiter">An instance of <typeparamref name="T"/> that delimits the various sub-ReadOnlySpans in the <see cref="ReadOnlySpan{T}"/>.</param>
+        /// <param name="source">The <see cref="ReadOnlySpan{T}"/> to be split.</param>
+        /// <param name="delimiter">An instance of <typeparamref name="T"/> that delimits the various sub-ReadOnlySpans in <paramref name="source"/>.</param>
         public SpanSplitEnumerator(ReadOnlySpan<T> source, T delimiter)
         {
             Span = source;
             Delimiter = delimiter;
             Current = default;
+            enumerationDone = false;
         }
-        /// <summary></summary>
+
+        /// <summary>
+        /// Returns an enumerator that iterates through a collection.
+        /// </summary>
         public readonly SpanSplitEnumerator<T> GetEnumerator()
         {
             return this;
@@ -36,19 +41,20 @@ public readonly SpanSplitEnumerator<T> GetEnumerator()
         /// <summary>
         /// Advances the enumerator to the next element of the collection.
         /// </summary>
-        /// <returns><code>true</code> if the enumerator was successfully advanced to the next element; <code>false</code> if the enumerator has passed the end of the collection.</returns>
+        /// <returns><see langword="true"/> if the enumerator was successfully advanced to the next element; <see langword="false"/> if the enumerator has passed the end of the collection.</returns>
         public bool MoveNext()
         {
-            ReadOnlySpan<T> span = Span;
-            if(span.IsEmpty)
+            if(enumerationDone)
             {
                 return false;
             }
+
+            ReadOnlySpan<T> span = Span;
             int index = span.IndexOf(Delimiter);
 
             if(index == -1 || index >= span.Length)
             {
-                Span = ReadOnlySpan<T>.Empty;
+                enumerationDone = true;
                 Current = span;
                 return true;
             }

src/Enumerators/Split/SpanSplitStringSplitOptionsEnumerator.cs

@@ -2,55 +2,61 @@
 
 namespace SpanExtensions.Enumerators
 {
-    /// <summary> 
-    /// Supports iteration over a <see cref="ReadOnlySpan{Char}"/> by splitting it at a specified delimiter and based on specified <see cref="StringSplitOptions"/>.  
-    /// </summary>   
+    /// <summary>
+    /// Supports iteration over a <see cref="ReadOnlySpan{Char}"/> by splitting it at a specified delimiter and based on specified <see cref="StringSplitOptions"/>.
+    /// </summary>
     public ref struct SpanSplitStringSplitOptionsEnumerator
     {
         ReadOnlySpan<char> Span;
         readonly char Delimiter;
         readonly StringSplitOptions Options;
+        bool enumerationDone;
 
         /// <summary>
-        /// Gets the element in the collection at the current position of the enumerator. 
+        /// Gets the element in the collection at the current position of the enumerator.
         /// </summary>
         public ReadOnlySpan<char> Current { get; internal set; }
 
         /// <summary>
-        /// Constructs a <see cref="SpanSplitEnumerator{Char}"/> from a span and a delimiter. ONLY CONSUME THIS CLASS THROUGH <see cref="ReadOnlySpanExtensions.Split(ReadOnlySpan{char}, char, StringSplitOptions)"/>. 
+        /// Constructs a <see cref="SpanSplitStringSplitOptionsEnumerator"/> from a span and a delimiter. <strong>Only consume this class through <see cref="ReadOnlySpanExtensions.Split(ReadOnlySpan{char}, char, StringSplitOptions)"/></strong>.
         /// </summary>
-        /// <param name="source">The <see cref="ReadOnlySpan{Char}"/> to be split.</param>  
-        /// <param name="delimiter">An <see cref="char"/> that delimits the various sub-ReadOnlySpans in the <see cref="ReadOnlySpan{Char}"/>.</param>
+        /// <param name="source">The <see cref="ReadOnlySpan{Char}"/> to be split.</param>
+        /// <param name="delimiter">A <see cref="char"/> that delimits the various sub-ReadOnlySpans in <paramref name="source"/>.</param>
         /// <param name="options">A bitwise combination of the enumeration values that specifies whether to trim results and include empty results.</param>
         public SpanSplitStringSplitOptionsEnumerator(ReadOnlySpan<char> source, char delimiter, StringSplitOptions options)
         {
             Span = source;
             Delimiter = delimiter;
             Options = options;
             Current = default;
+            enumerationDone = false;
         }
-        /// <summary></summary>
+
+        /// <summary>
+        /// Returns an enumerator that iterates through a collection.
+        /// </summary>
         public readonly SpanSplitStringSplitOptionsEnumerator GetEnumerator()
         {
             return this;
         }
-        
+
         /// <summary>
         /// Advances the enumerator to the next element of the collection.
         /// </summary>
-        /// <returns><code>true</code> if the enumerator was successfully advanced to the next element; <code>false</code> if the enumerator has passed the end of the collection.</returns>
+        /// <returns><see langword="true"/> if the enumerator was successfully advanced to the next element; <see langword="false"/> if the enumerator has passed the end of the collection.</returns>
         public bool MoveNext()
         {
-            ReadOnlySpan<char> span = Span;
-            if(span.IsEmpty)
+            if(enumerationDone)
             {
                 return false;
             }
+
+            ReadOnlySpan<char> span = Span;
             int index = span.IndexOf(Delimiter);
 
             if(index == -1 || index >= span.Length)
             {
-                Span = ReadOnlySpan<char>.Empty;
+                enumerationDone = true;
                 Current = span;
                 return true;
             }
@@ -66,8 +72,20 @@ public bool MoveNext()
                 if(Current.IsEmpty)
                 {
                     Span = span[(index + 1)..];
+                    if(Span.IsEmpty)
+                    {
+                        enumerationDone = true;
+                        return false;
+                    }
                     return MoveNext();
                 }
+
+                Span = span[(index + 1)..];
+                if(Span.IsEmpty)
+                {
+                    enumerationDone = true;
+                }
+                return true;
             }
             Span = span[(index + 1)..];
             return true;

src/Enumerators/Split/SpanSplitStringSplitOptionsWithCountEnumerator.cs

@@ -2,32 +2,49 @@
 
 namespace SpanExtensions.Enumerators
 {
-    /// <summary> 
-    /// Supports iteration over a <see cref="ReadOnlySpan{Char}"/> by splitting it at a specified delimiter and based on specified <see cref="StringSplitOptions"/>  with an upper limit of splits performed.  
-    /// </summary>   
+    /// <summary>
+    /// Supports iteration over a <see cref="ReadOnlySpan{Char}"/> by splitting it at a specified delimiter and based on specified <see cref="StringSplitOptions"/>  with an upper limit of splits performed.
+    /// </summary>
     public ref struct SpanSplitStringSplitOptionsWithCountEnumerator
     {
         ReadOnlySpan<char> Span;
         readonly char Delimiter;
         readonly StringSplitOptions Options;
         readonly int Count;
+        readonly CountExceedingBehaviour CountExceedingBehaviour;
         int currentCount;
+        bool enumerationDone;
+        readonly int CountMinusOne;
 
         /// <summary>
-        /// Gets the element in the collection at the current position of the enumerator. 
+        /// Gets the element in the collection at the current position of the enumerator.
         /// </summary>
         public ReadOnlySpan<char> Current { get; internal set; }
 
-        public SpanSplitStringSplitOptionsWithCountEnumerator(ReadOnlySpan<char> source, char delimiter, StringSplitOptions options, int count)
+        /// <summary>
+        /// Constructs a <see cref="SpanSplitStringSplitOptionsWithCountEnumerator"/> from a span and a delimiter. <strong>Only consume this class through <see cref="ReadOnlySpanExtensions.Split(ReadOnlySpan{char}, char, int, StringSplitOptions, CountExceedingBehaviour)"/></strong>.
+        /// </summary>
+        /// <param name="source">The <see cref="ReadOnlySpan{Char}"/> to be split.</param>
+        /// <param name="delimiter">A <see cref="char"/> that delimits the various sub-ReadOnlySpans in <paramref name="source"/>.</param>
+        /// <param name="count">The maximum number of sub-ReadOnlySpans to split into.</param>
+        /// <param name="options">A bitwise combination of the enumeration values that specifies whether to trim results and include empty results.</param>
+        /// <param name="countExceedingBehaviour">The handling of the instances more than count.</param>
+        public SpanSplitStringSplitOptionsWithCountEnumerator(ReadOnlySpan<char> source, char delimiter, int count, StringSplitOptions options, CountExceedingBehaviour countExceedingBehaviour = CountExceedingBehaviour.AppendLastElements)
         {
             Span = source;
             Delimiter = delimiter;
-            Options = options;
             Count = count;
+            CountExceedingBehaviour = countExceedingBehaviour;
+            Options = options;
             Current = default;
             currentCount = 0;
+            enumerationDone = false;
+            CountMinusOne = Math.Max(Count - 1, 0);
         }
-        /// <summary></summary>
+
+        /// <summary>
+        /// Returns an enumerator that iterates through a collection.
+        /// </summary>
         public readonly SpanSplitStringSplitOptionsWithCountEnumerator GetEnumerator()
         {
             return this;
@@ -36,23 +53,44 @@ public readonly SpanSplitStringSplitOptionsWithCountEnumerator GetEnumerator()
         /// <summary>
         /// Advances the enumerator to the next element of the collection.
         /// </summary>
-        /// <returns><code>true</code> if the enumerator was successfully advanced to the next element; <code>false</code> if the enumerator has passed the end of the collection.</returns>
+        /// <returns><see langword="true"/> if the enumerator was successfully advanced to the next element; <see langword="false"/> if the enumerator has passed the end of the collection.</returns>
         public bool MoveNext()
         {
-            ReadOnlySpan<char> span = Span;
-            if(span.IsEmpty)
+            if(enumerationDone)
             {
                 return false;
             }
+
+            ReadOnlySpan<char> span = Span;
             if(currentCount == Count)
             {
                 return false;
             }
             int index = span.IndexOf(Delimiter);
 
+            switch(CountExceedingBehaviour)
+            {
+                case CountExceedingBehaviour.CutLastElements:
+                    break;
+                case CountExceedingBehaviour.AppendLastElements:
+                    if(currentCount == CountMinusOne)
+                    {
+                        ReadOnlySpan<char> lower = span[..index];
+                        ReadOnlySpan<char> upper = span[(index + 1)..];
+                        Span<char> temp = new char[lower.Length + upper.Length];
+                        lower.CopyTo(temp[..index]);
+                        upper.CopyTo(temp[index..]);
+                        Current = temp;
+                        currentCount++;
+                        return true;
+                    }
+                    break;
+                default:
+                    throw new InvalidCountExceedingBehaviourException(CountExceedingBehaviour);
+            }
             if(index == -1 || index >= span.Length)
             {
-                Span = ReadOnlySpan<char>.Empty;
+                enumerationDone = true;
                 Current = span;
                 return true;
             }
@@ -70,8 +108,20 @@ public bool MoveNext()
                 if(Current.IsEmpty)
                 {
                     Span = span[(index + 1)..];
+                    if(Span.IsEmpty)
+                    {
+                        enumerationDone = true;
+                        return false;
+                    }
                     return MoveNext();
                 }
+
+                Span = span[(index + 1)..];
+                if(Span.IsEmpty)
+                {
+                    enumerationDone = true;
+                }
+                return true;
             }
             Span = span[(index + 1)..];
             return true;