FileCsvDocument

ReferencesSince v9.0
A simple, general-purpose, in-memory representation of a RFC 4180-compliant comma-separated value (CSV) file.

Read a file with Read(string) (or Read(string, bool) to treat the first row as a column-name header), then query its dimensions (RowCount, ColumnCount), retrieve typed values by column and row with the TryGet methods — addressing columns by index or, when a header is present, by name — or enumerate its rows. To build a file, construct the document with a fixed column count, populate cells with the Set(int, int, string) overloads (addressed by column and row), then persist it with Save(string). Every row has the same number of columns; addressing a column outside that count throws.

Constructors

FileCsvDocument

#Since v9.0
Constructs a new, empty document with a fixed number of columns. Every row written to the document has exactly this many fields. The document has no header row.
public FileCsvDocument(
columnCount
The number of columns. Must be greater than zero.
)
ArgumentOutOfRangeExceptionThrown when columnCount is less than one.

FileCsvDocument

#Since v9.0
Constructs a new, empty document with a header row of column names. The number of columns is the number of names supplied, and the header is written ahead of the data rows by Save(string). Columns can then be addressed by name (see ColumnIndex(string) and the name-keyed TryGet overloads).
public FileCsvDocument(
params string[]
columnNames
The column names. At least one is required.
)
ArgumentExceptionThrown when columnNames is null or empty.

Properties

ColumnCount

#Since v9.0
The number of columns in the document. Every row has exactly this many fields.
public int ColumnCount { get; }

HasHeader

#Since v9.0
True if the document has a header row of column names. See ColumnIndex(string).
public bool HasHeader { get; }

RowCount

#Since v9.0
The number of rows in the document.
public int RowCount { get; }

Indexers

this[]

#Since v9.0
Gets the value of a cell, addressed by column and row. Use TryGetString(int, int, string) for access that does not throw when the cell does not exist.
public string this[
column,
The zero-based column index (x).
row
The zero-based row index (y).
] { get; }
The value of the cell.
ArgumentOutOfRangeExceptionThrown when column or row is out of range.

Methods

Clear

#Since v9.0
Removes all rows from the document.
public void Clear()

ColumnIndex

#Since v9.0
Returns the zero-based index of the column with the given name (case-insensitive), or -1 if the document has no header or no column with that name. When names are duplicated, the first is returned.
public int ColumnIndex(
name
The column name to look up.
)
The column index, or -1.

GetEnumerator

#Since v9.0
Returns an enumerator that iterates over the committed rows of the document.
public IEnumerator<string[]> GetEnumerator()

GetRow

#Since v9.0
Returns the fields of a row.
public string[] GetRow(
row
The zero-based row index.
)
The fields of the row.
ArgumentOutOfRangeExceptionThrown when row is out of range.

Read

#Since v9.0
Reads a CSV file from disk.
public static FileCsvDocument Read(
path,
The path of the file to read.
hasHeader
When true, the first row is taken as the column-name header and is not counted as a data row.
)
A new document populated with the contents of the file.

Read

#Since v9.0
Reads a CSV file from disk. The file is assumed to have no header row.
public static FileCsvDocument Read(
path
The path of the file to read.
)
A new document populated with the contents of the file.

Read

#Since v9.0
Reads CSV content from a text reader.
public static FileCsvDocument Read(
reader,
The reader to read from.
hasHeader
When true, the first row is taken as the column-name header and is not counted as a data row.
)
A new document populated with the contents of the reader.

Read

#Since v9.0
Reads CSV content from a text reader. The content is assumed to have no header row.
public static FileCsvDocument Read(
reader
The reader to read from.
)
A new document populated with the contents of the reader.

Save

#Since v9.0
Writes the document to a file on disk using the specified encoding.
public void Save(
path,
The path of the file to write.
encoding
The character encoding to use, for example Encoding.ASCII or Encoding.UTF8. Note that Encoding.UTF8 emits a byte order mark; use new UTF8Encoding(false) to write UTF-8 without one.
)

Save

#Since v9.0
Writes the document to a file on disk, encoded as UTF-8 with a byte order mark. The mark lets spreadsheet applications (for example Excel on Windows and Mac) detect the encoding rather than falling back to the system code page, which garbles non-ASCII text such as Korean (RH-97173). Use Save(string, Encoding) with new UTF8Encoding(false) to write UTF-8 without a mark.
public void Save(
path
The path of the file to write.
)

Save

#Since v9.0
Writes the document to a text writer. Records are separated by CRLF, per RFC 4180. If the document has a header, it is written ahead of the data rows.
public void Save(
writer
The writer to write to.
)

Set

#Since v9.0
Sets the value of a cell to a boolean, written as "1" (true) or "0" (false).
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a cell to a color, stored as its 32-bit ARGB integer (Color.ToArgb()), so that the alpha channel round-trips.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a cell to a date and time, formatted with the specified .NET date/time format string and the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value,
The value to store.
format
A standard or custom date/time format string, for example "yyyy-MM-dd".
)

Set

#Since v9.0
Sets the value of a cell to a date and time, formatted as a round-trip ISO 8601 string (the "o" format) using the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a cell to a double-precision number, formatted with Localization.FormatNumber(double, LengthUnit, DistanceDisplayMode, int, bool). The unit system name is never appended to the field.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value,
The value to store.
units,
The length unit used to format the value.
DistanceDisplayMode
mode,
The distance display mode used to format the value.
precision
The number of digits of precision.
)

Set

#Since v9.0
Sets the value of a specific cell to a double-precision number, formatted with the specified .NET numeric format string and the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value,
The value to store.
format
A standard or custom numeric format string, for example "F2" or "0.###".
)

Set

#Since v9.0
Sets the value of a cell to a double-precision number, formatted with Localization.FormatNumber(double, UnitSystem, DistanceDisplayMode, int, bool). The unit system name is never appended to the field.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value,
The value to store.
units,
The unit system used to format the value.
DistanceDisplayMode
mode,
The distance display mode used to format the value.
precision
The number of digits of precision.
)

Set

#Since v9.0
Sets the value of a specific cell to a double-precision number, formatted with the general ("G") format specifier and the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a cell to a globally unique identifier, formatted with hyphens and no braces (the "D" format, for example "11f820ff-952a-4b0b-b10a-59f82c2eb1f4").
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a specific cell to a 32-bit integer, formatted using the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a specific cell to a 64-bit integer, formatted using the invariant culture.
public void Set(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The value to store.
)

Set

#Since v9.0
Sets the value of a cell, addressed by column and row. Rows are added as needed (any intervening rows are created and filled with empty fields), but the column count is fixed.
public void Set(
column,
The zero-based column index (x). Must be less than ColumnCount.
row,
The zero-based row index (y).
value
The value to store. A null value is stored as an empty field.
)
ArgumentOutOfRangeExceptionThrown when row is negative, or column is negative or not less than ColumnCount.

Set

#Since v9.0
Sets a row from a 3-D point, using the specified .NET numeric format string. This is only valid when ColumnCount is 3: the point's X, Y, and Z are written to columns 0, 1, and 2 with the invariant culture.
public void Set(
row,
The zero-based row index (y).
point,
The point to store.
format
A standard or custom numeric format string, for example "F2" or "0.###".
)
InvalidOperationExceptionThrown when ColumnCount is not 3.
ArgumentOutOfRangeExceptionThrown when row is negative.

Set

#Since v9.0
Sets a row from a 3-D point. This is only valid when ColumnCount is 3: the point's X, Y, and Z are written to columns 0, 1, and 2 with the general ("G") format specifier and the invariant culture.
public void Set(
row,
The zero-based row index (y).
point
The point to store.
)
InvalidOperationExceptionThrown when ColumnCount is not 3.
ArgumentOutOfRangeExceptionThrown when row is negative.

SetRow

#Since v9.0
Sets the fields of a row, addressed by index, growing the document as needed (any intervening rows are created and filled with empty fields). This is the row-level counterpart to GetRow(int). The number of fields must equal ColumnCount. A null field is stored as an empty field.
public void SetRow(
row,
The zero-based row index (y).
values
The fields of the row, one per column.
)
ArgumentOutOfRangeExceptionThrown when row is negative.
ArgumentNullExceptionThrown when values is null.
ArgumentExceptionThrown when the number of fields does not equal ColumnCount.

SetRow

#Since v9.0
Sets the fields of a row, addressed by index, growing the document as needed (any intervening rows are created and filled with empty fields). This is the row-level counterpart to GetRow(int). The number of fields must equal ColumnCount. A null field is stored as an empty field.
public void SetRow(
row,
The zero-based row index (y).
params string[]
values
The fields of the row, one per column.
)
ArgumentOutOfRangeExceptionThrown when row is negative.
ArgumentNullExceptionThrown when values is null.
ArgumentExceptionThrown when the number of fields does not equal ColumnCount.
Explicit

IEnumerable.GetEnumerator

#Since v9.0
IEnumerator IEnumerable.GetEnumerator()

ToString

#Since v9.0
Returns the full CSV content of the document as a string.
public override string ToString()
Object.ToString

TryGetBool

#Since v9.0
Retrieves the value of a cell as a boolean. Recognizes "true"/"false", "yes"/"no", and "1"/"0" (case-insensitive, surrounding whitespace ignored).
public bool TryGetBool(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out bool
value
The parsed value, or false if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetBool

#Since v9.0
Retrieves the value of a cell as a boolean, addressing the column by header name.
public bool TryGetBool(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out bool
value
The parsed value, or false if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetColor

#Since v9.0
Retrieves the value of a cell as a color from its 32-bit ARGB integer (Color.FromArgb(int)), as written by Set(int, int, Color).
public bool TryGetColor(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out Color
value
The parsed value, or Color.Empty if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetColor

#Since v9.0
Retrieves the value of a cell as a color, addressing the column by header name.
public bool TryGetColor(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out Color
value
The parsed value, or Color.Empty if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetDateTime

#Since v9.0
Retrieves the value of a cell as a date and time, parsed with the invariant culture and DateTimeStyles.RoundtripKind (so ISO 8601 values, including those written by Set(int, int, DateTime), round-trip).
public bool TryGetDateTime(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
value
The parsed value, or DateTime.MinValue if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetDateTime

#Since v9.0
Retrieves the value of a cell as a date and time, addressing the column by header name.
public bool TryGetDateTime(
column,
The header name of the column.
row,
The zero-based data-row index (y).
value
The parsed value, or DateTime.MinValue if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetDouble

#Since v9.0
Retrieves the value of a cell as a double-precision number. The cell is evaluated with RhinoMath.TryParseNumber(string, double), so command-line math expressions (for example "1/2") are supported.
public bool TryGetDouble(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out double
value
The parsed value, or 0.0 if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetDouble

#Since v9.0
Retrieves the value of a cell as a double-precision number, addressing the column by header name.
public bool TryGetDouble(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out double
value
The parsed value, or 0.0 if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetGuid

#Since v9.0
Retrieves the value of a cell as a globally unique identifier. Accepts any of the formats understood by Guid.TryParse(string, Guid) (with or without hyphens or braces).
public bool TryGetGuid(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out Guid
value
The parsed value, or Guid.Empty if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetGuid

#Since v9.0
Retrieves the value of a cell as a globally unique identifier, addressing the column by header name.
public bool TryGetGuid(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out Guid
value
The parsed value, or Guid.Empty if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetInt

#Since v9.0
Retrieves the value of a cell as a 32-bit integer, parsed using the invariant culture.
public bool TryGetInt(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out int
value
The parsed value, or 0 if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetInt

#Since v9.0
Retrieves the value of a cell as a 32-bit integer, addressing the column by header name.
public bool TryGetInt(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out int
value
The parsed value, or 0 if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetLong

#Since v9.0
Retrieves the value of a cell as a 64-bit integer, parsed using the invariant culture.
public bool TryGetLong(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out long
value
The parsed value, or 0 if the cell does not exist or cannot be parsed.
)
true if the cell exists and was parsed; otherwise false.

TryGetLong

#Since v9.0
Retrieves the value of a cell as a 64-bit integer, addressing the column by header name.
public bool TryGetLong(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out long
value
The parsed value, or 0 if the column or cell does not exist or cannot be parsed.
)
true if the column and cell exist and were parsed; otherwise false.

TryGetPoint

#Since v9.0
Retrieves a row as a 3-D point. This succeeds only when ColumnCount is 3: the row's three fields are joined and passed to Point3d.TryParse(string, Point3d).
public bool TryGetPoint(
row,
The zero-based row index (y).
out Point3d
point
The parsed point, or Point3d.Unset if the row could not be parsed.
)
true if the document has 3 columns and the row parsed as a point; otherwise false.

TryGetString

#Since v9.0
Retrieves the value of a cell as a string.
public bool TryGetString(
column,
The zero-based column index (x).
row,
The zero-based row index (y).
out string
value
The value of the cell, or null if the cell does not exist.
)
true if the cell exists; otherwise false.

TryGetString

#Since v9.0
Retrieves the value of a cell as a string, addressing the column by header name.
public bool TryGetString(
column,
The header name of the column.
row,
The zero-based data-row index (y).
out string
value
The value of the cell, or null if the column or cell does not exist.
)
true if the column and cell exist; otherwise false.