This documentation explains how to use the SpanMapper<T> and SpanObjectBuilder<T> classes for mapping and parsing flat-file data. Their primary purpose is to configure the mapping of fields from delimited data to a strongly-typed class.
These features are designed to work with the To<T> method, which facilitates conversion of CSV rows into instances of T. Each row’s fields are mapped according to the schema defined in SpanObjectBuilder<T> or the SpanMapper<T> delegate, ensuring accurate transformation into structured objects.
SpanMapper<T>
public delegate T SpanMapper<T>(ReadOnlySpan<char> span, IEnumerable<FieldSpan> fieldSpans);
Purpose:
The SpanMapper<T> delegate maps data from a ReadOnlySpan<char> representing a row of delimited flat-file data into a strongly-typed object of type T. It uses a collection of FieldSpan objects to determine the start and length of each field in the span.
span: The sourceReadOnlySpan<char>containing the delimited row data.fieldSpans: A collection ofFieldSpanobjects defining the start position and length of each field in the row.
Class SpanObjectBuilder<T>
The SpanObjectBuilder<T> class is designed to instantiate strongly-typed objects (T) from delimited flat-file data. It supports default parsers for common data types and allows customization via the SetParser method and the Parse delegate.
Instantiate a SpanObjectBuilder
public T Instantiate(ReadOnlySpan<char> span, IEnumerable<FieldSpan> fieldSpans)
Purpose:
Creates an instance of type T using constructor injection. The fields in the constructor are populated based on fieldSpans and the mapped parsers in ParserMapping.
span: TheReadOnlySpan<char>containing the delimited row data.fieldSpans: A collection ofFieldSpanobjects specifying the position and length of each field.
Behavior:
- Identifies the appropriate constructor of
Tby matching the number of fields infieldSpans. - Iterates through each
FieldSpan, using the associated parser to convert the field to the required type. - If a type lacks a parser, throws an exception.
- If parsing fails, throws a
FormatExceptionwith detailed error information.
Example:
var builder = new SpanObjectBuilder<MyClass>();
var spans = new List<FieldSpan>
{
new FieldSpan { Start = 0, Length = 5 }, // Field 1
new FieldSpan { Start = 6, Length = 10 } // Field 2
};
var obj = builder.Instantiate("12345 true", spans);
Specifying the field parsers
SetParser<TField>
If you need to parse additional types or override the default behavior, use the SetParser method.
Purpose:
Customizes the parser for a specific data type.
TField: The type for which the parser is being set.parse: A delegate implementing custom parsing logic forTField.
Example:
var builder = new SpanObjectBuilder<MyClass>();
builder.SetParser<Guid>(s => Guid.Parse(s));
Parse delegate
public delegate object? Parse(ReadOnlySpan<char> span);
Purpose:
The Parse delegate defines a method for parsing a ReadOnlySpan<char> into an object of a specific type. It is used to handle custom parsing for various data types in the SpanObjectBuilder<T> class.
span: TheReadOnlySpan<char>containing the value to parse.
Default Parsers
By default, the SpanObjectBuilder<T> supports the following types:
- Strings
- Numbers (
int,long,short,byte,float,double,decimal) - Booleans
- Dates (
DateTime,DateOnly,TimeOnly,DateTimeOffset) - Characters (
char)
To<T> Method
To integrate SpanMapper<T> and SpanObjectBuilder<T>:
- Define a
SpanMapper<T>that calls theInstantiatemethod ofSpanObjectBuilder<T>. - Use the
To<T>method to map rows of delimited data into strongly-typed objects.
Example:
SpanMapper<MyClass> mapper = (span, fieldSpans) =>
new SpanObjectBuilder<MyClass>().Instantiate(span, fieldSpans);
var result = mapper("12345 true".AsSpan(), fieldSpans);
