[API Proposal]: Add ReadOnlySequence overload for WriteRawValue

[BrennanConroy]

Background and motivation

When using the Utf8JsonWriter.WriteRawValue API, you can't pass multiple segments in to write a single value, you have to allocate a contiguous array and do a single call to WriteRawValue. In our use case we already have a ReadOnlySequence<byte> and want to write it as a raw json value.

But because the API only accepts string or span, we need to write the following:

if (result.RawSerializedData.IsSingleSegment)
{
    writer.WriteRawValue(result.RawSerializedData.First.Span, skipInputValidation: true);
}
else
{
    writer.WriteRawValue(result.RawSerializedData.ToArray(), skipInputValidation: true);
}

API Proposal

namespace System.Text.Json
{
    public sealed partial class Utf8JsonWriter
    {
+        public void WriteRawValue(ReadOnlySequence<byte> json, bool skipInputValidation = false);
+        public void WriteRawValue(ReadOnlySequence<char> json, bool skipInputValidation = false);
    }
}

API Usage

void MyFunc(Utf8JsonWriter writer, ReadOnlySequence<byte> sequence)
{
    writer.WriteRawValue(sequence);
}

Alternative Designs

No response

Risks

No response

[ghost]

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

Issue Details

---

Background and motivation

When using the Utf8JsonWriter.WriteRawValue API, you can't pass multiple segments in to write a single value, you have to allocate a contiguous array and do a single call to WriteRawValue. In our use case we already have a ReadOnlySequence<byte> and want to write it as a raw json value.

But because the API only accepts string or span, we need to write the following:

if (result.RawSerializedData.IsSingleSegment)
{
    writer.WriteRawValue(result.RawSerializedData.First.Span, skipInputValidation: true);
}
else
{
    writer.WriteRawValue(result.RawSerializedData.ToArray(), skipInputValidation: true);
}

API Proposal

namespace System.Text.Json
{
    public sealed partial class Utf8JsonWriter
    {
+        public void WriteRawValue(ReadOnlySequence<byte> json, bool skipInputValidation = false);
+        public void WriteRawValue([StringSyntax(StringSyntaxAttribute.Json)] ReadOnlySequence<char> json, bool skipInputValidation = false);
    }
}

API Usage

void MyFunc(Utf8JsonWriter writer, ReadOnlySequence<byte> sequence)
{
    writer.WriteRawValue(sequence);
}

Alternative Designs

No response

Risks

No response

Author:	BrennanConroy
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json
Milestone:	-

[teo-tsirpanis]

There isn't an implicit conversion from a string to a ReadOnlySequence<char> so the [StringSyntax(StringSyntaxAttribute.Json)] is not needed. And you forgot an issue title. 😅

[BrennanConroy]

And you forgot an issue title. 😅

Haha, I was too focused on filling out the API template!

[krwq]

Suggestion looks good to me as proposed, although we unlikely will have time to do it in this release, marking as 8.0.0 so it's on our radar for vNext.

[terrajobst]

Video

• We don't want to add the overload ReadOnlySequence<char> because we'd have to deal with transcoding surrogate pairs across elements in the sequence, which is quite a bit of work that nobody seems to be asking for right now.

namespace System.Text.Json;

public sealed partial class Utf8JsonWriter
{
    public void WriteRawValue(ReadOnlySequence<byte> json, bool skipInputValidation = false);
}

[lateapexearlyspeed]

Hi, I would try to add this API by this PR, could you please review?

Also, I modified parameter name from json to utf8Json because it is for byte version rather than char (string), which seems being followed by existing overloads.
Correct me, thanks !

public void WriteRawValue(ReadOnlySequence{byte} utf8Json, bool skipInputValidation = false);

[eiriktsarpalis]

Also, I modified parameter name from json to utf8Json because it is for byte version rather than char (string), which seems being followed by existing overloads.

Change sounds reasonable to me, thanks for correcting it.