Utf8DelimitedReader Struct
Definition
Provides a high-performance, forward-only reader for delimited (RFC 4180 CSV/TSV) bytes. The reader is a
ref struct, so it lives on the stack and cannot be boxed or captured.
public ref struct Utf8DelimitedReader
- Inherited Members
Remarks
A delimited document is an array of records. A call to Read() advances to the next token and reports it through TokenType: a document StartArray frames the records; with a header each record is an object (StartObject plus PropertyName / String pairs), and without a header each record is a positional array of String fields.
Fields are decoded when their record is read, and GetString() returns the decoded text: surrounding quotes are removed and doubled quotes are collapsed to a single literal. ValueSpan exposes the raw source bytes of a field value.
A line ends at a line feed, a carriage return and line feed, or a lone carriage return, and a blank line is skipped rather than read as a record of one empty field. Under Ragged, each field beyond the header's is named by its zero-based column index.
Constructors
Utf8DelimitedReader(ReadOnlySpan<byte>)
Initializes a new instance of the Utf8DelimitedReader struct over the supplied bytes.
public Utf8DelimitedReader(ReadOnlySpan<byte> data)
Parameters
dataReadOnlySpan<byte>The delimited source bytes.
Utf8DelimitedReader(ReadOnlySpan<byte>, DelimitedReaderOptions)
Initializes a new instance of the Utf8DelimitedReader struct over the supplied bytes using the supplied options.
public Utf8DelimitedReader(ReadOnlySpan<byte> data, DelimitedReaderOptions options)
Parameters
dataReadOnlySpan<byte>The delimited source bytes.
optionsDelimitedReaderOptionsThe reader options.
Remarks
A UTF-8 byte-order mark at the start of data is skipped; a U+FEFF anywhere else is field
content.
Exceptions
- 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. The comment character is checked even when comments are not allowed.
Properties
BytesConsumed
Gets the number of bytes consumed so far.
public readonly int BytesConsumed { get; }
Property Value
- int
The read position.
Headers
Gets the header column names, available once the document array has started.
public readonly IReadOnlyList<string> Headers { get; }
Property Value
- IReadOnlyList<string>
The header names, or an empty list in headerless mode.
LineNumber
Gets the 1-based line number at the current read position.
public readonly int LineNumber { get; }
Property Value
- int
The current line number.
TokenType
Gets the kind of the current token.
public readonly DelimitedTokenType TokenType { get; }
Property Value
- DelimitedTokenType
The current token kind.
ValueSpan
Gets the raw source bytes of the current field value, or an empty span for structural or synthesized tokens.
public readonly ReadOnlySpan<byte> ValueSpan { get; }
Property Value
- ReadOnlySpan<byte>
The raw field bytes.
Methods
GetString()
Gets the decoded text of the current property-name or string token.
public readonly string GetString()
Returns
- string
The decoded text.
Exceptions
- InvalidOperationException
Thrown when the current token has no text.
Read()
Advances the reader to the next token.
public bool Read()
Returns
Exceptions
- DelimitedFormatException
Thrown when the bytes are not valid delimited text.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |