Utf8DelimitedWriter Struct
Definition
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
outputIBufferWriter<byte>The destination buffer writer.
Exceptions
- ArgumentNullException
Thrown when
outputis 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
outputIBufferWriter<byte>The destination buffer writer.
optionsDelimitedWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
outputis null.- ArgumentException
Thrown when the delimiter, quote or comment character of
optionsis 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
streamStreamThe destination stream.
Exceptions
- ArgumentNullException
Thrown when
streamis 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
streamStreamThe destination stream.
optionsDelimitedWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
streamis null.- ArgumentException
Thrown when the delimiter, quote or comment character of
optionsis 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
namestringThe field name.
Exceptions
- ArgumentNullException
Thrown when
nameis 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
valuestringThe field value.
Exceptions
- ArgumentNullException
Thrown when
valueis null.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |