Table of Contents

Utf8YamlWriter Struct

Definition

Namespace
Bodu.Text.Yaml.Writer
Assembly
Bodu.Text.Yaml.dll
Package
Bodu.Text.Yaml 1.3.0
Source
Utf8YamlWriter.cs

Provides a forward-only writer that emits a YAML document in block style to a UTF-8 buffer, in the manner of Utf8JsonWriter.

public ref struct Utf8YamlWriter
Inherited Members

Remarks

The writer emits block mappings and sequences with configurable indentation, choosing the most compact safe scalar presentation for each value (plain when unambiguous, otherwise double-quoted). A string is written plain only when neither a YAML 1.2 nor a YAML 1.1 reader would read it as another value: a number, a boolean, null, a YAML 1.1 sexagesimal number such as 1:30, or the merge key <<. Empty mappings and sequences are emitted in the flow forms {} and [] so they round-trip as empty collections rather than null. A mapping key is written as an implicit key (key: value) unless its written form is longer than the 1024 characters an implicit key may hold, in which case it is written as an explicit key (? key), with the value indicator on the next line.

The writer is a ref struct and cannot be boxed, stored on the heap, or captured by a lambda. Its mutable state lives behind a single shared reference, so passing the writer by value hands the callee the same in-progress document rather than an independent copy.

Constructors

Utf8YamlWriter(IBufferWriter<byte>)

Initializes a new instance of the Utf8YamlWriter struct.

public Utf8YamlWriter(IBufferWriter<byte> output)

Parameters

output IBufferWriter<byte>

The buffer to which UTF-8 YAML is written.

Exceptions

ArgumentNullException

output is null.

Utf8YamlWriter(IBufferWriter<byte>, YamlWriterOptions)

Initializes a new instance of the Utf8YamlWriter struct with options.

public Utf8YamlWriter(IBufferWriter<byte> output, YamlWriterOptions options)

Parameters

output IBufferWriter<byte>

The buffer to which UTF-8 YAML is written.

options YamlWriterOptions

The writer options.

Exceptions

ArgumentNullException

output is null.

ArgumentException

The options specify an unsupported newline string.

ArgumentOutOfRangeException

The options specify an out-of-range indentation width.

Methods

WriteBoolean(bool)

Writes a boolean scalar value.

public void WriteBoolean(bool value)

Parameters

value bool

The boolean value.

Exceptions

InvalidOperationException

The document root has already been written, or the current container is a mapping with no pending key.

WriteDouble(double)

Writes a floating-point scalar value.

public void WriteDouble(double value)

Parameters

value double

The floating-point value.

Exceptions

InvalidOperationException

The document root has already been written, or the current container is a mapping with no pending key.

WriteEndMapping()

Ends the current block mapping.

public void WriteEndMapping()

Exceptions

InvalidOperationException

There is no open container, the innermost open container is a sequence, or a key is awaiting its value.

WriteEndSequence()

Ends the current block sequence.

public void WriteEndSequence()

Exceptions

InvalidOperationException

There is no open container, or the innermost open container is a mapping.

WriteInteger(long)

Writes an integer scalar value.

public void WriteInteger(long value)

Parameters

value long

The integer value.

Exceptions

InvalidOperationException

The document root has already been written, or the current container is a mapping with no pending key.

WriteNull()

Writes a null scalar value.

public void WriteNull()

Exceptions

InvalidOperationException

The document root has already been written, or the current container is a mapping with no pending key.

WritePropertyName(string)

Writes a mapping key. The next write supplies its value.

public void WritePropertyName(string name)

Parameters

name string

The key text.

Remarks

A key whose written form, quotes included, is longer than the 1024 characters an implicit key may hold is written as an explicit key (? key), with the value indicator on the next line, so that the document stays readable.

Exceptions

ArgumentNullException

name is null.

ArgumentException

name contains an unpaired surrogate.

InvalidOperationException

The current container is not a mapping, or a key is already pending.

WriteStartMapping()

Begins a block mapping at the current value position.

public void WriteStartMapping()

Exceptions

InvalidOperationException

The document root has already been written, the current container is a mapping with no pending key, or the container would be nested deeper than the maximum depth.

YamlSerializationException

The container would be nested deeper than the maximum depth while the writer is driven by YamlSerializer, which reports the failure with the path to the value.

WriteStartSequence()

Begins a block sequence at the current value position.

public void WriteStartSequence()

Exceptions

InvalidOperationException

The document root has already been written, the current container is a mapping with no pending key, or the container would be nested deeper than the maximum depth.

YamlSerializationException

The container would be nested deeper than the maximum depth while the writer is driven by YamlSerializer, which reports the failure with the path to the value.

WriteString(string)

Writes a string scalar value.

public void WriteString(string value)

Parameters

value string

The string value.

Exceptions

ArgumentNullException

value is null.

ArgumentException

value contains an unpaired surrogate.

InvalidOperationException

The document root has already been written, or the current container is a mapping with no pending key.

Applies to

ProductVersions
.NET8, 10