CsvRecordMapper()
Added in v34.0.0
protected CsvRecordMapper()Creates a mapper whose columns are looked up by their own names.
Class in CsvHelper
CsvRecordMapper<T>
Added in v34.0.0
Reads records of type T from the columns of one reader's header. The CsvHelper source generator writes one for each CsvRecordAttribute type; CsvRecordMapper.Create<T>(CsvReader) creates it.
public abstract class CsvRecordMapper<T>- Namespace
CsvHelper- Assembly
CsvHelper.dll- Builds
- net10.0 netstandard2.1 netstandard2.0 net47
- Source
- CsvRecordMapper.cs
Remarks
A mapper resolves its columns when it is created and does not change afterwards, so it can read records of any reader with the same columns, on any thread (the workers of CsvReader.ParallelEnumerate<T>(int) share one).
To write one by hand, find the columns in the constructor with Column(CsvReader, string, int, bool, string), call ThrowIfColumnsMissing, and read the fields with the reader's CsvReader.GetString(int) and CsvReader.Parse<T>(int) in Read(CsvReader). Register it with CsvRecordMapper.Register<T>(Func<CsvReader, CsvRecordMapper<T>>), or put a CsvConverterAttribute naming it on T.
Constructors
CsvRecordMapper(string)
Added in v34.0.0
protected CsvRecordMapper(string columnPrefix)Creates a mapper that puts columnPrefix in front of the names it looks up.
Parameters
columnPrefixstring- The text in front of each header name, such as
"Ship ", for a record read as a member of another record (CsvColumnAttribute.Prefix);""for none.
Exceptions
- ArgumentNullException
columnPrefixisnull.
Properties
ColumnPrefix
Added in v34.0.0
protected string ColumnPrefix { get; }The text that Column(CsvReader, string, int, bool, string) puts in front of each header name; "" for none.
Property value
string
Methods
Column(CsvReader, string, int, bool, string)
Added in v34.0.0
protected int Column(CsvReader reader, string name, int index, bool optional, string member)Finds the column of a member: index when it is not negative, else the header column called ColumnPrefix followed by name. Missing required columns are reported together by ThrowIfColumnsMissing.
Parameters
readerCsvReader- The reader whose header is searched.
namestring- The header name of the column, matched as by CsvReader.TryGetFieldIndex(string, out int).
indexint- The 0-based index of the column, or -1 to find it by
name. optionalbool- Whether the column may be missing.
memberstring- The name of the member or parameter, for the error message.
Returns
int
The 0-based index of the column, or -1 when the header has no such column.
Column(CsvReader, string[], int, bool, string)
Added in v34.0.0
protected int Column(CsvReader reader, string[] names, int index, bool optional, string member)Finds the column of a member that can have several names: index when it is not negative, else the header column called ColumnPrefix followed by the first of names that the header has. Missing required columns are reported together by ThrowIfColumnsMissing.
Parameters
readerCsvReader- The reader whose header is searched.
namesstring[]- The header names of the column, tried in order, each matched as by CsvReader.TryGetFieldIndex(string, out int).
indexint- The 0-based index of the column, or -1 to find it by
names. optionalbool- Whether the column may be missing.
memberstring- The name of the member or parameter, for the error message.
Returns
int
The 0-based index of the column, or -1 when the header has none of the names.
Exceptions
- ArgumentNullException
namesisnull.
Column(CsvReader, string[], int, int, bool, string)
Added in v34.0.0
protected int Column(CsvReader reader, string[] names, int nameIndex, int index, bool optional, string member)Finds the column of a member among several columns with the same name: index when it is not negative, else the one at nameIndex among the header columns called ColumnPrefix followed by one of names (the first name that the header has that many times). Missing required columns are reported together by ThrowIfColumnsMissing.
Parameters
readerCsvReader- The reader whose header is searched.
namesstring[]- The header names of the column, tried in order, each matched as by CsvReader.TryGetFieldIndex(string, int, out int).
nameIndexint- 0 for the first column with the name, 1 for the second, and so on.
indexint- The 0-based index of the column, or -1 to find it by
names. optionalbool- Whether the column may be missing.
memberstring- The name of the member or parameter, for the error message.
Returns
int
The 0-based index of the column, or -1 when the header has none of the names that many times.
Exceptions
- ArgumentNullException
namesisnull.- ArgumentOutOfRangeException
nameIndexis negative.
ColumnNames(CsvReader, int, int, string)
Added in v34.0.0
protected string[] ColumnNames(CsvReader reader, int start, int end, string member)The header names of the columns from start to end, the keys of a dictionary member that reads them.
Parameters
readerCsvReader- The reader whose header names the columns.
startint- The 0-based index of the first column.
endint- The 0-based index of the last column, or -1 for the last column of the header.
memberstring- The name of the member, for the error message.
Returns
string[]
The names of the columns that the header has, in order.
Exceptions
- ArgumentNullException
readerisnull.- ArgumentOutOfRangeException
startis negative.- InvalidOperationException
- The input has no header.
Columns(CsvReader, string[], bool, string)
Added in v34.0.0
protected int[] Columns(CsvReader reader, string[] names, bool optional, string member)Finds the columns of a collection member: every header column called ColumnPrefix followed by the first of names that the header has, in order, for files that repeat a column name. Without any, a required member is reported by ThrowIfColumnsMissing.
Parameters
readerCsvReader- The reader whose header is searched.
namesstring[]- The header names of the columns, tried in order, each matched as by CsvReader.TryGetFieldIndex(string, int, out int).
optionalbool- Whether the columns may be missing, which reads an empty collection.
memberstring- The name of the member, for the error message.
Returns
int[]
The 0-based indexes of the columns, in header order; empty when the header has none of the names.
Exceptions
- ArgumentNullException
namesisnull.
FindFailingMember(CsvReader, out int)
Added in v34.0.0
public virtual string? FindFailingMember(CsvReader reader, out int fieldIndex)After Read(CsvReader) threw for the current record, finds the member whose field made it throw, by reading the members again one at a time. The record methods of CsvReader call it to say where a record failed (CsvFormatException.Member), so reading costs nothing more until a record fails. Generated mappers implement it; this implementation finds nothing.
Parameters
readerCsvReader- The reader, still positioned on the record that failed.
fieldIndexint- The 0-based index of the field of the member, or -1 when it is not known or no member failed.
Returns
string?
The member, as error messages name it (
Order.Price), or null when every member reads on its own, such as when the constructor or a setter threw.NestedMapper<TNested>(CsvReader, string)
Added in v34.0.0
protected CsvRecordMapper<TNested> NestedMapper<TNested>(CsvReader reader, string prefix)Creates the mapper of a member whose type is itself a record type, which reads its columns from the same records, with ColumnPrefix and then prefix in front of their names. Its missing required columns are reported with this mapper's by ThrowIfColumnsMissing.
Type parameters
TNested- The type of the member.
Parameters
readerCsvReader- The reader whose header is searched.
prefixstring- The text in front of the nested record's header names (CsvColumnAttribute.Prefix);
""for none.
Returns
CsvRecordMapper<TNested>
Exceptions
- ArgumentNullException
prefixisnull.- InvalidOperationException
TNestedhas no mapper, or its mapper does not support column prefixes and the prefix is not empty, or the nested mappers lead back to their own type without end.
Read(CsvReader)
Added in v34.0.0abstract
public abstract T Read(CsvReader reader)Reads the current record of reader.
Parameters
readerCsvReader- A reader positioned on a record, whose columns are those of the reader the mapper was created for.
Returns
T
A new
T with the values of the record.Exceptions
- FormatException
- A field cannot be parsed as the type of its member.
- OverflowException
- A numeric field is outside the range of the type of its member.
Read(CsvReader, T)
Added in v34.0.0
public virtual void Read(CsvReader reader, T record)Reads the current record of reader into record, an existing instance, for CsvReader.EnumerateRecords. Generated mappers implement it for classes whose members can all be set after construction; this implementation throws.
Parameters
readerCsvReader- A reader positioned on a record, whose columns are those of the reader the mapper was created for.
recordT- The instance whose members are set.
Exceptions
- NotSupportedException
- The mapper cannot refill an instance.
- FormatException
- A field cannot be parsed as the type of its member.
- OverflowException
- A numeric field is outside the range of the type of its member.
ThrowIfColumnsMissing(CsvReader)
Added in v34.0.0
protected void ThrowIfColumnsMissing(CsvReader reader)Throws a KeyNotFoundException naming every required column that Column(CsvReader, string, int, bool, string) and NestedMapper did not find, if there are any.
Parameters
readerCsvReader- The reader whose header was searched.
Exceptions
- KeyNotFoundException
- The header lacks a required column, or the input has no header and a required member has no column index.