Implement ISpanFormattable for DefaultFormatter (#434)

axunonb · web-flow · commit 7ef11f466832 · 2024-07-11T08:28:26.000+02:00
* Initial commit

* Implement ISpanFormattable for DefaultFormatter
* Remove usage of stack buffer for ISpanFormattable in ZCharArray
* Make IFormatProvider an optional argument in ZCharArray.Write overloads
* Add unit tests

* Unit test ISpanFormattable exceeding initial buffer length

* Update class xmldoc
* Add missing pragma NET6_0_OR_GREATER
* Add unit test for ISpanFormattable exceeding buffer on first attempt

* Re-add wiki update checks
diff --git a/.github/workflows/CheckWikiUpdates.yml b/.github/workflows/CheckWikiUpdates.yml
@@ -0,0 +1,59 @@
+name: Check for Wiki Updates
+
+on:
+  workflow_dispatch: # Allows manual trigger
+  # push: # Uncomment to run on push
+  schedule:
+    - cron: '0 0 * * *' # Runs once a day
+
+jobs:
+  check-wiki:
+    if: ${{ github.repository == 'axuno/SmartFormat' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout wiki
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: wiki  # Checkout wiki to wiki folder
+
+      - name: Get last commit date, message and number of commits
+        id: get-info
+        run: |
+            cd wiki
+            DATE=$(git log -1 --format=%cd --date=iso)
+            FORMATTED_DATE=$(date -d"$DATE" +'%Y-%m-%d %H:%M:%S')
+            echo "updatedOn=$FORMATTED_DATE" >> $GITHUB_ENV
+            # The :a;N;$!ba; part buffers the input to ensure that all newline characters are replaced, not just those at the end of each line read
+            printf "commitMessage=\"%s\"\n" "$(git log -1 --pretty=%B | sed ':a;N;$!ba;s/\n/ ↲ /g' | sed "s/'/\\\\'/g")" >> $GITHUB_ENV
+            echo "hash=$(git rev-parse HEAD)" >> $GITHUB_ENV
+            echo "commitCount=$(git rev-list --count --since='24 hours ago' HEAD)" >> $GITHUB_ENV
+      - name: Print variables
+        run: |
+          echo ${{ env.updatedOn }}
+          echo "${{ env.commitMessage }}"
+          echo ${{ env.hash }}
+          echo ${{ env.commitCount }}
+      - name: Checkout main repo
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository }}
+          path: main-repo # Checkout main repo to main-repo folder
+          token: ${{ secrets.WIKI_CHECK_TOKEN }}
+          ref: ${{ github.ref }}
+      - name: Create issue if wiki was updated
+        id: create-issue
+        if: ${{ env.commitCount != '0' }}
+        uses: JasonEtco/create-an-issue@v2.9.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.WIKI_CHECK_TOKEN }}
+          UpdatedOn: ${{ env.updatedOn }}
+          CommitMessage: ${{ env.commitMessage }}
+          CommitCount: ${{ env.commitCount }}
+          Hash: ${{ env.hash }}
+        with:
+          filename: main-repo/.github/workflows/Wiki_Update_Issue_Template.md
+          update_existing: true
+          search_existing: open
+      - name: Show issue URL
+        run: 'echo Created ${{ steps.create-issue.outputs.url }}'
diff --git a/.github/workflows/Wiki_Update_Issue_Template.md b/.github/workflows/Wiki_Update_Issue_Template.md
@@ -0,0 +1,18 @@
+---
+name: Wiki Update
+about: Issue template for updates of the wiki
+title: 'Wiki Update'
+labels: 'Docs'
+assignees: ''
+---
+
+Number of commits  
+made to the Wiki in the last 24 hours: **{{ env.CommitCount }}**
+
+These are the details of the latest commit: 
+
+| Item  | Value  |
+|:---|:---|
+| Date | {{ env.UpdatedOn }} |
+| Hash | [{{ env.Hash }}](https://github.com/axuno/SmartFormat/wiki/_compare/{{ env.Hash }}) |
+| Message | {{ env.commitMessage }} |
diff --git a/src/SmartFormat.Tests/Extensions/DefaultFormatterTests.cs b/src/SmartFormat.Tests/Extensions/DefaultFormatterTests.cs
@@ -69,6 +69,63 @@ public void Call_With_IFormattable_Argument()
 
     #endregion
 
+    #region * ISpanFormattable Test *
+
+#if NET6_0_OR_GREATER
+    [Test]
+    public void ISpanFormattable_Exceeding_Stackalloc_Buffer()
+    {
+        var smart = GetFormatter();
+        var data = new ISpanFormattableTest();
+        var result = smart.Format("{0}", data);
+
+        Assert.Multiple(() =>
+        {
+            // On first attempt, the data will not fit into the buffer
+            Assert.That(data.TrialNo, Is.GreaterThan(1));
+            Assert.That(result, Is.EqualTo(data.ToString()));
+        });
+    }
+
+    internal class ISpanFormattableTest : ISpanFormattable
+    {
+        char[] _buffer;
+
+        internal int TrialNo;
+
+        public ISpanFormattableTest()
+        {
+            _buffer = new char[1024];
+            _buffer.AsSpan().Fill('b');
+        }
+
+        public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
+        {
+            if (++TrialNo == 1 || destination.Length < _buffer.Length)
+            {
+                charsWritten = 0;
+                return false;
+            }
+
+            _buffer.AsSpan().CopyTo(destination);
+            charsWritten = _buffer.Length;
+            return true;
+        }
+
+        public string ToString(string? format, IFormatProvider? formatProvider)
+        {
+            return string.Format(formatProvider, format ?? string.Empty, new string(_buffer));
+        }
+
+        public override string ToString()
+        {
+            return new string(_buffer);
+        }
+    }
+#endif
+
+    #endregion
+
     #region *** Format with custom formatter ***
 
     [TestCase("format", "value", true)]
@@ -113,8 +170,7 @@ public string Format(string? format, object? arg, IFormatProvider? formatProvide
                    new string((arg as string ?? "?").Reverse().Select(c => c).ToArray());
         }
     }
-
-    #endregion
+#endregion
 
     #region *** FormatDelegate Tests **
 
@@ -158,4 +214,4 @@ public void FormatDelegate_WithCulture()
     }
 
     #endregion
-}
+}
diff --git a/src/SmartFormat.Tests/ZString/ZCharArrayTests.cs b/src/SmartFormat.Tests/ZString/ZCharArrayTests.cs
@@ -70,6 +70,45 @@ public void Buffer_Write_ISpanFormattable()
 
         Assert.That(buffer.ToString(), Is.EqualTo("12.3400"));
     }
+
+    [Test]
+    public void ISpanFormattable_Exceeding_BufferLength()
+    {
+        var buffer = new ZCharArray(16);
+        var initialBufferCapacity = buffer.Capacity;
+        var data = new SpanFormattable();
+        buffer.Write(data, Span<char>.Empty);
+
+        Assert.Multiple(() =>
+        {
+            // On first attempt, the data will not fit into the buffer
+            Assert.That(data.TrialNo, Is.GreaterThan(1));
+            Assert.That(buffer.Capacity, Is.GreaterThan(initialBufferCapacity));
+        });
+    }
+
+    internal record SpanFormattable : ISpanFormattable
+    {
+        internal int TrialNo;
+
+        public string ToString(string? format, IFormatProvider? formatProvider)
+        {
+            return nameof(SpanFormattable);
+        }
+
+        public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
+        {
+            if (++TrialNo == 1)
+            {
+                charsWritten = 0;
+                return false;
+            }
+
+            destination.Fill('#');
+            charsWritten = destination.Length;
+            return true;
+        }
+    }
 #endif
 
     [Test]
@@ -96,7 +135,7 @@ public void Buffer_Reset_Size_To_Zero()
             Assert.That(buffer.Length, Is.EqualTo(0));
         });
     }
-
+    
     [Test]
     public void Buffer_Thread_Safety()
     {
diff --git a/src/SmartFormat/Extensions/DefaultFormatter.cs b/src/SmartFormat/Extensions/DefaultFormatter.cs
@@ -7,16 +7,37 @@
 
 namespace SmartFormat.Extensions;
 
+#if NET6_0_OR_GREATER
 /// <summary>
-/// Do the default formatting, same logic as "String.Format".
+/// Does the default formatting.
+/// This formatter in always required, unless you implement your own.
+/// <pre/>
+/// It supports <see cref="ISpanFormattable"/>, <see cref="IFormattable"/>, and <see cref="ICustomFormatter"/>.
 /// </summary>
+#else
+/// <summary>
+/// Does the default formatting.
+/// This formatter in always required, unless you implement your own.
+/// <pre/>
+/// It supports <see cref="IFormattable"/> and <see cref="ICustomFormatter"/>.
+/// </summary>
+#endif
 public class DefaultFormatter : IFormatter
 {
+
+#if NET6_0_OR_GREATER
+    /// <summary>
+    /// The maximum size of the stack-allocated buffer
+    /// for formatting <see cref="System.ISpanFormattable"/> objects.
+    /// </summary>
+    internal const int StackAllocCharBufferSize = 512;
+#endif
+    
     /// <summary>
     /// Obsolete. <see cref="IFormatter"/>s only have one unique name.
     /// </summary>
     [Obsolete("Use property \"Name\" instead", true)]
-    public string[] Names { get; set; } = {"default", "d", string.Empty};
+    public string[] Names { get; set; } = { "default", "d", string.Empty };
 
     ///<inheritdoc/>
     public string Name { get; set; } = "d";
@@ -42,37 +63,57 @@ public bool TryEvaluateFormat(IFormattingInfo formattingInfo)
             return true;
         }
 
-        // Use the provider to see if a CustomFormatter is available:
-        var provider = formattingInfo.FormatDetails.Provider;
+        /* 
+         * The order of precedence is:
+         * 1. ICustomFormatter from the IFormatProvider
+         * 2. ISpanFormattable (for .NET 6.0 or later)
+         * 3. IFormattable
+         * 4. ToString
+         */
 
-        //  We will try using IFormatProvider, IFormattable, and if all else fails, ToString.
-        string? result; 
+        var provider = formattingInfo.FormatDetails.Provider;
         if (provider?.GetFormat(typeof(ICustomFormatter)) is ICustomFormatter cFormatter)
         {
             var formatText = format?.GetLiteralText();
-            result = cFormatter.Format(formatText, current, provider);
-        }
-        // IFormattable
-        // Note: This is what ValueStringBuilder is implementing in the same way
-        else if (current is IFormattable formattable)
-        {
-            var formatText = format?.ToString();
-            result = formattable.ToString(formatText, provider);
+            formattingInfo.Write(cFormatter.Format(formatText, current, provider).AsSpan());
+            return true;
         }
-        else if (current is string str)
+
+#if NET6_0_OR_GREATER
+        if (current is ISpanFormattable spanFormattable)
         {
-            formattingInfo.Write(str.AsSpan());
+            // ISpanFormattable has the same speed as IFormattable,
+            // but brings less GC pressure (e.g. 25% less for processing 1234567.890123f).
+
+            var fmtTextSpan = format != null ? format.AsSpan() : Span<char>.Empty;
+
+            // Try to use the stack buffer first
+            Span<char> buffer = stackalloc char[StackAllocCharBufferSize];
+
+            if (spanFormattable.TryFormat(buffer, out var written, fmtTextSpan, provider))
+            {
+                formattingInfo.Write(buffer.Slice(0, written));
+                return true;
+            }
+
+            // If the stack buffer is too small, use a heap buffer
+            using var arrayBuffer = new ZString.ZCharArray(2_000_000);
+            arrayBuffer.Write(spanFormattable, fmtTextSpan, provider);
+            formattingInfo.Write(arrayBuffer.GetSpan());
             return true;
         }
-        // ToString:
-        else
+#endif
+
+        if (current is IFormattable formattable)
         {
-            result = current?.ToString();
+            var fmtTextString = format?.ToString();
+            formattingInfo.Write(formattable.ToString(fmtTextString, provider).AsSpan());
+            return true;
         }
 
-        // Output the result:
-        formattingInfo.Write(result != null ? result.AsSpan() : ReadOnlySpan<char>.Empty);
-
+        // Fallback to ToString (string.ToString() returns 'this')
+        var result = current != null ? current.ToString().AsSpan() : Span<char>.Empty;
+        formattingInfo.Write(result);
         return true;
     }
 }
diff --git a/src/SmartFormat/ZString/ZCharArray.cs b/src/SmartFormat/ZString/ZCharArray.cs
@@ -33,11 +33,6 @@ private static readonly ArrayPool<char>
     /// </summary>
     public const int MaxBufferCapacity = 10_000_000;
 
-    /// <summary>
-    /// The maximum size of the stack-allocated buffer.
-    /// </summary>
-    public const int StackAllocCharBufferSizeLimit = 256;
-
     /// <summary>
     /// Creates a new <see cref="ZCharArray"/> with a length of <see cref="DefaultBufferCapacity"/>>.
     /// </summary>
@@ -205,22 +200,22 @@ public void Write(char c, int count)
     /// <param name="data"></param>
     /// <param name="format"></param>
     /// <param name="provider"></param>
-    /// <exception cref="FormatException"></exception>
     /// <exception cref="ObjectDisposedException"></exception>
-    public void Write(ISpanFormattable data, ReadOnlySpan<char> format, IFormatProvider provider)
+    public void Write(ISpanFormattable data, ReadOnlySpan<char> format, IFormatProvider? provider = null)
     {
         ThrowIfDisposed();
 
-        Span<char> stackBuffer = stackalloc char[StackAllocCharBufferSizeLimit];
-        if (data.TryFormat(stackBuffer, out var written, format, provider))
+        // Increases the buffer size until it's big enough
+        while (true)
         {
-            GrowBufferIfNeeded(written);
-            stackBuffer.Slice(0, written).CopyTo(_bufferArray!.AsSpan(_currentLength));
-            _currentLength += written;
-            return;
-        }
+            if (data.TryFormat(_bufferArray.AsSpan(_currentLength), out var written, format, provider))
+            {
+                _currentLength += written;
+                return;
+            }
 
-        throw new FormatException("The data could not be formatted.");
+            GrowBufferIfNeeded(1_000);
+        }
     }
 #endif
 
@@ -231,9 +226,8 @@ public void Write(ISpanFormattable data, ReadOnlySpan<char> format, IFormatProvi
     /// <param name="data"></param>
     /// <param name="format"></param>
     /// <param name="provider"></param>
-    /// <exception cref="FormatException"></exception>
     /// <exception cref="ObjectDisposedException"></exception>
-    public void Write(IFormattable data, string format, IFormatProvider provider)
+    public void Write(IFormattable data, string format, IFormatProvider? provider = null)
     {
         ThrowIfDisposed();
         var formatted = data.ToString(format, provider).AsSpan();
