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 sealed class CsvOptions<T> where T : unmanaged, IBinaryInteger<T>

Type Parameters

T

Token type (char or byte)

Inheritance
object
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

Remarks

Unlike IsDefined(Type, object), flags-enums are considered valid if an undefined value is a combination of defined flags.

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

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: ,

public char Delimiter { get; set; }

Property Value

char

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

ExceptionHandler

Delegate that is called when an exception is thrown when parsing a record.
Not used with Enumerate().

public CsvExceptionHandler<T>? ExceptionHandler { get; set; }

Property Value

CsvExceptionHandler<T>

FieldQuoting

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

public CsvFieldQuoting FieldQuoting { get; set; }

Property Value

CsvFieldQuoting

Remarks

You can combine conditions using bitwise OR. For example, to quote both empty fields and fields with leading spaces: CsvFieldQuoting.Empty | CsvFieldQuoting.LeadingSpaces
Having a non-zero value while Quote is null will throw an exception when writing.

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

IgnoreDuplicateHeaders

Whether to ignore CSV headers that match to the same property, field, or constructor parameter as another header. If true, only the last match is used. Default is false, which throws an exception if a duplicate header is encountered.

public bool IgnoreDuplicateHeaders { 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

IgnoreHeaderCase

Whether to ignore case when matching enum values. Default is true.

public bool IgnoreHeaderCase { get; set; }

Property Value

bool
See Also

IgnoreUnmatchedHeaders

Whether to ignore headers that cannot be matched to any property, field, or constructor parameter. Default is false, which throws an exception if an unrecognized header field is encountered.

public bool IgnoreUnmatchedHeaders { 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.
Create a copy of the instance if you need to modify it after this point.

public bool IsReadOnly { get; }

Property Value

bool
See Also

Newline

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

public CsvNewline Newline { get; set; }

Property Value

CsvNewline

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.

NormalizeHeader

Function used to normalize header values when reading the header record.
The default is null, which uses the header value as-is.

public Func<ReadOnlySpan<char>, string>? NormalizeHeader { get; set; }

Property Value

Func<ReadOnlySpan<char>, string>
See Also

Null

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

public 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 control characters. Default value: "
If set to null, no control characters or newlines can appear anywhere in the data, and FieldQuoting has no effect.

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

All records are expected to be valid CSV, so even if the callback skips a record (e.g. starting with #), it must still have valid CSV structure, and control characters like delimiters and quotes are NOT ignored.

Trimming

Whether to trim leading and/or trailing spaces from fields.
The default value is None.

public CsvFieldTrimming Trimming { get; set; }

Property Value

CsvFieldTrimming
See Also

TypeBinder

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

public 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:

ValidateQuotes

Configures how strictly quotes are validated when reading CSV. Has no effect if Quote is null.
The default value is Strict, which validates every accessed field for validity, but not unread fields or skipped records.

public CsvQuoteValidation ValidateQuotes { get; set; }

Property Value

CsvQuoteValidation

Remarks

Quote parity is still required; every field must have an even number of quotes.

Methods

AddConverter<TConverter>()

Adds a converter to be lazily created when needed.

public CsvOptions<T> AddConverter<TConverter>() where TConverter : ICsvConverterFactory<T>

Returns

CsvOptions<T>

Type Parameters

TConverter

Type of converter factory to add

AddConverter<TValue>(CsvConverter<T, TValue>)

Adds a converter to the converters collection.

public CsvOptions<T> AddConverter<TValue>(CsvConverter<T, TValue> converter)

Parameters

converter CsvConverter<T, TValue>

Returns

CsvOptions<T>

Type Parameters

TValue

AddConverter<TValue>(Func<CsvOptions<T>, CsvConverter<T, TValue>>)

Adds a converter to be lazily created when needed.

public CsvOptions<T> AddConverter<TValue>(Func<CsvOptions<T>, CsvConverter<T, TValue>> factory)

Parameters

factory Func<CsvOptions<T>, CsvConverter<T, TValue>>

Factory function to create the converter when first needed

Returns

CsvOptions<T>

Type Parameters

TValue

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 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 IFormatProvider? GetFormatProvider(Type resultType)

Parameters

resultType Type

Returns

IFormatProvider

GetNullToken(Type)

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

public 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 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>.

MakeReadOnly()

Seals the instance from modifications.

public void MakeReadOnly()

Remarks

Automatically called by the framework when the instance is used.

Edit this page