API Proposal: String.{Try}CopyTo(Span<char>)

[stephentoub]

Background and Motivation

When working with text (strings and spans), it's relatively common to need to copy a string to a span, which can be done with:

string.AsSpan().CopyTo(destination)

We can make this simpler and faster by adding such a CopyTo directly to string:

string.CopyTo(destination)

Same with TryCopyTo. For example, Number.Formatting.cs in corelib has this:

runtime/src/libraries/System.Private.CoreLib/src/System/Number.Formatting.cs

Lines 757 to 769 in f0f3b84

	private static bool TryCopyTo(string source, Span<char> destination, out int charsWritten)
	{
	Debug.Assert(source != null);
	if (source.AsSpan().TryCopyTo(destination))
	{
	charsWritten = source.Length;
	return true;
	}
	charsWritten = 0;
	return false;
	}

by changing the source.AsSpan().TryCopyTo(destination) there to source.TryCopyTo(destination) (with an implementation of TryCopyTo on string that's the same 7-line implementation on span), we get this diff:

Proposed API

namespace System
{
    public sealed class String
    {
        ...
        public void CopyTo(int sourceIndex, char[] destination, int destinationIndex, int count);
+       public void CopyTo(Span<char> destination);
+       public bool TryCopyTo(Span<char> destination);
    }
}

Risks

string.AsSpan().{Try}CopyTo works with null input strings, because AsSpan() special-cases null to return an empty span. As a result, someone switching from the former to these new APIs could incur a null reference exception if they used a null string.

[GrabYourPitchforks]

I think this category of API is generally useful. When I was experimenting with Utf8String I had an internal AsSpanSkipNullCheck method hanging off the type.

runtime/src/libraries/System.Private.CoreLib/src/System/Utf8String.cs

Lines 72 to 80 in 066a24c

	/// <summary>
	/// Similar to <see cref="Utf8Extensions.AsSpan(Utf8String)"/>, but skips the null check on the input.
	/// Throws a <see cref="NullReferenceException"/> if the input is null.
	/// </summary>
	[MethodImpl(MethodImplOptions.AggressiveInlining)]
	internal Utf8Span AsSpanSkipNullCheck()
	{
	return Utf8Span.UnsafeCreateWithoutValidation(this.AsBytesSkipNullCheck());
	}

The general idea is that it was for scenarios where I really didn't expect the string instance to be null, and I was willing to take the NRE in order to avoid complicated branching in my hot paths.

[bartonjs]

Video

• While our newer Span-writing methods return the number of elements written (when there's not a better purpose for the return value) this has symmetry with the current Span methods.

namespace System
{
    public sealed class String
    {
        ...
        public void CopyTo(int sourceIndex, char[] destination, int destinationIndex, int count);
+       public void CopyTo(Span<char> destination);
+       public bool TryCopyTo(Span<char> destination);
    }
}