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
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.
Exceptions:
| ArgumentOutOfRangeException | Thrown when columnCount is less than one. |
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).Exceptions:
| ArgumentException | Thrown when columnNames is null or empty. |
Properties
The number of columns in the document. Every row has exactly this many fields.
True if the document has a header row of column names. See ColumnIndex(string).
The column names, or null if the document has no header. RowCount counts only the data rows; the header is not one of them.
Indexers
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.
Returns: The value of the cell.
Exceptions:
| ArgumentOutOfRangeException | Thrown when column or row is out of range. |
Methods
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.
Returns: The column index, or -1.
Returns an enumerator that iterates over the committed rows of the document.
Returns the fields of a row.
Returns: The fields of the row.
Exceptions:
| ArgumentOutOfRangeException | Thrown when row is out of range. |
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.
Returns: A new document populated with the contents of the file.
Reads a CSV file from disk. The file is assumed to have no header row.
Returns: A new document populated with the contents of the file.
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.
Returns: A new document populated with the contents of the reader.
Reads CSV content from a text reader. The content is assumed to have no header row.
Returns: A new document populated with the contents of the reader.
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.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.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.
Sets the value of a cell to a boolean, written as "1" (true) or "0" (false).
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.
Sets the value of a cell to a date and time, formatted with the specified .NET date/time format string and the invariant culture.
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.
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.
Sets the value of a specific cell to a double-precision number, formatted with the specified .NET numeric format string and the invariant culture.
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.
Sets the value of a specific cell to a double-precision number, formatted with the general ("G") format specifier and the invariant culture.
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").
Sets the value of a specific cell to a 32-bit integer, formatted using the invariant culture.
Sets the value of a specific cell to a 64-bit integer, formatted using the invariant culture.
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.
Exceptions:
| ArgumentOutOfRangeException | Thrown when row is negative, or column is negative or not less than ColumnCount. |
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.
Exceptions:
| InvalidOperationException | Thrown when ColumnCount is not 3. |
| ArgumentOutOfRangeException | Thrown when row is negative. |
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.
Exceptions:
| InvalidOperationException | Thrown when ColumnCount is not 3. |
| ArgumentOutOfRangeException | Thrown when row is negative. |
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.
Exceptions:
| ArgumentOutOfRangeException | Thrown when row is negative. |
| ArgumentNullException | Thrown when values is null. |
| ArgumentException | Thrown when the number of fields does not equal ColumnCount. |
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.
Exceptions:
| ArgumentOutOfRangeException | Thrown when row is negative. |
| ArgumentNullException | Thrown when values is null. |
| ArgumentException | Thrown when the number of fields does not equal ColumnCount. |
Retrieves the value of a cell as a boolean. Recognizes "true"/"false", "yes"/"no", and "1"/"0" (case-insensitive, surrounding whitespace ignored).
Returns: true if the cell exists and was parsed; otherwise false.
Retrieves the value of a cell as a boolean, addressing the column by header name.
Returns: true if the column and cell exist and were parsed; otherwise false.
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.
Returns: true if the cell exists and was parsed; otherwise false.
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.
Returns: true if the column and cell exist and were parsed; otherwise false.
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).
out DateTime
value
The parsed value, or DateTime.MinValue if the cell does not exist or cannot be parsed.
Returns: true if the cell exists and was parsed; otherwise false.
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).
out DateTime
value
The parsed value, or DateTime.MinValue if the column or cell does not exist or cannot be parsed.
Returns: true if the column and cell exist and were parsed; otherwise false.
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.
Returns: true if the cell exists and was parsed; otherwise false.
Retrieves the value of a cell as a double-precision number, addressing the column by header name.
Returns: true if the column and cell exist and were parsed; otherwise false.
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.
Returns: true if the cell exists and was parsed; otherwise false.
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.
Returns: true if the column and cell exist and were parsed; otherwise false.
Retrieves the value of a cell as a 32-bit integer, parsed using the invariant culture.
Returns: true if the cell exists and was parsed; otherwise false.
Retrieves the value of a cell as a 32-bit integer, addressing the column by header name.
Returns: true if the column and cell exist and were parsed; otherwise false.
Retrieves the value of a cell as a 64-bit integer, parsed using the invariant culture.
Returns: true if the cell exists and was parsed; otherwise false.
Retrieves the value of a cell as a 64-bit integer, addressing the column by header name.
Returns: true if the column and cell exist and were parsed; otherwise false.
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.
Returns: true if the document has 3 columns and the row parsed as a point; otherwise false.
Retrieves the value of a cell as a string.
Returns: true if the cell exists; otherwise false.
Retrieves the value of a cell as a string, addressing the column by header name.
Returns: true if the column and cell exist; otherwise false.