[API Proposal]: `TryCopyTo(destination, out int elementsWritten)`

[MihaZupan]

Background and motivation

With more and more methods having the signature of bool TryFoo(..., out int charsWritten), you run into situations where you're copying things from a span, but then have to manually deal with the out parameter.
Having overloads that out the number of elements written can help avoid the boilerplate.

API Proposal

namespace System;

public sealed class String
{
    public bool TryCopyTo(Span<char> destination);
+   public bool TryCopyTo(Span<char> destination, out int charsWritten);
}

public readonly struct ReadOnlySpan<T>
{
    public bool TryCopyTo(Span<T> destination);
+   public bool TryCopyTo(Span<T> destination, out int elementsWritten);
}

public readonly struct Span<T>
{
    public bool TryCopyTo(Span<T> destination);
+   public bool TryCopyTo(Span<T> destination, out int elementsWritten);
}

API Usage

-if (result.TryCopyTo(destination))
-{
-    charsWritten = result.Length;
-    return true;
-}
-
-charsWritten = 0;
-return false;
+return result.TryCopyTo(destination, out charsWritten);

A couple examples from this repo:

runtime/src/libraries/System.Private.Uri/src/System/UriExt.cs

Lines 631 to 638 in b35e96b

	if (charsToUnescape.TryCopyTo(destination))
	{
	charsWritten = charsToUnescape.Length;
	return true;
	}
	charsWritten = 0;
	return false;

runtime/src/libraries/System.Private.Uri/src/System/Uri.cs

Lines 1630 to 1637 in b35e96b

	if (result.TryCopyTo(destination))
	{
	charsWritten = result.Length;
	return true;
	}
	charsWritten = 0;
	return false;

runtime/src/libraries/Common/src/System/Security/Cryptography/Helpers.cs

Lines 89 to 99 in b35e96b

	internal static bool TryCopyToDestination(this ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)
	{
	if (source.TryCopyTo(destination))
	{
	bytesWritten = source.Length;
	return true;
	}
	bytesWritten = 0;
	return false;
	}

runtime/src/libraries/System.Private.CoreLib/src/System/Globalization/Normalization.cs

Lines 51 to 58 in b35e96b

	if (source.TryCopyTo(destination))
	{
	charsWritten = source.Length;
	return true;
	}
	charsWritten = 0;
	return false;

runtime/src/libraries/System.Private.CoreLib/src/System/Collections/Generic/ValueListBuilder.cs

Lines 149 to 159 in b35e96b

	public bool TryCopyTo(Span<T> destination, out int itemsWritten)
	{
	if (_span.Slice(0, _pos).TryCopyTo(destination))
	{
	itemsWritten = _pos;
	return true;
	}
	itemsWritten = 0;
	return false;
	}

Alternative Designs

• More types?
• elementsWritten vs itemsWritten?

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-memory
See info in area-owners.md if you want to be subscribed.

[NinoFloris]

One downside is that it might give users the idea a buffer saturating copy is done for these overloads. Instead it's just the normal binary outcome of TryCopyTo, either everything was copied or nothing was. I'm not sure that creating this potential for confusion is worth it on the api surface. They also seem like easy extension methods to define internally.

[MihaZupan]

As far as I'm aware, none of the Try* APIs in the base libraries that only return an out int written support partial operations.
Those that do also return the number of consumed elements, or use the OperationStatus pattern.

I agree that Copy- is a bit special because it's obvious that elementsRead == elementsWritten, though I think that a method with the alternative behavior you described would/should be called something along the lines of Read or Consume instead.

They also seem like easy extension methods to define internally.

They are simple, but it's unfortunate if they're something that many projects would have to implement.
For example when looking through runtime, I see usages in these: MihaZupan@bf0d67a.

[jeffhandley]

Assigned to @krwq for triage.

[krwq]

@MihaZupan after looking at your example I see this as useful utility but without reading anything I thought the bool flag was to tell if it copied partial or entire input so I 100% agree with @NinoFloris on this. If we're going to consider this it needs better name for what it does so it is not confusing but the fact I cannot come up with any name is usually a first sign for me that there is something wrong with the abstraction. Perhaps there is some better way to solve this than creating this API (i.e. syntax sugar or something to make this easier but I can't come up with anything at the moment).

Since this is not necessarily needed for .NET 10 I'll mark it as Future for now but I do agree that lack of it adds lots of boilerplate in the code so I'll leave it open so we can keep discussing possible approach to address the boilerplate.

[MihaZupan]

Looks like more people share Nino's concerns about overloading TryCopyTo being potentially misleading.

Just throwing a random idea out there - how would TryCopyAll/TryCopyAllTo sound as an alternative?

[tannergooding]

I think that'd be generally "worse" due to having two method groups that do the same thing.

Anyone can define such an extension method if they want already and otherwise this isn't overly complex:

amountWritten = TryCopyTo(destination) ? source.Length : 0;