API proposal: Add File class method overloads for ReadOnlyMemory and ReadOnlySpan

[Tan90909090]

Related to #30305.

Motivation

Currently, File APIs for writing a file only accept byte[] and string.
For instance, File.WriteAllBytesAsync only accepts byte[]. When I want to write a ReadOnlyMemory<byte> to file, I have two choises.

1. Call ReadOnlyMemory<byte>.ToArray() then call File.WriteAllBytesAsync(string, byte[], CancellationToken). But this allocates extra memory.
2. Create a FileStream instance with an appropriate FileOptions and call FileStream.WriteAsync(ReadOnlyMemory<byte>, CancellationToken). But this choise is verbose.

It is convenient to be able to pass ReadOnlyMemory<byte> to File.WriteAllBytesAsync() directly.

Proposal

namespace System.IO
{
    public static class File
    {
        // it seems like path might be better as ReadOnlyMemory<char>/ReadOnlySpan<char>
        // in these methods, but FileStream doesn't currently support that.
        public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
        public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void AppendAllText(string path, ReadOnlySpan<char> contents);
        public static void AppendAllText(string path, ReadOnlySpan<char> contents, Encoding encoding);
        public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
        public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void WriteAllText(string path, ReadOnlySpan<char> contents);
        public static void WriteAllText(string path, ReadOnlySpan<char> contents, Encoding encoding);
        public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void WriteAllBytes(string path, ReadOnlySpan<byte> bytes);
        public static ValueTask WriteAllBytesAsync(string path, ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken = default);
    }
}

[ghost]

Tagging subscribers to this area: @carlossanlop, @jozkee
Notify danmosemsft if you want to be subscribed.

[carlossanlop]

Thanks for the contribution, @Tan90909090.

I noticed that in the source code for File.WriteAllBytesAsync, we create a FileStream and call WriteAsync, converting the byte[] to a ReadOnlyMemory<byte>. So I see the value of having the proposed API.

[GrabYourPitchforks]

@carlossanlop Should we mark this as ready for review? Seems like it's actionable by the API reviewers.

[Tan90909090]

Oh! I forget File APIs targeting string!
In the source, File.AppendAllTextAsync and File.WriteAllTextAsync call InternalWriteAllTextAsync, which a create StreamWriter and call WriteAsync, converting the string to a ReadOnlyMemory<char>.
Currently File.AppendAllLinesAsync and File.WriteAllLinesAsync don't use ReadOnlyMemory<char> but I think they are also able to use ReadOnlyMemory<char>.
More proposal:

namespace System.IO
{
    public static class File
    {
+       public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
+       public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
+       public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
+       public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
+       public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
+       public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
+       public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
+       public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
    }
}

Question: Should I merge a description and change the issue title, or open another issue about APIs for ReadOnlyMemory<char>?

[carlossanlop]

Good catch, @Tan90909090. I updated your main issue description with all the APIs from your last comment.
I'm also marking this as ready for review, @GrabYourPitchforks.

[Tan90909090]

It seemed that a public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default) is missing so I added this.
Thank you for your quick action.

[Tan90909090]

I also forgot about synchronous APIs... I updated this issue description for consistency.
Since there are FileStream.Write(ReadOnlySpan<Byte>) and StreamWriter.Write(ReadOnlySpan<Char>), the File class should be able to implement these methods.
Note: IEnumerable<ReadOnlySpan<T>> is prohibited so I omited AppendAllLines and WriteAllLines overloads.

[jkotas]

There is not much benefit in returning ValueTask from these APIs. They should be able to use Task just fine.

[GrabYourPitchforks]

@carlossanlop Do you suppose any of our existing internal call sites would be able to use the new proposed overloads? I [very briefly] looked through source.dot.net and didn't immediately see any good candidates.

[terrajobst]

Video

• It seems odd to combine a low-level concept like span/memory with very high-level APIs like "write all this data to file".
• The goal is to make it very convenient to write some data to a file, not performance.
• My concern is that these additions would "pollute" a core API that is frequently used by beginners. The API is designed to grow to expose users to more concepts, such as StreamReader and FileStream.
• If the arugment is that creating a file stream is too hard, for example, opening it for async, I'd rather we add dedicated methods for that, such as OpenForAsync.
• Unless there is a compelling reason for those APIs, we're inclined to say no.

namespace System.IO
{
    public static class File
    {
        public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
        public static ValueTask AppendAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void AppendAllText(string path, ReadOnlySpan<char> contents);
        public static void AppendAllText(string path, ReadOnlySpan<char> contents, Encoding encoding);
        public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
        public static ValueTask AppendAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllLinesAsync(string path, IEnumerable<ReadOnlyMemory<char>> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void WriteAllText(string path, ReadOnlySpan<char> contents);
        public static void WriteAllText(string path, ReadOnlySpan<char> contents, Encoding encoding);
        public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, CancellationToken cancellationToken = default);
        public static ValueTask WriteAllTextAsync(string path, ReadOnlyMemory<char> contents, Encoding encoding, CancellationToken cancellationToken = default);
        public static void WriteAllBytes(string path, ReadOnlySpan<byte> bytes);
        public static ValueTask WriteAllBytesAsync(string path, ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken = default);
    }
}