Class CsvWriter<T>
- Namespace
- FlameCsv
- Assembly
- FlameCsv.Core.dll
Provides convenience methods for writing CSV records.
public sealed class CsvWriter<T> : IDisposable, IAsyncDisposable where T : unmanaged, IBinaryInteger<T>Type Parameters
T
- Inheritance
-
objectCsvWriter<T>
- Implements
Constructors
CsvWriter(CsvFieldWriter<T>)
Initializes a new writer instance.
public CsvWriter(CsvFieldWriter<T> inner)Parameters
innerCsvFieldWriter<T>Field writer instance to write to
Properties
AutoFlush
Whether to automatically check if the writer needs to be flushed after each record.
The default value is true.
public bool AutoFlush { get; set; }Property Value
- See Also
EnsureTrailingNewline
Whether to automatically ensure a trailing newline is written if not already present
when the writer completes without an error.
The default value is true.
public bool EnsureTrailingNewline { get; set; }Property Value
Remarks
The trailing newline check does not validate the field count.
ExpectedFieldCount
Field count required for each record, if set. Terminating a record (with NextRecord() or completion) will throw a CsvWriteException if the record is not empty, and the field count does not match.
public int? ExpectedFieldCount { get; set; }Property Value
- int?
Remarks
If not null, set to the field count of the first non-empty record written if ValidateFieldCount
is true. You can set this property to null to reset the field count validation in this case.
FieldIndex
0-based index of the current field. Reset to 0 at the start of each record.
public int FieldIndex { get; }Property Value
HeaderWritten
Whether a header record has been written.
public bool HeaderWritten { get; }Property Value
Remarks
This property is set to true after the first call to WriteHeader.
It has no effect on the usage of the writer, but can be helpful when writing values in a streaming manner.
IsCompleted
Whether the writer has completed (disposed).
public bool IsCompleted { get; }Property Value
LineIndex
1-based index of the current line/record. Incremented after each newline.
public int LineIndex { get; }Property Value
Remarks
Newlines in quoted fields/strings are not counted, this property represents the logical CSV record index.
Options
Options instance of this writer.
public CsvOptions<T> Options { get; }Property Value
- CsvOptions<T>
Writer
Returns a read-only reference to the inner writer.
[EditorBrowsable(EditorBrowsableState.Never)]
public ref readonly CsvFieldWriter<T> Writer { get; }Property Value
Methods
Complete(Exception?)
Completes the writer, flushing any remaining data if exception is null.
Multiple completions are no-ops.
public void Complete(Exception? exception = null)Parameters
exceptionExceptionObserved exception when writing the data. If not null, the final buffer is not flushed and the exception is rethrown.
CompleteAsync(Exception?, CancellationToken)
Completes the writer, flushing any remaining data if exception is null.
Multiple completions are no-ops.
public ValueTask CompleteAsync(Exception? exception = null, CancellationToken cancellationToken = default)Parameters
exceptionExceptionObserved exception when writing the data, passed to the inner ICsvBufferWriter<T>. If not null, the final buffer is not flushed and the exception is rethrown.
cancellationTokenCancellationTokenToken to cancel the operation
Returns
Remarks
Unlike completion of ICsvBufferWriter<T> and PipeWriter,
this method rethrows exception if it is not null.
Flush()
Flushes the writer.
public void Flush()Exceptions
- ObjectDisposedException
Thrown if the writer has completed (see Complete(Exception?)).
FlushAsync(CancellationToken)
Flushes the writer.
public ValueTask FlushAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenToken to cancel flushing
Returns
Exceptions
- ObjectDisposedException
Thrown if the writer has completed (see CompleteAsync(Exception?, CancellationToken)).
NextRecord()
Writes a newline and flushes the buffer if needed when AutoFlush is true.
public void NextRecord()Exceptions
- ObjectDisposedException
The writer has completed
NextRecordAsync(CancellationToken)
Writes a newline and flushes the buffer if needed when AutoFlush is true.
public ValueTask NextRecordAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationTokenToken to cancel the flush
Returns
Exceptions
- ObjectDisposedException
The writer has completed
WriteField(ReadOnlySpan<char>, bool)
Writes a field with the preceding delimiter if needed.
public void WriteField(ReadOnlySpan<char> chars, bool skipEscaping = false)Parameters
charsReadOnlySpan<char>skipEscapingboolWhether no escaping should be performed, use with care
WriteField(ReadOnlySpan<T>, bool)
Writes a field with the preceding delimiter if needed.
public void WriteField(ReadOnlySpan<T> value, bool skipEscaping = false)Parameters
valueReadOnlySpan<T>Value to write
skipEscapingboolWhether no escaping should be performed, use with care
WriteField<TField>(CsvConverter<T, TField>, TField?)
Writes a field with the preceding delimiter if needed.
public void WriteField<TField>(CsvConverter<T, TField> converter, TField? value)Parameters
converterCsvConverter<T, TField>Converter instance to write the value with
valueTFieldValue to write
Type Parameters
TFieldField type that will be converted
WriteField<TField>(TField?)
Writes a field with the preceding delimiter if needed.
[RequiresDynamicCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use an alternative overload for native AOT applications.")]
[RequiresUnreferencedCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use an alternative overload for native AOT applications.")]
public void WriteField<TField>(TField? value)Parameters
valueTFieldValue to write
Type Parameters
TFieldField type that will be converted
Remarks
Converter will be retrieved from options.
WriteFields(ReadOnlySpan<string>, bool)
Writes the fields with the preceding delimiter if needed.
public void WriteFields(ReadOnlySpan<string> values, bool skipEscaping = false)Parameters
valuesReadOnlySpan<string>Values to write
skipEscapingboolWhether no escaping should be performed, use with care
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
null values are written as empty fields.
WriteHeader(in CsvRecord<T>)
Writes the header from the provided record.
public int WriteHeader(in CsvRecord<T> record)Parameters
recordCsvRecord<T>Record to write the headers from
Returns
- int
Number of fields written
Exceptions
- NotSupportedException
Thrown if the writer was created with HasHeader set to
falseor if the record does not have a header.
WriteHeader(params ReadOnlySpan<string>)
Writes the provided header values.
public int WriteHeader(params ReadOnlySpan<string> values)Parameters
valuesReadOnlySpan<string>Header values
Returns
- int
Number of fields written
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
null values are written as empty fields.
Does not validate HasHeader.
WriteHeader<TRecord>()
Writes the header for TRecord
to the current line using TypeBinder.
[RequiresUnreferencedCode("This code path uses reflection. Use the overloads accepting source generated CsvTypeMap for AOT/trimming compatible code.")]
[RequiresDynamicCode("This code path uses compiled expressions. Use the overloads accepting source generated CsvTypeMap for AOT/trimming compatible code.")]
public int WriteHeader<TRecord>()Returns
- int
Number of fields written
Type Parameters
TRecord
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
WriteHeader<TRecord>(CsvTypeMap<T, TRecord>)
Writes the header for TRecord to the current line using the type map.
public int WriteHeader<TRecord>(CsvTypeMap<T, TRecord> typeMap)Parameters
typeMapCsvTypeMap<T, TRecord>Type map to use for writing
Returns
- int
Number of fields written
Type Parameters
TRecord
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
WriteRecord(CsvPreservedRecord<T>)
Writes the provided record to the writer.
public int WriteRecord(CsvPreservedRecord<T> record)Parameters
recordCsvPreservedRecord<T>Record to write
Returns
- int
Number of fields written
Remarks
If the record uses the same options-instance as the writer, the raw record is written directly.
WriteRecord(in CsvRecord<T>)
Writes the provided record to the writer.
public int WriteRecord(in CsvRecord<T> record)Parameters
recordCsvRecord<T>Record to write
Returns
- int
Number of fields written
Remarks
If the record uses the same options-instance as the writer, the raw record is written directly.
WriteRecord(in CsvRecord<T>, scoped ReadOnlySpan<CsvFieldIdentifier>)
Writes the specified fields from the provided record to the writer.
public int WriteRecord(in CsvRecord<T> record, scoped ReadOnlySpan<CsvFieldIdentifier> fieldIds)Parameters
recordCsvRecord<T>Record to write
fieldIdsReadOnlySpan<CsvFieldIdentifier>Identifiers of fields to write
Returns
- int
Number of fields written
Remarks
If the record uses the same options-instance as the writer, the raw fields are written directly.
Fields are written in the order they are specified in fieldIds.
WriteRecord<TRecord>(CsvTypeMap<T, TRecord>, TRecord)
Writes the value to the current line using the type map.
public int WriteRecord<TRecord>(CsvTypeMap<T, TRecord> typeMap, TRecord value)Parameters
typeMapCsvTypeMap<T, TRecord>Type map to use for writing
valueTRecordValue to write
Returns
- int
Number of fields written
Type Parameters
TRecord
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
Throws on null values.
Exceptions
WriteRecord<TRecord>(TRecord)
Writes the value to the current line using TypeBinder.
[RequiresUnreferencedCode("This code path uses reflection. Use the overloads accepting source generated CsvTypeMap for AOT/trimming compatible code.")]
[RequiresDynamicCode("This code path uses compiled expressions. Use the overloads accepting source generated CsvTypeMap for AOT/trimming compatible code.")]
public int WriteRecord<TRecord>(TRecord value)Parameters
valueTRecordValue to write
Returns
Type Parameters
TRecord
Remarks
Does not write a trailing newline, see NextRecord() and NextRecordAsync(CancellationToken).
Throws on null values.