CsvSeparatorStream class · CsvHelper

public sealed class CsvSeparatorStream : Stream

Namespace: CsvHelper
Assembly: CsvHelper.dll
Inheritance: object MarshalByRefObject Stream CsvSeparatorStream
Builds: net10.0 netstandard2.1 netstandard2.0 net47
Source: CsvSeparatorStream.cs

Remarks

Pass it to CsvReader.Create(Stream, CsvReaderOptions, bool). The reader then splits fields on Replacement, and gives the stream its CsvReaderOptions.Mode, quote, escape and comment characters, so the separators that are text stay as they are: in quoted fields, after an escape character and in comment lines. Everything else passes through unchanged, so CsvReader.RawRecord shows Replacement where the separator was.

The stream works on bytes, in the buffer of the caller, so the reader keeps its UTF-8 fast path. The input is UTF-8, or a single-byte encoding set in CsvReaderOptions.Encoding; UTF-16 and UTF-32 input is not supported. Input that contains Replacement outside quoted fields would read wrongly, so reading it throws a CsvFormatException: choose another replacement for such data.

Example

using var reader = CsvReader.Create(new CsvSeparatorStream(File.OpenRead("orders.csv"), "||"));
while (reader.Read()) Console.WriteLine(reader.GetString("Name"));

Constructors

CsvSeparatorStream(Stream, string, char, bool)

Added in v34.0.0

public CsvSeparatorStream(Stream stream, string separator, char replacement = '\u001f', bool leaveOpen = false)

Creates a stream that reads stream with replacement in place of separator.

Parameters

streamStream: The input, read from its current position. It does not need to be seekable.
separatorstring: The separator of the input, such as ||: 1 to 16 bytes in the input encoding, without line breaks, the quote, escape or comment character, or replacement.
replacementchar: The ASCII character that takes the place of each separator, and that the reader splits on. The input must not contain it outside quoted fields.
leaveOpenbool: Whether stream stays open when this stream is disposed.

Exceptions

ArgumentNullException: stream or separator is null.
ArgumentException: stream cannot be read, separator is empty, too long or contains a character it cannot contain, or replacement is not ASCII or is a line break.

Properties

CanRead

Added in v34.0.0

public override bool CanRead { get; }

Whether the stream can be read: true until it is disposed.

Property value

bool

CanSeek

Added in v34.0.0

public override bool CanSeek { get; }

Always false: the stream reads its input once, in order.

Property value

bool

CanWrite

Added in v34.0.0

public override bool CanWrite { get; }

Always false: the stream is read-only.

Property value

bool

Length

Added in v34.0.0

public override long Length { get; }

Not supported: the stream is not seekable.

Property value

long

Exceptions

NotSupportedException: Always.

Position

Added in v34.0.0

public override long Position { get; set; }

Not supported: the stream is not seekable.

Property value

long

Exceptions

NotSupportedException: Always.

Replacement

Added in v34.0.0

public char Replacement { get; }

The character that takes the place of each Separator, and that the reader splits on.

Property value

char

Separator

Added in v34.0.0

public string Separator { get; }

The separator of the input that this stream replaces.

Property value

string

Methods

Dispose(bool)

Added in v34.0.0

protected override void Dispose(bool disposing)

Disposes the stream and, unless it was created to leave it open, the underlying stream.

Parameters

disposingbool: Whether the call comes from Stream.Dispose() rather than a finalizer.

DisposeAsync()

net10.0 onlyAdded in v34.0.0

public override ValueTask DisposeAsync()

Disposes the stream and, unless it was created to leave it open, the underlying stream.

Returns

A task that completes when the underlying stream is disposed.

Flush()

Added in v34.0.0

public override void Flush()

Does nothing: the stream is read-only.

Read(Span<byte>)

net10.0 onlyAdded in v34.0.0

public override int Read(Span<byte> buffer)

Reads input, with Replacement in place of each separator.

Parameters

bufferSpan<byte>: The buffer to read into.

Returns

int

The number of bytes read: at least 1, or 0 at the end of the input (or when buffer is empty).

Exceptions

ObjectDisposedException: The stream has been disposed.
CsvFormatException: The input contains Replacement outside quoted fields.
NotSupportedException: The input starts with a UTF-16 or UTF-32 byte order mark.

Read(byte[], int, int)

Added in v34.0.0

public override int Read(byte[] buffer, int offset, int count)

Reads input, with Replacement in place of each separator.

Parameters

bufferbyte[]: The buffer to read into.
offsetint: The position in buffer to read into.
countint: The most bytes to read.

Returns

int

The number of bytes read: at least 1, or 0 at the end of the input (or when count is 0).

Exceptions

ArgumentNullException: buffer is null.
ArgumentOutOfRangeException: offset and count are not a range of buffer.
ObjectDisposedException: The stream has been disposed.
CsvFormatException: The input contains Replacement outside quoted fields.
NotSupportedException: The input starts with a UTF-16 or UTF-32 byte order mark.

ReadAsync(Memory<byte>, CancellationToken)

net10.0 onlyAdded in v34.0.0

public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)

Reads input asynchronously, with Replacement in place of each separator.

Parameters

bufferMemory<byte>: The buffer to read into.
cancellationTokenCancellationToken: Cancels reading from the underlying stream.

Returns

The number of bytes read: at least 1, or 0 at the end of the input (or when buffer is empty).

Exceptions

ObjectDisposedException: The stream has been disposed.
CsvFormatException: The input contains Replacement outside quoted fields.
NotSupportedException: The input starts with a UTF-16 or UTF-32 byte order mark.

ReadAsync(byte[], int, int, CancellationToken)

Added in v34.0.0

public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)

Reads input asynchronously, with Replacement in place of each separator.

Parameters

bufferbyte[]: The buffer to read into.
offsetint: The position in buffer to read into.
countint: The most bytes to read.
cancellationTokenCancellationToken: Cancels reading from the underlying stream.

Returns

Task<int>

The number of bytes read: at least 1, or 0 at the end of the input (or when count is 0).

Exceptions

ArgumentNullException: buffer is null.
ArgumentOutOfRangeException: offset and count are not a range of buffer.
ObjectDisposedException: The stream has been disposed.
CsvFormatException: The input contains Replacement outside quoted fields.
NotSupportedException: The input starts with a UTF-16 or UTF-32 byte order mark.

Seek(long, SeekOrigin)

Added in v34.0.0

public override long Seek(long offset, SeekOrigin origin)

Not supported: the stream is not seekable.

Parameters

offsetlong: Not used.
originSeekOrigin: Not used.

Returns

long

Nothing: the method always throws.

Exceptions

NotSupportedException: Always.

SetLength(long)

Added in v34.0.0

public override void SetLength(long value)

Not supported: the stream is read-only.

Parameters

valuelong: Not used.

Exceptions

NotSupportedException: Always.

Write(byte[], int, int)

Added in v34.0.0

public override void Write(byte[] buffer, int offset, int count)

Not supported: the stream is read-only.

Parameters

bufferbyte[]: Not used.
offsetint: Not used.
countint: Not used.

Exceptions

NotSupportedException: Always.

Fields

DefaultReplacement

Added in v34.0.0static

public const char DefaultReplacement = '\u001f'

The default Replacement: U+001F, the ASCII unit separator, which text does not contain.