[API Proposal]: File.AppendAllBytes

Background and motivation

The File class has all methods for bytes which also exist for text except of appending data. Not only that it fits into the api surface by filling this gap is also saves us writing more than one line of code.

API Proposal

namespace System.IO;

public class File
{
+    public static void AppendAllBytes(string path, ReadOnlySpan<byte> data);
+    public static Task AppendAllBytesAsync(string path, ReadOnlyMemory<byte> data, CancellationToken cancellationToken = default);
     public static void AppendAllText(string path, string? contents);
     public static Task AppendAllTextAsync(string path, string? contents, CancellationToken cancellationToken = default);
}

API Usage

byte[] data = File.ReadAllBytes("C:\\1.bin");

File.AppendAllBytes("C:\\2.bin", data);

Alternative Designs

No response

Risks

No response

The data argument should be of type ReadOnlySpan<byte> instead of byte[]??

The data argument should be of type ReadOnlySpan<byte> instead of byte[]??

WriteAllBytes uses byte[] instead of span, thats why I used it here as well but yeah sure it can be a span.

Few comments from my side:

Why the API should allow for nulls? What is the point of appending nothing to a file? Creating it? If so, we have dedicated API for that.
We need an async overload too.
The mentioned APIs were introduced before Span and Memory, the new methods should accepts ReadOnlySpan and ReadOnlyMemory to accept both arrays and other types of inputs.

namespace System.IO;

public class File
{
+    public static void AppendAllBytes(string path, ReadOnlySpan<byte> data);
+    public static Task AppendAllBytesAsync(string path, ReadOnlyMemory<byte> data, CancellationToken cancellationToken = default);
}

Having said that, I am going to update the proposal and make it as ready for review.

Why the API should allow for nulls? What is the point of appending nothing to a file?

The AppendAllText allows a nullable string I only followed this choice.

runtime/src/libraries/System.Private.CoreLib/src/System/IO/File.cs

Lines 775 to 776 in 4c75b58

    
           public static void AppendAllText(string path, string? contents) 
        
               => AppendAllText(path, contents, UTF8NoBOM);

Possibly because of that:

runtime/src/libraries/System.Private.CoreLib/src/System/IO/File.cs

Lines 1211 to 1222 in 4c75b58

    
           using SafeFileHandle fileHandle = OpenHandle(path, mode, FileAccess.Write, FileShare.Read, FileOptions.None, GetPreallocationSize(mode, contents, encoding, preambleSize)); 
        
           long fileOffset = mode == FileMode.Append && fileHandle.CanSeek ? RandomAccess.GetLength(fileHandle) : 0; 
        
           if (string.IsNullOrEmpty(contents)) 
        
           { 
        
               if (preambleSize > 0 // even if the content is empty, we want to store the preamble 
        
                   && fileOffset == 0) // if we're appending to a file that already has data, don't write the preamble. 
        
               { 
        
                   RandomAccess.WriteAtOffset(fileHandle, preamble, fileOffset); 
        
               } 
        
               return; 
        
           }

Why the API should allow for nulls? What is the point of appending nothing to a file? Creating it? If so, we have dedicated API for that.

There's value in being consistent with the existing APIs here. If someone is using WriteAllText with something that ends up being null and they decide to switch to appending rather than overriding, it'd be nice if that didn't then entail having to handle the arguments differently.

The mentioned APIs were introduced before Span and Memory, the new methods should accepts ReadOnlySpan and ReadOnlyMemory to accept both arrays and other types of inputs.

Do we want ReadOnly{Span/Memory}<byte> overloads then for the existing ones? What about ReadOnlySpan<char> for the ones currently only accepting strings?

@adamsitnik

@adamsitnik @stephentoub Can I work on this API implementation?

@adamsitnik

@adamsitnik can you assign this issue to me?

@AlexRadch please excuse me, for some reason I've missed the notification. Since you still have some actionable PRs opened (example: #88009 (review)), I am going to assign @MojtabaTajik. I hope you don't mind.

@adamsitnik

@adamsitnik @stephentoub Can I work on this API implementation?

@MojtabaTajik I've assigned you, please let me know if you need some help.

@adamsitnik

Hi @adamsitnik and @MojtabaTajik,

I noticed this PR has been quiet since August 19th. If it's okay, I'd like to help out or take it on.

@adamsitnik

Hi @adamsitnik and @MojtabaTajik,

I noticed this PR has been quiet since August 19th. If it's okay, I'd like to help out or take it on.

Hey @tcortega

I was on vacation, but I hope to get it done this week.

Navigation Menu

Repository navigation

[API Proposal]: File.AppendAllBytes #84532

Background and motivation

API Proposal

API Usage

Alternative Designs

Risks

9 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	public static void AppendAllText(string path, string? contents)
	=> AppendAllText(path, contents, UTF8NoBOM);

	using SafeFileHandle fileHandle = OpenHandle(path, mode, FileAccess.Write, FileShare.Read, FileOptions.None, GetPreallocationSize(mode, contents, encoding, preambleSize));
	long fileOffset = mode == FileMode.Append && fileHandle.CanSeek ? RandomAccess.GetLength(fileHandle) : 0;

	if (string.IsNullOrEmpty(contents))
	{
	if (preambleSize > 0 // even if the content is empty, we want to store the preamble
	&& fileOffset == 0) // if we're appending to a file that already has data, don't write the preamble.
	{
	RandomAccess.WriteAtOffset(fileHandle, preamble, fileOffset);
	}
	return;
	}

[API Proposal]: File.AppendAllBytes #84532

Description

Background and motivation

API Proposal

API Usage

Alternative Designs

Risks

Activity

gfoidl commented on Apr 11, 2023

Symbai commented on Apr 11, 2023

adamsitnik commented on May 19, 2023

Symbai commented on May 19, 2023

stephentoub commented on May 19, 2023

9 remaining items

MojtabaTajik commented on Jul 31, 2023

adamsitnik commented on Jul 31, 2023

adamsitnik commented on Jul 31, 2023

tcortega commented on Sep 30, 2023

MojtabaTajik commented on Sep 30, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions