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.
Parameters:
| columnCount (int) | The number of columns. Must be greater than zero. |
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).Parameters:
| columnNames (params string[]) | The column names. At least one is required. |
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.
Parameters:
| name (string) | The column name to look up. |
Returns: The column index, or -1.
Returns an enumerator that iterates over the committed rows of the document.
Returns the fields of a row.
Parameters:
| row (int) | The zero-based row index. |
Returns: The fields of the row.
Exceptions:
| ArgumentOutOfRangeException | Thrown when row is out of range. |
Reads a CSV file from disk.
Reads a CSV file from disk. The file is assumed to have no header row.
Parameters:
| path (string) | The path of the file to read. |
Returns: A new document populated with the contents of the file.
Reads CSV content from a text reader.
Parameters:
| reader (TextReader) | The reader to read from. |
| hasHeader (bool) | 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.
Parameters:
| reader (TextReader) | The reader to read from. |
Returns: A new document populated with the contents of the reader.
Writes the document to a file on disk using the specified encoding.
Parameters:
| path (string) | The path of the file to write. |
| encoding (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.Parameters:
| path (string) | The path of the file to write. |
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.
Parameters:
| writer (TextWriter) | The writer to write to. |
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.
public void Set(int column, int row, double value, LengthUnit units, DistanceDisplayMode mode, int precision)
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.
Parameters:
| column (int) | The zero-based column index (x). |
| row (int) | The zero-based row index (y). |
| value (double) | The value to store. |
| units (LengthUnit) | The length unit used to format the value. |
| mode (DistanceDisplayMode) | The distance display mode used to format the value. |
| precision (int) | 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.
public void Set(int column, int row, double value, UnitSystem units, DistanceDisplayMode mode, int precision)
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.
Parameters:
| column (int) | The zero-based column index (x). |
| row (int) | The zero-based row index (y). |
| value (double) | The value to store. |
| units (UnitSystem) | The unit system used to format the value. |
| mode (DistanceDisplayMode) | The distance display mode used to format the value. |
| precision (int) | 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.
Parameters:
| column (int) | The zero-based column index (x). Must be less than ColumnCount. |
| row (int) | The zero-based row index (y). |
| value (string) | 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.
Parameters:
| row (int) | The zero-based row index (y). |
| point (Point3d) | The point to store. |
| format (string) | A standard or custom numeric format string, for example "F2" or "0.###". |
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.
Parameters:
| row (int) | The zero-based row index (y). |
| values (IEnumerable<string>) | 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.
Parameters:
| row (int) | The zero-based row index (y). |
| values (params string[]) | 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. |
Returns the full CSV content of the document as a string.
Overrides: Object.ToString
Retrieves the value of a cell as a boolean. Recognizes "true"/"false", "yes"/"no", and "1"/"0" (case-insensitive, surrounding whitespace ignored).
Retrieves the value of a cell as a boolean, addressing the column by header name.
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).
Parameters:
| column (int) | The zero-based column index (x). |
| row (int) | The zero-based row index (y). |
| value (out Color) | 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.
Parameters:
| column (string) | The header name of the column. |
| row (int) | The zero-based data-row index (y). |
| value (out Color) | 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).
Parameters:
| column (int) | The zero-based column index (x). |
| row (int) | The zero-based row index (y). |
| value (out DateTime) | 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.
Parameters:
| column (string) | The header name of the column. |
| row (int) | The zero-based data-row index (y). |
| value (out DateTime) | 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.
Retrieves the value of a cell as a double-precision number, addressing the column by header name.
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).
Parameters:
| column (int) | The zero-based column index (x). |
| row (int) | The zero-based row index (y). |
| value (out Guid) | 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.
Parameters:
| column (string) | The header name of the column. |
| row (int) | The zero-based data-row index (y). |
| value (out Guid) | 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.
Retrieves the value of a cell as a 32-bit integer, addressing the column by header name.
Retrieves the value of a cell as a 64-bit integer, parsed using the invariant culture.
Retrieves the value of a cell as a 64-bit integer, addressing the column by header name.
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).
Parameters:
| row (int) | The zero-based row index (y). |
| point (out Point3d) | 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.
Retrieves the value of a cell as a string, addressing the column by header name.