Table of Contents

Utf8DelimitedWriter Struct

Definition

Namespace
Bodu.Text.Delimited.Writer
Assembly
Bodu.Text.Delimited.dll
Package
Bodu.Text.Delimited 1.3.0
Source
Utf8DelimitedWriter.cs

Provides a forward-only writer that emits delimited (RFC 4180 CSV/TSV) text as UTF-8 bytes to an IBufferWriter<T> or a Stream. The writer is a ref struct.

public ref struct Utf8DelimitedWriter
Inherited Members

Remarks

Records are written between WriteStartArray() and WriteEndArray(). An object record - WriteStartObject(), WritePropertyName(string) / WriteString(string) pairs, then WriteEndObject() - contributes a header row (from the first record's names) followed by a value row. A positional record - a nested WriteStartArray() of WriteString(string) values - contributes a value row with no header.

A field is quoted, with internal quotes doubled, when the reader would otherwise read it back differently: when it contains the delimiter, the quote character, or a line break; when it begins or ends with a space or a tab; when it is the first field of its record and begins with CommentChar; when it is the first field the writer writes and begins with U+FEFF; and when it is the only field of its record and is empty. Every other field is written bare.

The output therefore round-trips through Utf8DelimitedReader with the same delimiter and quote: a record of one empty field is written "" rather than as an empty line, which the reader skips; a first field is not read as a comment line by a reader that allows comments with the writer's comment character; a U+FEFF that begins the document is not skipped as a byte order mark; and a reader with TrimFields keeps the spaces and tabs at a field's ends. A record with no fields at all is written as an empty line, which the reader skips.

Constructors

Utf8DelimitedWriter(IBufferWriter<byte>)

Initializes a new instance of the Utf8DelimitedWriter struct that writes to the supplied buffer.

public Utf8DelimitedWriter(IBufferWriter<byte> output)

Parameters

output IBufferWriter<byte>

The destination buffer writer.

Exceptions

ArgumentNullException

Thrown when output is null.

Utf8DelimitedWriter(IBufferWriter<byte>, DelimitedWriterOptions)

Initializes a new instance of the Utf8DelimitedWriter struct that writes to the supplied buffer using the supplied options.

public Utf8DelimitedWriter(IBufferWriter<byte> output, DelimitedWriterOptions options)

Parameters

output IBufferWriter<byte>

The destination buffer writer.

options DelimitedWriterOptions

The writer options.

Exceptions

ArgumentNullException

Thrown when output is null.

ArgumentException

Thrown when the delimiter, quote or comment character of options is not an ASCII character or is a carriage return or a line feed, when the delimiter equals the quote, or when the comment character equals the delimiter or the quote.

Utf8DelimitedWriter(Stream)

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

public Utf8DelimitedWriter(Stream stream)

Parameters

stream Stream

The destination stream.

Exceptions

ArgumentNullException

Thrown when stream is null.

Utf8DelimitedWriter(Stream, DelimitedWriterOptions)

Initializes a new instance of the Utf8DelimitedWriter struct that writes to the supplied stream using the supplied options.

public Utf8DelimitedWriter(Stream stream, DelimitedWriterOptions options)

Parameters

stream Stream

The destination stream.

options DelimitedWriterOptions

The writer options.

Exceptions

ArgumentNullException

Thrown when stream is null.

ArgumentException

Thrown when the delimiter, quote or comment character of options is not an ASCII character or is a carriage return or a line feed, when the delimiter equals the quote, or when the comment character equals the delimiter or the quote.

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()

WriteEndArray()

Writes the end of the document array, or flushes a positional record when inside the document.

public void WriteEndArray()

WriteEndObject()

Writes the end of an object record, emitting the header row on the first record.

public void WriteEndObject()

WritePropertyName(string)

Writes the name of the next field within an object record.

public readonly void WritePropertyName(string name)

Parameters

name string

The field name.

Exceptions

ArgumentNullException

Thrown when name is null.

WriteStartArray()

Writes the start of the document array, or the start of a positional record when already inside the document.

public void WriteStartArray()

WriteStartObject()

Writes the start of an object record.

public void WriteStartObject()

WriteString(string)

Writes the value of the next field.

public readonly void WriteString(string value)

Parameters

value string

The field value.

Exceptions

ArgumentNullException

Thrown when value is null.

Applies to

ProductVersions
.NET8, 10