Struct JsonWriter

Namespace

Nerdbank.Json

Assembly

Nerdbank.Json.dll

Writes JSON values to a UTF-8 buffer.

public ref struct JsonWriter

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

This type is allocation-conscious and writes UTF-8 directly to an IBufferWriter<T>.

Constructors

JsonWriter(IBufferWriter<byte>)

Initializes a new instance of the JsonWriter struct.

public JsonWriter(IBufferWriter<byte> writer)

Parameters

writer IBufferWriter<byte>

The destination for UTF-8 JSON bytes.

Properties

UnflushedBytes

Gets the number of bytes that have been written but not yet committed flushed to the underlying IBufferWriter<T>.

public readonly int UnflushedBytes { get; }

Property Value

int

WriteIndented

Gets a value indicating whether line breaks and indentation should be written.

public bool WriteIndented { readonly get; init; }

Property Value

bool

Methods

Advance(int)

Commits one complete, trusted UTF-8 JSON value written into the latest GetSpan(int) reservation.

public void Advance(int length)

Parameters

length int

The number of payload bytes written, or zero to cancel the reservation without writing a value.

Remarks

A positive advance consumes the reservation and applies the same enclosing indentation and value bookkeeping as WriteRaw(ReadOnlySpan<byte>). Payload contents are not validated, escaped, or reindented. Callers still write enclosing separators explicitly. A zero advance is also allowed without a reservation. Invalid advances leave the reservation, byte counters, and container state unchanged.

Exceptions

ArgumentOutOfRangeException

length is negative or exceeds the reserved span.

InvalidOperationException

A positive advance has no active reservation.

Clone(IBufferWriter<byte>)

Creates a writer for a new destination using this writer's formatting options.

public readonly JsonWriter Clone(IBufferWriter<byte> writer)

Parameters

writer IBufferWriter<byte>

The new destination.

Returns

JsonWriter

An independent writer with no inherited container or pending-property state.

Flush()

Ensures everything previously written has been flushed to the underlying IBufferWriter<T>.

public void Flush()

GetSpan(int)

Reserves contiguous space for one complete, trusted UTF-8 JSON value.

public Span<byte> GetSpan(int length)

Parameters

length int

The minimum number of payload bytes required. Zero requests a nonempty span.

Returns

Span<byte>

A borrowed span of at least length bytes, excluding any enclosing indentation.

Remarks

Fill the span and call Advance(int) once with the complete value's byte length. As with WriteRaw(ReadOnlySpan<byte>), syntax is not validated: fragments, property names, separators, empty values, and multiple values are not supported. Reservation does not consume a value or change container state, but may flush previously written bytes. Each successful call replaces the previous reservation; unadvanced contents need not be preserved. The span expires on another reservation, any write, Advance(int), Flush(), or returning this writer to JsonAsyncWriter. Do not copy a writer to share its reservation.

Exceptions

ArgumentOutOfRangeException

length is negative or too large for a contiguous reservation including indentation.

Write(RawJson)

Writes one raw JSON value after validating its syntax and the default depth limit.

public void Write(RawJson value)

Parameters

value RawJson

The raw JSON value. An empty or default payload is invalid.

Remarks

Preserves the exact UTF-8 bytes. Raw values must use strict JSON without comments or trailing commas.

Write(bool)

Writes a JSON boolean literal.

public void Write(bool value)

Parameters

value bool

The value to write.

Write(byte)

Writes a JSON number value.

public void Write(byte value)

Parameters

value byte

The value to write.

Write(decimal)

Writes a JSON number value.

public void Write(decimal value)

Parameters

value decimal

The value to write.

Write(double)

Writes a JSON number value.

public void Write(double value)

Parameters

value double

The value to write.

Write(short)

Writes a JSON number value.

public void Write(short value)

Parameters

value short

The value to write.

Write(int)

Writes a JSON number value.

public void Write(int value)

Parameters

value int

The value to write.

Write(long)

Writes a JSON number value.

public void Write(long value)

Parameters

value long

The value to write.

Write(ReadOnlySpan<char>)

Writes a JSON string value.

public void Write(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The value to write.

Write(sbyte)

Writes a JSON number value.

public void Write(sbyte value)

Parameters

value sbyte

The value to write.

Write(float)

Writes a JSON number value.

public void Write(float value)

Parameters

value float

The value to write.

Write(string?)

Writes a JSON string value.

public void Write(string? value)

Parameters

value string

The value to write.

Write(ushort)

Writes a JSON number value.

public void Write(ushort value)

Parameters

value ushort

The value to write.

Write(uint)

Writes a JSON number value.

public void Write(uint value)

Parameters

value uint

The value to write.

Write(ulong)

Writes a JSON number value.

public void Write(ulong value)

Parameters

value ulong

The value to write.

WriteBase64StringValue(byte[]?)

Writes a JSON Base64 string value.

public void WriteBase64StringValue(byte[]? value)

Parameters

value byte[]

The value to write.

WriteBase64StringValue(ReadOnlySpan<byte>)

Writes a JSON Base64 string value.

public void WriteBase64StringValue(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The value to write.

WriteEndArray()

Writes the end of a JSON array.

public void WriteEndArray()

WriteEndObject()

Writes the end of a JSON object.

public void WriteEndObject()

WriteNull()

Writes the JSON null literal.

public void WriteNull()

WritePropertyName(string)

Writes a JSON property name and name separator.

public void WritePropertyName(string name)

Parameters

name string

The property name to write.

WriteRaw(scoped in ReadOnlySequence<byte>)

Writes a raw, possibly segmented UTF-8 JSON value without validating or escaping it.

public void WriteRaw(scoped in ReadOnlySequence<byte> value)

Parameters

value ReadOnlySequence<byte>

The UTF-8 JSON to write.

WriteRaw(ReadOnlySpan<byte>)

Writes raw UTF-8 JSON without validating or escaping it.

public void WriteRaw(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The UTF-8 JSON to write.

WriteRaw(string)

Writes a raw JSON token.

public void WriteRaw(string value)

Parameters

value string

The raw JSON text to write.

WriteStartArray()

Writes the start of a JSON array.

public void WriteStartArray()

WriteStartObject()

Writes the start of a JSON object.

public void WriteStartObject()

WriteString(scoped in ReadOnlySequence<byte>)

Writes decoded, possibly segmented UTF-8 content as a JSON string.

public void WriteString(scoped in ReadOnlySequence<byte> value)

Parameters

value ReadOnlySequence<byte>

Decoded UTF-8 bytes. UTF-8 code points may span segments.

Remarks

Non-ASCII bytes are preserved without Unicode validation or transcoding.

WriteString(ReadOnlySpan<byte>)

Writes decoded UTF-8 content as a JSON string, escaping quotes, backslashes, and control bytes.

public void WriteString(ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

Decoded UTF-8 bytes, not an already-escaped JSON token.

Remarks

Non-ASCII bytes are preserved without Unicode validation or transcoding.

WriteValueSeparator()

Writes a JSON value separator.

public void WriteValueSeparator()