Utf8IniWriter Struct
Definition
Provides a forward-only writer that emits INI text as UTF-8 bytes to an IBufferWriter<T> or a
Stream. The writer is a ref struct.
public ref struct Utf8IniWriter
- Inherited Members
Remarks
INI is line-oriented, so the writer emits progressively: WriteSectionHeader(string) produces a
[name] line, WritePropertyName(string) followed by WriteString(string) produces
one key=value line, and WriteComment(string) produces one comment line per line of its text.
The writer writes only text that Utf8IniReader reads back unchanged, and throws ArgumentException for the following:
-
a value containing a line break, which a
key=valueline cannot hold, or beginning or ending with a space or a tab, which the reader trims; -
a key that is empty, begins or ends with a space or a tab, contains
=or a line break, or begins with[,;or#, which the reader would read as another key, a section header or a comment; -
a section name that is empty, begins or ends with a space or a tab, contains a line break, or holds a
]that a;or#follows after optional spaces and tabs, where the reader would end the name; - a key or a section name that begins with U+FEFF, which the reader skips as a byte order mark at the start of a document, refused wherever the name is written so that the rule does not depend on position.
Constructors
Utf8IniWriter(IBufferWriter<byte>)
Initializes a new instance of the Utf8IniWriter struct that writes to the supplied buffer.
public Utf8IniWriter(IBufferWriter<byte> output)
Parameters
outputIBufferWriter<byte>The destination buffer writer.
Exceptions
- ArgumentNullException
Thrown when
outputis null.
Utf8IniWriter(IBufferWriter<byte>, IniWriterOptions)
Initializes a new instance of the Utf8IniWriter struct that writes to the supplied buffer using the supplied options.
public Utf8IniWriter(IBufferWriter<byte> output, IniWriterOptions options)
Parameters
outputIBufferWriter<byte>The destination buffer writer.
optionsIniWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
outputis null.
Utf8IniWriter(Stream)
Initializes a new instance of the Utf8IniWriter struct that writes to the supplied stream.
public Utf8IniWriter(Stream stream)
Parameters
streamStreamThe destination stream.
Exceptions
- ArgumentNullException
Thrown when
streamis null.
Utf8IniWriter(Stream, IniWriterOptions)
Initializes a new instance of the Utf8IniWriter struct that writes to the supplied stream using the supplied options.
public Utf8IniWriter(Stream stream, IniWriterOptions options)
Parameters
streamStreamThe destination stream.
optionsIniWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
streamis null.
Properties
BytesCommitted
Gets the number of bytes flushed to the destination.
public readonly long BytesCommitted { get; }
Property Value
- long
The committed byte count.
BytesPending
Gets the number of bytes written but not yet flushed to the destination.
public readonly long BytesPending { get; }
Property Value
- long
The pending byte count; always zero in direct buffer-writer mode.
Methods
Dispose()
Flushes any buffered bytes and releases the writer.
public void Dispose()
Flush()
Flushes any buffered bytes to the destination stream. This method is a no-op in direct buffer-writer mode.
public void Flush()
WriteComment(string)
Writes a comment as one comment line per line of its text, each prefixed with the configured comment character and followed by a line feed.
public void WriteComment(string text)
Parameters
textstringThe comment text, without the leading prefix.
Remarks
A carriage return, a line feed, or a carriage return followed by a line feed ends a line of the text, as it ends a line for Utf8IniReader, so each line reads back as a comment of its own; an empty line becomes an empty comment line.
Exceptions
- ArgumentNullException
Thrown when
textis null.
WritePropertyName(string)
Writes a key name, followed by the = assignment. Call WriteString(string) next to write
the value.
public void WritePropertyName(string name)
Parameters
namestringThe key name.
Remarks
A key beginning with # is refused even though a reader may disallow hash comments, because the writer
cannot know the options its output will be read with. A key beginning with U+FEFF is refused wherever it is
written, although the reader skips U+FEFF only at the start of a document, where it is a byte order mark, so
that the rule does not depend on position.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- ArgumentException
Thrown when
nameis empty, begins or ends with a space or a tab, contains=, a carriage return or a line feed, or begins with[,;or#, since the reader would not read it back as this key, or when it begins with U+FEFF.
WriteSectionHeader(string)
Writes a section header line ([name]).
public void WriteSectionHeader(string name)
Parameters
namestringThe section name.
Remarks
A name may hold any other ]: the reader ends a section name at the first ] that only whitespace or
a comment follows, so foo]bar is written as [foo]bar] and read back unchanged. A # after a
] is refused even though a reader may disallow hash comments, because the writer cannot know the options
its output will be read with. A name beginning with U+FEFF is refused, as a key beginning with it is, even
though the reader would read it back unchanged, so that keys and section names follow one rule wherever they are
written.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- ArgumentException
Thrown when
nameis empty, begins or ends with a space or a tab, contains a carriage return or a line feed, or holds a]that a;or#follows after optional spaces and tabs, since the reader would not read it back as this name, or when it begins with U+FEFF.
WriteString(string)
Writes a string value, followed by a line feed.
public void WriteString(string value)
Parameters
valuestringThe value to write.
Exceptions
- ArgumentNullException
Thrown when
valueis null.- ArgumentException
Thrown when
valuecontains a carriage return or a line feed, which akey=valueline cannot hold, or begins or ends with a space or a tab, which the reader trims.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |