Table of Contents

Utf8TomlWriter Struct

Definition

Namespace
Bodu.Text.Toml.Writer
Assembly
Bodu.Text.Toml.dll
Package
Bodu.Text.Toml 1.0.0
Source
Utf8TomlWriter.Streaming.cs

Provides an append-only writer that emits normalized TOML bytes to an IBufferWriter<T>. Because TOML's surface layout is a whole-document property, the writer is not progressive: it buffers every value into an in-memory tree and serializes it when the root table is closed.

public ref struct Utf8TomlWriter
Inherited Members

Examples

var buffer = new ArrayBufferWriter<byte>();
var writer = new Utf8TomlWriter(buffer);

writer.WriteStartTable();             // the required root table
writer.WritePropertyName("name");
writer.WriteString("app");
writer.WritePropertyName("port");
writer.WriteInteger(8080);

writer.WritePropertyName("server");
writer.WriteStartTable();             // nested table, emitted as a [server] block
writer.WritePropertyName("host");
writer.WriteString("localhost");
writer.WriteEndTable();

writer.WriteEndTable();               // closing the root table emits the document
// buffer.WrittenSpan now holds the UTF-8 TOML bytes.

Remarks

The writer is a ref struct whose mutable state lives in shared managed objects - a stack of open containers and the buffered value tree - so a copy taken by value continues to write to the same output. Whether a table becomes a [header] block or an inline { … } depends on where it sits in the finished document, and arrays are inline, so the layout cannot be decided incrementally: the forward Write* calls only build the tree.

Normalized emission happens once, when the outermost table is closed by the root WriteEndTable(). A table's scalar and array members are written first as key = value lines, then its sub-tables as [dotted.path] block headers (depth-first, in document order); an array whose every element is a table is emitted as a run of [[path]] blocks. Arrays of non-table values are inline ([1, 2, 3]), and a table that appears as an array element is an inline table ({ a = 1, b = 2 }). Keys are bare when they match the bare-key grammar and basic-quoted otherwise; strings are basic-quoted with escaping; floats render inf, -inf, and nan and otherwise use their shortest round-trippable spelling; date-times use the RFC 3339 form matching their kind.

Constructors

Utf8TomlWriter(IBufferWriter<byte>)

Initializes a new instance of the Utf8TomlWriter struct.

public Utf8TomlWriter(IBufferWriter<byte> output)

Parameters

output IBufferWriter<byte>

The destination buffer writer.

Exceptions

ArgumentNullException

Thrown when output is null.

Utf8TomlWriter(IBufferWriter<byte>, TomlWriterOptions)

Initializes a new instance of the Utf8TomlWriter struct using the supplied options.

public Utf8TomlWriter(IBufferWriter<byte> output, TomlWriterOptions options)

Parameters

output IBufferWriter<byte>

The destination buffer writer.

options TomlWriterOptions

The writer options controlling the specification version and maximum nesting depth.

Remarks

A MaxDepth of zero or less selects the default maximum depth of 64, and a larger value is clamped to Bodu.Text.Toml.TomlLimits.AbsoluteMaxDepth so that an unbounded configured value cannot drive the writer into a StackOverflowException. Opening a container past that depth - a table or array nested deeper than the effective limit - throws TomlSerializationException.

Exceptions

ArgumentNullException

Thrown when output is null.

Utf8TomlWriter(Stream)

Initializes a new instance of the Utf8TomlWriter struct that writes the finished document to a stream.

public Utf8TomlWriter(Stream utf8Toml)

Parameters

utf8Toml Stream

The writable destination stream.

Exceptions

ArgumentNullException

Thrown when utf8Toml is null.

ArgumentException

Thrown when utf8Toml does not support writing.

Utf8TomlWriter(Stream, TomlWriterOptions)

Initializes a new instance of the Utf8TomlWriter struct that writes the finished document to a stream, using the supplied options.

public Utf8TomlWriter(Stream utf8Toml, TomlWriterOptions options)

Parameters

utf8Toml Stream

The writable destination stream.

options TomlWriterOptions

The writer options controlling the maximum nesting depth.

Remarks

Rendered bytes are buffered when the root table is closed and reach the stream when Flush() or Dispose() is called; BytesPending reports the buffered count.

Exceptions

ArgumentNullException

Thrown when utf8Toml is null.

ArgumentException

Thrown when utf8Toml does not support writing.

Properties

BytesCommitted

Gets the number of bytes committed to the destination so far.

public readonly long BytesCommitted { get; }

Property Value

long

For a buffer-writer destination, the bytes delivered when the root table was closed; for a stream destination, the bytes written to the stream by Flush().

BytesPending

Gets the number of rendered bytes buffered for a stream destination and not yet flushed.

public readonly long BytesPending { get; }

Property Value

long

The pending byte count. Always zero for a buffer-writer destination, where bytes are delivered as the root table closes; for a stream destination the count becomes non-zero when the document completes and returns to zero on Flush().

Methods

Dispose()

Flushes any buffered output to the destination stream.

public readonly void Dispose()

Remarks

The writer holds no unmanaged resources and does not own the destination, so disposal only flushes; it may be called multiple times. The method enables the using pattern over the ref struct.

Flush()

Writes any buffered output to the destination stream and flushes it.

public readonly void Flush()

Remarks

For a buffer-writer destination the method is a no-op: rendered bytes are delivered to the IBufferWriter<T> when the root table is closed.

Reset()

Resets the writer so a new document can be written to the same destination.

public readonly void Reset()

Remarks

Open containers, the buffered value tree, any unflushed stream output, and the BytesCommitted / BytesPending counts are all cleared.

WriteBoolean(bool)

Writes a Boolean value.

public readonly void WriteBoolean(bool value)

Parameters

value bool

The Boolean value.

WriteBoolean(string, bool)

Writes a property name and Boolean value as a pair.

public readonly void WriteBoolean(string name, bool value)

Parameters

name string

The key text.

value bool

The Boolean value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteEndArray()

Writes the end of the current array.

public readonly void WriteEndArray()

Exceptions

InvalidOperationException

Thrown when no container is open or the innermost open container is not an array.

WriteEndTable()

Writes the end of the current table.

public readonly void WriteEndTable()

Remarks

Closing the outermost table serializes the buffered value tree to normalized TOML and writes the resulting UTF-8 bytes to the destination buffer writer.

Exceptions

InvalidOperationException

Thrown when no container is open, the innermost open container is not a table, or the table has a pending property name without a value.

WriteFloat(double)

Writes an IEEE 754 binary64 floating-point value.

public readonly void WriteFloat(double value)

Parameters

value double

The floating-point value.

WriteFloat(string, double)

Writes a property name and IEEE 754 binary64 floating-point value as a pair.

public readonly void WriteFloat(string name, double value)

Parameters

name string

The key text.

value double

The floating-point value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteInteger(long)

Writes a 64-bit signed integer value.

public readonly void WriteInteger(long value)

Parameters

value long

The integer value.

WriteInteger(string, long)

Writes a property name and 64-bit signed integer value as a pair.

public readonly void WriteInteger(string name, long value)

Parameters

name string

The key text.

value long

The integer value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteLocalDate(DateOnly)

Writes a local date value in RFC 3339 form.

public readonly void WriteLocalDate(DateOnly value)

Parameters

value DateOnly

The local date value.

WriteLocalDate(string, DateOnly)

Writes a property name and local date value as a pair.

public readonly void WriteLocalDate(string name, DateOnly value)

Parameters

name string

The key text.

value DateOnly

The local date value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteLocalDateTime(DateTime)

Writes a local date-time value in RFC 3339 form, without any offset.

public readonly void WriteLocalDateTime(DateTime value)

Parameters

value DateTime

The local date-time value.

WriteLocalDateTime(string, DateTime)

Writes a property name and local date-time value as a pair.

public readonly void WriteLocalDateTime(string name, DateTime value)

Parameters

name string

The key text.

value DateTime

The local date-time value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteLocalTime(string, TimeOnly)

Writes a property name and local time value as a pair.

public readonly void WriteLocalTime(string name, TimeOnly value)

Parameters

name string

The key text.

value TimeOnly

The local time value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteLocalTime(TimeOnly)

Writes a local time value in RFC 3339 form.

public readonly void WriteLocalTime(TimeOnly value)

Parameters

value TimeOnly

The local time value.

WriteOffsetDateTime(DateTimeOffset)

Writes an offset date-time value in RFC 3339 form.

public readonly void WriteOffsetDateTime(DateTimeOffset value)

Parameters

value DateTimeOffset

The offset date-time value.

WriteOffsetDateTime(string, DateTimeOffset)

Writes a property name and offset date-time value as a pair.

public readonly void WriteOffsetDateTime(string name, DateTimeOffset value)

Parameters

name string

The key text.

value DateTimeOffset

The offset date-time value.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WritePropertyName(ReadOnlySpan<byte>)

Writes the name of the table key whose value follows from UTF-8 text.

public readonly void WritePropertyName(ReadOnlySpan<byte> utf8Name)

Parameters

utf8Name ReadOnlySpan<byte>

The UTF-8 key text.

Exceptions

ArgumentException

Thrown when utf8Name is not valid UTF-8.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or the key has already been written to the current table.

WritePropertyName(ReadOnlySpan<char>)

Writes the name of the table key whose value follows.

public readonly void WritePropertyName(ReadOnlySpan<char> name)

Parameters

name ReadOnlySpan<char>

The key text.

Exceptions

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WritePropertyName(string)

Writes the name of the table key whose value follows.

public readonly void WritePropertyName(string name)

Parameters

name string

The key text.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteStartArray()

Writes the start of an array.

public readonly void WriteStartArray()

Exceptions

TomlSerializationException

Thrown when opening the array would exceed the effective maximum nesting depth.

InvalidOperationException

Thrown when the document is already complete, when the array would become the document root (the root of a TOML document must be a table), or when the enclosing container is a table with no pending property name.

WriteStartArray(string)

Writes a property name and the start of its array as a pair.

public readonly void WriteStartArray(string name)

Parameters

name string

The key text.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

TomlSerializationException

Thrown when opening the array would exceed the configured maximum nesting depth.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteStartTable()

Writes the start of a table.

public readonly void WriteStartTable()

Exceptions

TomlSerializationException

Thrown when opening the table would exceed the effective maximum nesting depth.

InvalidOperationException

Thrown when the document is already complete, or when the enclosing container is a table with no pending property name.

WriteStartTable(string)

Writes a property name and the start of its table as a pair.

public readonly void WriteStartTable(string name)

Parameters

name string

The key text.

Exceptions

ArgumentNullException

Thrown when name is null.

ArgumentException

Thrown when name contains an unpaired surrogate.

TomlSerializationException

Thrown when opening the table would exceed the configured maximum nesting depth.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

WriteString(ReadOnlySpan<byte>)

Writes a string value from UTF-8 text.

public readonly void WriteString(ReadOnlySpan<byte> utf8Value)

Parameters

utf8Value ReadOnlySpan<byte>

The UTF-8 string value.

Exceptions

ArgumentException

Thrown when utf8Value is not valid UTF-8.

InvalidOperationException

Thrown when the document is already complete or the enclosing table has no pending property name.

WriteString(ReadOnlySpan<char>)

Writes a string value.

public readonly void WriteString(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The string value.

Exceptions

ArgumentException

Thrown when value contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete or the enclosing table has no pending property name.

WriteString(string)

Writes a string value.

public readonly void WriteString(string value)

Parameters

value string

The string value.

Exceptions

ArgumentNullException

Thrown when value is null.

ArgumentException

Thrown when value contains an unpaired surrogate.

WriteString(string, string)

Writes a property name and string value as a pair.

public readonly void WriteString(string name, string value)

Parameters

name string

The key text.

value string

The string value.

Exceptions

ArgumentNullException

Thrown when name or value is null.

ArgumentException

Thrown when name or value contains an unpaired surrogate.

InvalidOperationException

Thrown when the document is already complete, the innermost open container is not a table, another property name is already pending, or name has already been written to the current table.

Applies to

ProductVersions
.NET8, 10