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

UseDefaultConverters

CsvBooleanValuesAttribute

Comparer

String comparer used to match CSV headers and BooleanValues. Default is OrdinalIgnoreCase.

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

Property Value

IEqualityComparer<string>

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

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

UseDefaultConverters

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

Remarks

You can combine conditions using bitwise OR. For example, to quote both empty fields, and fields with leading spaces:

CsvFieldQuoting.Empty | CsvFieldQuoting.LeadingSpaces

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

GetFormatProvider(Type)

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

FormatProvider

GetFormatProvider(Type)

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

GetFormat(Type, string?)

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 first member that matches a header 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

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

CsvOptions(CsvOptions<T>)

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 rented from the shared array pool.

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.

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

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

CanFormatNull

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

GetNumberStyles(Type, NumberStyles)

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

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.

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

FieldQuoting

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>

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

• string
  
• enum
  
• bool
  
• Common IBinaryNumber<TSelf> types such as int and long)
  
• Common IFloatingPoint<TSelf> types such as double and float
  
• Guid
  
• DateTime
  
• DateTimeOffset
  
• TimeSpan
  
• For token type char any type that implements ISpanFormattable and ISpanParsable<TSelf>.
  
• For token type byte any type that implements at least one of IUtf8SpanFormattable and IUtf8SpanParsable<TSelf>, with ISpanFormattable and ISpanParsable<TSelf> as fallbacks.
  

ValidateFieldCount

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

public bool ValidateFieldCount { get; set; }

Property Value

bool

Methods

DialectEquals(CsvOptions<T>?)

Returns true if other has the exact same CSV dialect as this instance (e.g. both types read and write CSV structure identically).

[EditorBrowsable(EditorBrowsableState.Never)]
public bool DialectEquals(CsvOptions<T>? other)

Parameters

other CsvOptions<T>

Returns

bool

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.

Validate()

Ensures Delimiter, Quote, and Escape are valid.

public void Validate()

Exceptions

CsvConfigurationException