Table of Contents

Class CsvOptions<T>

Namespace
FlameCsv
Assembly
FlameCsv.Core.dll

Object used to configure dialect, converters, and other options to read and write CSV data.

public class CsvOptions<T> where T : unmanaged, IBinaryInteger<T>

Type Parameters

T

Token type

Inheritance
CsvOptions<T>

Constructors

CsvOptions()

Initializes an options-instance with default configuration.

public CsvOptions()

CsvOptions(CsvOptions<T>)

Initializes a new instance of options, copying the configuration from other.

public CsvOptions(CsvOptions<T> other)

Parameters

other CsvOptions<T>

Properties

AllowUndefinedEnumValues

Whether to allow enum values that are not defined in the enum type. Default is false.

public bool AllowUndefinedEnumValues { get; set; }

Property Value

bool

Aot

Returns a convenience type that provides AOT-safe access to converters.

[EditorBrowsable(EditorBrowsableState.Never)]
public CsvOptions<T>.AotSafeConverters Aot { get; }

Property Value

CsvOptions<T>.AotSafeConverters

Remarks

This API is meant to be used by the source generator to produce trimming/AOT safe code. Because of this, CsvConverterFactory<T> is not supported. All non-default converters must be configured manually using the Converters property.

BooleanValues

Optional custom boolean value mapping. If not empty, must contain at least one value for both true and false. Default is empty.

public IList<(string text, bool value)> BooleanValues { get; }

Property Value

IList<(string text, bool value)>
See Also

Comparer

String comparer used to match CSV header to members and parameters. Default is OrdinalIgnoreCase.

public IEqualityComparer<string> Comparer { get; set; }

Property Value

IEqualityComparer<string>

Remarks

The parsed CSV header fields are converted to strings using TryGetChars(ReadOnlySpan<T>, Span<char>, out int) or GetAsString(ReadOnlySpan<T>).

ConverterCache

Contains cached converters for types that have been requested with GetConverter(Type).

protected ConcurrentDictionary<Type, CsvConverter<T>> ConverterCache { get; }

Property Value

ConcurrentDictionary<Type, CsvConverter<T>>
See Also

Converters

Collection of all converters and factories of the options instance, not including the built-in converters (see UseDefaultConverters).

public IList<CsvConverter<T>> Converters { get; }

Property Value

IList<CsvConverter<T>>

Remarks

Modifying the collection after the options-instance is used (IsReadOnly is true) results in an exception.

Default

Returns read-only default options for T with the same configuration as new(). The returned instance is thread-safe.

public static CsvOptions<T> Default { get; }

Property Value

CsvOptions<T>

Remarks

Throws NotSupportedException for token types other than char or byte.

Delimiter

The separator character between CSV fields. Default value is ,.

public char Delimiter { get; set; }

Property Value

char

Dialect

Gets or creates the dialect using the configured options.

protected ref readonly CsvDialect<T> Dialect { get; }

Property Value

CsvDialect<T>

EnumFlagsSeparator

Separator character used when parsing and formatting flags-enums as strings.
Default is ',' (comma).

public char EnumFlagsSeparator { get; set; }

Property Value

char

Remarks

The separator character must not be a surrogate char, an ASCII digit, letter, or the '-' character.
If an enum name contains the separator character, a runtime exception will be thrown.

EnumFormat

The default format for enums, used if enum's format is not defined in Formats.

[StringSyntax("EnumFormat")]
public string? EnumFormat { get; set; }

Property Value

string
See Also

Escape

Optional character used for escaping special characters. The default value is null, which means RFC4180 escaping (quotes) is used.

public char? Escape { get; set; }

Property Value

char?

FieldQuoting

Defines the quoting behavior when writing values. Default is Auto.

public CsvFieldQuoting FieldQuoting { get; set; }

Property Value

CsvFieldQuoting

FormatProvider

Format provider used it none is defined for type in FormatProviders. Defaults to InvariantCulture.

public IFormatProvider? FormatProvider { get; set; }

Property Value

IFormatProvider
See Also

FormatProviders

Format providers used per type.

public IDictionary<Type, IFormatProvider?> FormatProviders { get; }

Property Value

IDictionary<Type, IFormatProvider>

Remarks

Structs and their Nullable<T> counterparts are treated as equal.

See Also

Formats

Format used per type.

public IDictionary<Type, string?> Formats { get; }

Property Value

IDictionary<Type, string>

Remarks

Structs and their Nullable<T> counterparts are treated as equal.

See Also

HasHeader

Whether to read/write a header record. The default is true.

public bool HasHeader { get; set; }

Property Value

bool

IgnoreEnumCase

Whether to ignore casing when parsing enum values. Default is true.

public bool IgnoreEnumCase { get; set; }

Property Value

bool

IsReadOnly

Whether the options-instance is sealed and can no longer be modified. Options become read only after they begin being used to avoid concurrency bugs.

public bool IsReadOnly { get; }

Property Value

bool
See Also

MaxConverterCacheSize

Maximum number of converters cached internally by the options instance before the cache is cleared. For converters by type, for example, with GetConverter(Type). Default is MaxValue.

protected int MaxConverterCacheSize { get; set; }

Property Value

int

MemoryPool

Pool used to create reusable buffers when reading multisegment data, or unescaping large fields. Default value is Shared. Set to null to disable pooling and always heap allocate.

public MemoryPool<T>? MemoryPool { get; set; }

Property Value

MemoryPool<T>

Remarks

Buffers that are larger than MaxBufferSize size are heap allocated.

Newline

1-2 characters long newline string. The default is CRLF.

public string Newline { get; set; }

Property Value

string

Remarks

If the newline is 2 characters long, either of the characters is allowed as a record delimiter, e.g., the default value can read CSV with only LF newlines.

NoReadAhead

Disables buffering CSV fields to memory when reading. The default is true, which will enable the library to use high performance SIMD operations to read multiple record's worth of fields before yielding them, which is significantly faster than reading records one-at-a-time. Unless you have a specific reason to disable read-ahead, it is recommended to keep it enabled.

[EditorBrowsable(EditorBrowsableState.Advanced)]
public bool NoReadAhead { get; set; }

Property Value

bool

Remarks

A pre-requisite for read-ahead to work is that the CsvDialect<T> has only ASCII tokens.

See Also

Null

Default null token to use when writing null values or reading nullable structs. Default is null (empty field in CSV).

public virtual string? Null { get; set; }

Property Value

string
See Also

NullTokens

Returns tokens used to parse and format null values. See GetNullToken(Type).

public IDictionary<Type, string?> NullTokens { get; }

Property Value

IDictionary<Type, string>
See Also

NumberStyles

Styles used when parsing IBinaryNumber<TSelf> and IFloatingPoint<TSelf>.

public IDictionary<Type, NumberStyles> NumberStyles { get; }

Property Value

IDictionary<Type, NumberStyles>

Remarks

Structs and their Nullable<T> counterparts are treated as equal.

See Also

Quote

Characted used to quote strings containing special characters. Default value is ".

public char Quote { get; set; }

Property Value

char

RecordCallback

Delegate that is called for each record before it is processed. Can be used to skip records or reset the header.

public CsvRecordCallback<T>? RecordCallback { get; set; }

Property Value

CsvRecordCallback<T>

Remarks

Comments are not fully supported. All lines are expected to be either valid CSV or empty. Commented lines with delimiters and/or mismatched quotes will not work properly.

StringPool

String pool to use when parsing strings. Default is null, which results in no pooling.

public StringPool? StringPool { get; set; }

Property Value

StringPool

Remarks

Pooling reduces raw throughput, but can have a profound impact on allocations if the data has repeating strings.

See Also

TypeBinder

The type binder used for reflection code paths. The default value is CsvReflectionBinder<T>.

public virtual ICsvTypeBinder<T> TypeBinder { get; set; }

Property Value

ICsvTypeBinder<T>
See Also
CsvTypeMap<T, TValue>

UseDefaultConverters

Whether to use the library's built-in converters. Default is true. The converters can be configured using properties of CsvOptions<T>.

public bool UseDefaultConverters { get; set; }

Property Value

bool

Remarks

The following types are supported by default:

ValidateFieldCount

If true, validates that all records have the same number of fields when reading CsvValueRecord<T> or writing with CsvWriter<T>. Default is false.

public bool ValidateFieldCount { get; set; }

Property Value

bool

Whitespace

Optional whitespace characters that are trimmed out of each field before processing them, and fields written with the preceding or trailing whitespace are quoted. The default is null/empty.

public string? Whitespace { get; set; }

Property Value

string
See Also

Methods

GetAsString(ReadOnlySpan<T>)

Returns a string representation of the value.

public virtual string GetAsString(ReadOnlySpan<T> value)

Parameters

value ReadOnlySpan<T>

Returns

string

Remarks

Used interchangeably with TryGetChars(ReadOnlySpan<T>, Span<char>, out int), and should return the exact same value for the same input.

GetConverter(Type)

Returns a converter for resultType.

[RequiresDynamicCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use the source generator APIs for native AOT applications.")]
[RequiresUnreferencedCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use the source generator APIs for native AOT applications.")]
public CsvConverter<T> GetConverter(Type resultType)

Parameters

resultType Type

Returns

CsvConverter<T>

Remarks

Never returns a CsvConverterFactory<T>

GetConverter<TResult>()

Returns a converter for TResult.

[RequiresDynamicCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use the source generator APIs for native AOT applications.")]
[RequiresUnreferencedCode("This code path may require types that cannot be statically analyzed and might need runtime code generation. Use the source generator APIs for native AOT applications.")]
public CsvConverter<T, TResult> GetConverter<TResult>()

Returns

CsvConverter<T, TResult>

Type Parameters

TResult

Type to convert

Exceptions

CsvConverterMissingException

GetFormat(Type, string?)

Returns the custom format configured for resultType, or defaultValue by default.

public virtual string? GetFormat(Type resultType, string? defaultValue = null)

Parameters

resultType Type
defaultValue string

Returns

string

GetFormatProvider(Type)

Returns the custom format provider configured for resultType, or FormatProvider by default.

public virtual IFormatProvider? GetFormatProvider(Type resultType)

Parameters

resultType Type

Returns

IFormatProvider

GetFromString(string?)

Returns the T representation of the string.

public virtual ReadOnlyMemory<T> GetFromString(string? value)

Parameters

value string

Returns

ReadOnlyMemory<T>

Remarks

Used interchangeably with TryWriteChars(ReadOnlySpan<char>, Span<T>, out int), and should return the exact same value for the same input.

GetNullToken(Type)

Returns the null value for parsing and formatting for the parameter type. Returns Null if none is configured in NullTokens.

public virtual ReadOnlyMemory<T> GetNullToken(Type resultType)

Parameters

resultType Type

Returns

ReadOnlyMemory<T>

GetNumberStyles(Type, NumberStyles)

Returns the custom number styles configured for the INumberBase<TSelf>, or defaultValue by default.

public virtual NumberStyles GetNumberStyles(Type resultType, NumberStyles defaultValue)

Parameters

resultType Type
defaultValue NumberStyles

Returns

NumberStyles

Remarks

Defaults are Integer for IBinaryInteger<TSelf> and Float for IFloatingPoint<TSelf>.

InitializeDialect()

Initializes the dialect.

protected virtual CsvDialect<T> InitializeDialect()

Returns

CsvDialect<T>

Remarks

If overridden, the dialect must be valid (see Validate()).

MakeReadOnly()

Seals the instance from modifications.

public void MakeReadOnly()

Remarks

Automatically called by the framework when the instance is used.

TryGetChars(ReadOnlySpan<T>, Span<char>, out int)

Writes value as chars to destination.

public virtual bool TryGetChars(ReadOnlySpan<T> value, Span<char> destination, out int charsWritten)

Parameters

value ReadOnlySpan<T>

Value to write

destination Span<char>

Buffer to write the value as chars to

charsWritten int

If successful, how many chars were written to the destination

Returns

bool

True if the destination buffer was large enough and the value was written

Remarks

Used interchangeably with GetAsString(ReadOnlySpan<T>), and should return the exact same value for the same input.

TryWriteChars(ReadOnlySpan<char>, Span<T>, out int)

Writes value as T to destination.

public virtual bool TryWriteChars(ReadOnlySpan<char> value, Span<T> destination, out int charsWritten)

Parameters

value ReadOnlySpan<char>

Value to write

destination Span<T>

Buffer to write the chars to

charsWritten int

If successful, how many chars were written to the destination

Returns

bool

True if the destination buffer was large enough and the value was written

Remarks

Used interchangeably with GetFromString(string?), and should return the exact same value for the same input.

Edit this page