Table of Contents

Utf8IniWriter Struct

Definition

Namespace
Bodu.Text.Ini.Writer
Assembly
Bodu.Text.Ini.dll
Package
Bodu.Text.Ini 1.3.0
Source
Utf8IniWriter.cs

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=value line 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

output IBufferWriter<byte>

The destination buffer writer.

Exceptions

ArgumentNullException

Thrown when output is 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

output IBufferWriter<byte>

The destination buffer writer.

options IniWriterOptions

The writer options.

Exceptions

ArgumentNullException

Thrown when output is null.

Utf8IniWriter(Stream)

Initializes a new instance of the Utf8IniWriter struct that writes to the supplied stream.

public Utf8IniWriter(Stream stream)

Parameters

stream Stream

The destination stream.

Exceptions

ArgumentNullException

Thrown when stream is 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

stream Stream

The destination stream.

options IniWriterOptions

The writer options.

Exceptions

ArgumentNullException

Thrown when stream is 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

text string

The 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 text is 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

name string

The 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 name is null.

ArgumentException

Thrown when name is 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

name string

The 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 name is null.

ArgumentException

Thrown when name is 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

value string

The value to write.

Exceptions

ArgumentNullException

Thrown when value is null.

ArgumentException

Thrown when value contains a carriage return or a line feed, which a key=value line cannot hold, or begins or ends with a space or a tab, which the reader trims.

Applies to

ProductVersions
.NET8, 10