Utf8YamlWriter Struct
Definition
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
outputIBufferWriter<byte>The buffer to which UTF-8 YAML is written.
Exceptions
- ArgumentNullException
outputis null.
Utf8YamlWriter(IBufferWriter<byte>, YamlWriterOptions)
Initializes a new instance of the Utf8YamlWriter struct with options.
public Utf8YamlWriter(IBufferWriter<byte> output, YamlWriterOptions options)
Parameters
outputIBufferWriter<byte>The buffer to which UTF-8 YAML is written.
optionsYamlWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
outputis 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
valueboolThe 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
valuedoubleThe 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
valuelongThe 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
namestringThe 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
nameis null.- ArgumentException
namecontains 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
valuestringThe string value.
Exceptions
- ArgumentNullException
valueis null.- ArgumentException
valuecontains an unpaired surrogate.- InvalidOperationException
The document root has already been written, or the current container is a mapping with no pending key.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |