add XDocument.SaveAsync (#196)

Author: SimonCropp

apiCount.include.md

@@ -1 +1 @@
-**API count: 299**
+**API count: 302**

api_list.include.md

@@ -380,6 +380,13 @@
  * `Boolean TryFormat(Span<Char>, Int32&, ReadOnlySpan<Char>, IFormatProvider)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.uint64.tryformat)
 
 
+#### Xml.Linq.XDocument
+
+ * `Task SaveAsync(Xml.XmlWriter, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-xml-xmlwriter-system-threading-cancellationtoken))
+ * `Task SaveAsync(Stream, Xml.Linq.SaveOptions, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-io-stream-system-xml-linq-saveoptions-system-threading-cancellationtoken))
+ * `Task SaveAsync(TextWriter, Xml.Linq.SaveOptions, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-io-textwriter-system-xml-linq-saveoptions-system-threading-cancellationtoken))
+
+
 ### Static helpers
 
 #### EnumPolyfill

src/Consume/Consume.cs

@@ -18,6 +18,10 @@
 using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
+using System.Xml;
+using System.Xml.Linq;
+using MemoryStream = System.IO.MemoryStream;
+
 #pragma warning disable CS4014
 
 class Consume
@@ -457,6 +461,14 @@ void GetMemberWithSameMetadataDefinitionAs(MemberInfo info)
         var result = typeof(string).GetMemberWithSameMetadataDefinitionAs(info);
     }
 
+    void XDocumentSaveAsync()
+    {
+        var document = new XDocument();
+        document.SaveAsync(new XmlTextWriter(null!), CancellationToken.None);
+        document.SaveAsync(new StringWriter(), SaveOptions.None, CancellationToken.None);
+        document.SaveAsync(new MemoryStream(), SaveOptions.None, CancellationToken.None);
+    }
+
 #if FeatureMemory
     void RandomNextBytesSpan()
     {

src/Polyfill/Polyfill_XDocument.cs

@@ -0,0 +1,83 @@
+// <auto-generated />
+#pragma warning disable
+
+#if NETFRAMEWORK || NETSTANDARD2_0
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Xml;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using System.Xml.Linq;
+using Link = System.ComponentModel.DescriptionAttribute;
+
+static partial class Polyfill
+{
+    /// <summary>
+    /// Output this <see cref="XDocument"/> to an <see cref="XmlWriter"/>.
+    /// </summary>
+    /// <param name="writer">
+    /// The <see cref="XmlWriter"/> to output the XML to.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// A cancellation token.
+    /// </param>
+    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-xml-xmlwriter-system-threading-cancellationtoken)")]
+    public static Task SaveAsync(
+        this XDocument target,
+        XmlWriter writer,
+        CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        target.Save(writer);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Output this <see cref="XDocument"/> to a <see cref="Stream"/>.
+    /// </summary>
+    /// <param name="stream">
+    /// The <see cref="Stream"/> to output the XML to.
+    /// </param>
+    /// <param name="options">
+    /// If SaveOptions.DisableFormatting is enabled the output is not indented.
+    /// If SaveOptions.OmitDuplicateNamespaces is enabled duplicate namespace declarations will be removed.
+    /// </param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-io-stream-system-xml-linq-saveoptions-system-threading-cancellationtoken)")]
+    public static Task SaveAsync(
+        this XDocument target,
+        Stream stream,
+        SaveOptions options,
+        CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        target.Save(stream, options);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Output this <see cref="XDocument"/> to a <see cref="TextWriter"/>.
+    /// </summary>
+    /// <param name="textWriter">
+    /// The <see cref="TextWriter"/> to output the XML to.
+    /// </param>
+    /// <param name="options">
+    /// If SaveOptions.DisableFormatting is enabled the output is not indented.
+    /// If SaveOptions.OmitDuplicateNamespaces is enabled duplicate namespace declarations will be removed.
+    /// </param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.xml.linq.xdocument.saveasync#system-xml-linq-xdocument-saveasync(system-io-textwriter-system-xml-linq-saveoptions-system-threading-cancellationtoken)")]
+    public static Task SaveAsync(
+        this XDocument target,
+        TextWriter textWriter,
+        SaveOptions options,
+        CancellationToken cancellationToken)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        target.Save(textWriter, options);
+        return Task.CompletedTask;
+    }
+}
+#endif

src/Tests/PolyfillTests_XDocument.cs

@@ -0,0 +1,40 @@
+using System.Xml;
+using System.Xml.Linq;
+
+partial class PolyfillTests
+{
+    [Test]
+    public async Task XDocumentSaveAsyncXmlWriter()
+    {
+        var document = GetXDocument();
+        var builder = new StringBuilder();
+        var settings = new XmlWriterSettings
+        {
+            OmitXmlDeclaration = true,
+            Indent = true,
+            Async = true
+        };
+
+        using var writer = XmlWriter.Create(builder, settings);
+        await document.SaveAsync(writer, Cancel.None);
+        await writer.FlushAsync();
+        Assert.AreEqual("<Child />", builder.ToString());
+    }
+
+    [Test]
+    public async Task XDocumentSaveAsyncStream()
+    {
+        var document = GetXDocument();
+        using var stream = new MemoryStream();
+
+        await document.SaveAsync(stream, SaveOptions.DisableFormatting, Cancel.None);
+        stream.Position = 0;
+        using var reader = new StreamReader(stream);
+        var result = await reader.ReadToEndAsync();
+
+        Assert.AreEqual("<?xml version=\"1.0\" encoding=\"utf-8\"?><Child />", result);
+    }
+
+    static XDocument GetXDocument() =>
+        new(new XElement("Child"));
+}