Csv Rust Reference Documentation

Csv

Current Version: 11.6.1

Chilkat.Csv

Read, edit, sort, and write CSV or delimiter-separated data in memory.

Chilkat.Csv is a practical in-memory table class for working with CSV and other delimiter-separated text formats. It can load CSV data from files or strings, access cells by row/column index or column name, manage header rows, insert and delete rows or columns, sort records, search for matching rows, and write the result back using configurable delimiters, quoting rules, character encodings, and line endings.

In-memory CSV table

Load CSV data, modify cells, add rows, delete rows or columns, and write the updated table back to a file or string.

Header and named columns

Use a header row to access fields by column name instead of only by numeric column index.

Cell and row operations

Read and update individual cells, insert columns, remove data, find matching rows, and sort the table as needed.

Delimiter control

Work with comma-separated data or other delimiter-separated formats by configuring the delimiter character.

Quoting and output formatting

Control quoted fields, forced quoting, output line endings, explicit character encodings, and UTF-8 BOM emission.

Excel worksheet loading

Load worksheet data from an opened .xlsx ZIP container when CSV-style access to spreadsheet content is needed.

Common pattern: Load CSV data, specify whether the first row is a header, access or modify cells by index or column name, perform any row, column, search, or sort operations, then save the table using the delimiter, charset, quoting, BOM, and line-ending settings required by the target system.

For an extended overview, see Csv Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Csv;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let csv = Csv::new();
// ... the native object is freed when `csv` goes out of scope.
pub fn new() -> Csv

Creates the underlying native Chilkat object (Csv also implements Default). Every method takes &self, so the object never needs to be declared mut. A Csv is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Csv

The native object is freed when the Csv is dropped — when it goes out of scope, or explicitly with drop(csv). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Csv>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match csv.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

AutoTrim
// read/write
pub fn auto_trim(&self) -> bool
pub fn set_auto_trim(&self, value: bool)

Controls whether leading and trailing whitespace is removed from values returned by GetCell and GetCellByName.

  • When true, surrounding whitespace such as spaces and tabs is removed from returned cell values.
  • When false, returned cell values are not trimmed. This is the default.

This property does not modify the cell contents stored in the CSV and does not change the text written by the save methods. It also does not trim the names returned by GetColumnName.

top
Crlf
// read/write
pub fn crlf(&self) -> bool
pub fn set_crlf(&self, value: bool)

Controls the line endings used by SaveFile, SaveFile2, SaveToString, and SaveToSb.

  • When true, records are terminated with CRLF. This is the default.
  • When false, records are terminated with LF.

The original line-ending style of loaded data is not preserved. The selected line ending is used for all output records, including the final record.

top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
Delimiter
// read/write
pub fn delimiter(&self) -> String
pub fn set_delimiter(&self, value: &str)

Specifies the single character used to separate fields within each CSV record. The default value is a comma (,).

Although this property has a string type, only the first character of a non-empty value is used. Assigning an empty string does not clear or reset the current delimiter.

If the delimiter has not been explicitly set, Chilkat detects it while loading the first CSV data and updates this property with the detected character. The detection may examine more than the first record. Once selected or detected, the delimiter remains in effect for subsequent loads performed by the same object. To load data that uses a different delimiter, explicitly set this property before loading or use a new Csv object.

A semicolon (;) is commonly used in locales where a comma is used as the decimal separator.

Creating a new CSV: Set this property before adding rows or columns when a delimiter other than comma is required.

Vertical-bar delimiter: If this property is explicitly set to |, and EnableQuotes has not been explicitly set, EnableQuotes defaults to false.

top
EnableQuotes
// read/write
pub fn enable_quotes(&self) -> bool
pub fn set_enable_quotes(&self, value: bool)
Introduced in version 9.5.0.71

Controls whether double quotation marks have their standard CSV meaning when reading and writing data. The default value is true.

When true, a quoted field is treated as one field even when it contains the delimiter, CR, or LF. A double quotation mark inside a quoted field is represented by two consecutive double quotation marks. Fields created by the application are quoted automatically when required.

Chilkat retains whether a field loaded from CSV text was quoted, so quotation marks that were not strictly required may remain when the CSV is saved again.

When false, quotation marks are ordinary characters and do not protect delimiters or line endings. Do not disable quoting when field values can contain the delimiter, quotation marks, CR, or LF, because such values cannot be represented or round-tripped reliably as ordinary delimited text.

More Information and Examples
CSV Enable Quotes
top
EscapeBackslash
// read/write
pub fn escape_backslash(&self) -> bool
pub fn set_escape_backslash(&self, value: bool)
Introduced in version 9.5.0.44

Controls whether a backslash causes the following character to be treated literally while parsing CSV data. The default value is false.

When true, examples include:

  • \, represents a literal delimiter character.
  • \\ represents one backslash.
  • \" represents a literal double quotation mark.

This is not C-style escape decoding. For example, \n, \r, and \t produce the literal characters n, r, and t; they do not produce a line feed, carriage return, or tab.

Normal CSV quoting is still used when output fields contain delimiters or line endings.

top
HasColumnNames
// read/write
pub fn has_column_names(&self) -> bool
pub fn set_has_column_names(&self, value: bool)

Indicates whether the first record is a column-name row rather than a data row. The default value is false.

Set this property to true before loading CSV data when the first record contains column names. Chilkat then stores the first record as the column names and excludes it from NumRows and zero-based data-row indexing.

Changing this property to true after data has already been loaded does not reinterpret the first data row as column names. Calling SetColumnName automatically changes this property to true.

Methods that address a column by name require this property to be true and require the requested name to exist.

More Information and Examples
CSV Load from String
top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
NumColumns
// read-only
pub fn num_columns(&self) -> i32

The number of columns in the first row of the CSV. When HasColumnNames is true, this is the number of column names in the header row.

CSV rows may contain different numbers of fields. Therefore, this property is not necessarily the maximum number of columns found in any row. Use GetNumCols to obtain the number of columns in a particular data row.

top
NumRows
// read-only
pub fn num_rows(&self) -> i32

The number of data rows in the CSV.

  • When HasColumnNames is true, the column-name row is not included.
  • Interior blank rows are included.
  • Empty or whitespace-only rows following the last non-empty row are not included.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.88

Provides optional keywords for uncommon CSV-processing requirements. The default value is an empty string, and this property should normally remain empty. To enable more than one option, use a comma-separated list.

The following keywords are defined:

  • QuotedCells (v9.5.0.96) — Encloses every data cell in double quotation marks when writing the CSV.
  • QuotedColumnNames (v9.5.0.96) — Encloses every column name in double quotation marks when writing the CSV.
  • EMIT_BOM (v9.5.0.93) — Writes a UTF-8 byte order mark when saving a UTF-8 encoded CSV file.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top
XlsxDateFormat
// read/write
pub fn xlsx_date_format(&self) -> String
pub fn set_xlsx_date_format(&self, value: &str)
Introduced in version 11.3.0

Specifies the date format used when converting Excel date cells from an .xlsx worksheet to CSV text.

The default value is mm-dd-yy. Other formats include d/m/yyyy, m/d/yyyy, and similar Excel-style date-format patterns.

top

Methods

DeleteColumn
pub fn delete_column(&self, index: i32) -> Result<()>

Deletes the column at zero-based index index. The deletion is applied to the column-name row, when present, and to each data row that contains that column.

index must not be negative. For predictable deletion, index should be less than NumColumns.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Delete Column
top
DeleteColumnByName
pub fn delete_column_by_name(&self, column_name: &str) -> Result<()>

Deletes the column named by column_name. This method requires HasColumnNames to be true.

Column-name matching is case-sensitive. Surrounding whitespace in a loaded column name is not part of its lookup name. Column names should be unique to avoid ambiguous lookup and deletion behavior.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Delete Column by Name
top
DeleteRow
pub fn delete_row(&self, index: i32) -> Result<()>

Deletes the data row at zero-based index index. The first data row is at index 0, regardless of whether a column-name row exists.

index must be between 0 and NumRows - 1.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Delete Row
top
GetCell
pub fn get_cell(&self, row: i32, col: i32) -> Result<String>

Returns the contents of the cell at data row row and column col.

Row and column indexes are zero-based. The upper-left data cell is at row 0, column 0. When HasColumnNames is true, the header row is not included in the row index.

  • If row is negative or beyond the available data rows, Err is returned and LastMethodSuccess is false.
  • If col is negative, Err is returned and LastMethodSuccess is false.
  • If row is valid but col is beyond the number of fields in that row, an empty string is returned and LastMethodSuccess is true.

When AutoTrim is true, surrounding whitespace is removed from the returned value without changing the stored cell content.

Returns Err(chilkat::Error) on failure.

More Information and Examples
CSV Get Contents of Cell
top
GetCellByName
pub fn get_cell_by_name(&self, row_index: i32, column_name: &str) -> Result<String>

Returns the contents of the cell at data row row_index in the column named by column_name. Row indexing begins at 0 and excludes the header row.

This method requires HasColumnNames to be true. Column-name matching is case-sensitive. Surrounding whitespace is removed from column names for lookup purposes, so column_name should contain the trimmed name. If duplicate lookup names exist, the last matching column is used.

If the row or column name is invalid, Err is returned and LastMethodSuccess is false. When AutoTrim is true, surrounding whitespace is removed from the returned cell value.

Returns Err(chilkat::Error) on failure.

More Information and Examples
CSV Get Contents of Cell using Row Index and Column Name
top
GetColumnName
pub fn get_column_name(&self, index: i32) -> Result<String>

Returns the original, untrimmed name of the column at zero-based index index. The first column is at index 0.

Returns Err(chilkat::Error) on failure.

More Information and Examples
CSV Get Column Names
top
GetIndex
pub fn get_index(&self, column_name: &str) -> i32

Returns the zero-based index of the column named by column_name, or -1 if no matching column exists.

This method requires HasColumnNames to be true. Matching is case-sensitive. Surrounding whitespace is removed from loaded column names for lookup purposes, so column_name should contain the trimmed name. If duplicate lookup names exist, the index of the last matching column is returned.

top
GetNumCols
pub fn get_num_cols(&self, row: i32) -> i32

Returns the number of fields in the data row at zero-based index row. This is useful for CSV data containing rows of different lengths.

Returns 0 if row is negative or beyond the available data rows.

top
InsertColumn
pub fn insert_column(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.89

Inserts one empty field into each existing row and, when present, into the column-name row. index is a zero-based insertion position.

  • If index is within a row, the empty field is inserted before that position.
  • If index is at or beyond the end of a row, one empty field is appended to that row.
  • Rows are not padded to a common width, so ragged rows remain ragged.
  • Calling this method on an object with no rows and no column-name row has no effect.

index must not be negative.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Insert Column
top
LoadFile
pub fn load_file(&self, path: &str) -> Result<()>

Clears the current contents and loads CSV data from the file specified by path. Set HasColumnNames, Delimiter, EnableQuotes, and other parsing options before calling this method.

On Windows, the file is decoded using the current Windows ANSI code page. Use LoadFile2 when the character encoding must be specified explicitly.

The existing CSV contents are cleared before the file is opened. Therefore, a failure such as a missing file does not preserve the previously loaded data.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadFile2
pub fn load_file2(&self, filename: &str, charset: &str) -> Result<()>

Clears the current contents and loads CSV data from the file specified by filename. charset specifies the character encoding used by the file.

Set HasColumnNames, Delimiter, EnableQuotes, and other parsing options before calling this method.

See Supported Charsets for the encoding names recognized by Chilkat.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Read Japanese utf-8 CSV File
top
LoadFromString
pub fn load_from_string(&self, csv_data: &str) -> Result<()>

Clears the current contents and loads the CSV text contained in csv_data. Set HasColumnNames, Delimiter, EnableQuotes, and other parsing options before calling this method.

Passing an empty string successfully clears the CSV. The parser is permissive; for example, an unterminated quoted field extends through the end of csv_data rather than necessarily causing the load to fail.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Load from String
top
RowMatches
pub fn row_matches(&self, row_index: i32, match_pattern: &str, case_sensitive: bool) -> bool

Compares the complete data row at zero-based index row_index with the wildcard pattern in match_pattern. The row is compared as one delimited record using the current Delimiter; the pattern may therefore include or span field separators.

  • The asterisk character (*) may appear any number of times and matches zero or more characters.
  • When case_sensitive is true, matching is case-sensitive.
  • When case_sensitive is false, matching is case-insensitive.
  • AutoTrim does not alter the row used for matching.

Returns true when the row matches match_pattern. Returns false when it does not match or when row_index is outside the available data rows.

top
SaveFile
pub fn save_file(&self, path: &str) -> Result<()>

Writes the entire CSV to the file specified by path.

On Windows, the text is encoded using the current Windows ANSI code page. Use SaveFile2 when the output encoding must be specified explicitly.

Record endings are controlled by Crlf, and the final record is also followed by the selected line ending.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SaveFile2
pub fn save_file2(&self, filename: &str, charset: &str) -> Result<()>

Writes the entire CSV to the file specified by filename. charset specifies the output character encoding, and Chilkat converts the CSV text to that encoding while saving.

Record endings are controlled by Crlf, and the final record is also followed by the selected line ending.

See Supported Charsets for the encoding names recognized by Chilkat.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Write utf-8 CSV Compatible with Excel
top
SaveToSb
pub fn save_to_sb(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.93

Clears sb and writes the entire CSV document into it.

Record endings are controlled by Crlf. sb contains a line ending after the final record.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SaveToString
pub fn save_to_string(&self) -> Result<String>

Returns the entire CSV document as a string.

Record endings are controlled by Crlf. The returned string includes a line ending after the final record. The line-ending style originally loaded into the object is not preserved.

Returns Err(chilkat::Error) on failure.

top
SetCell
pub fn set_cell(&self, row: i32, col: i32, content: &str) -> Result<()>

Sets the cell at zero-based data row row and column col to content.

The CSV grows as needed. If row is beyond the current last row, intervening rows are created as empty rows. Within the target row, intervening columns are created as empty cells. Other rows are not padded, so the resulting CSV may contain rows with different numbers of fields. Passing NumRows as row appends a new data row.

content may contain delimiters, quotation marks, CR, and LF when EnableQuotes is true; Chilkat applies the necessary CSV quoting when the data is saved. row and col must not be negative.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Set Cell by Index or NameCSV Append New Row
top
SetCellByName
pub fn set_cell_by_name(&self, row_index: i32, column_name: &str, content_str: &str) -> Result<()>

Sets the cell at zero-based data row row_index in the column named by column_name to content_str.

This method requires HasColumnNames to be true and requires column_name to match an existing column name. Matching is case-sensitive and uses the trimmed lookup form of the stored column name. A missing column is not created.

The data-row collection grows as needed. content_str may contain delimiters, quotation marks, CR, and LF when EnableQuotes is true.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Set Cell by Index or Name
top
SetColumnName
pub fn set_column_name(&self, index: i32, column_name: &str) -> Result<()>

Sets the name of the column at zero-based index index to column_name. The first column is at index 0.

Calling this method automatically sets HasColumnNames to true. It can therefore be used on an empty object to create the column-name row. index must not be negative.

For reliable name-based access, use unique column names without surrounding whitespace.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
CSV Set Column Name
top
SortByColumn
pub fn sort_by_column(&self, column_name: &str, ascending: bool, case_sensitive: bool) -> Result<()>

Sorts the data rows using the values in the column named by column_name. The column-name row is not moved.

  • When ascending is true, rows are sorted in ascending order.
  • When ascending is false, rows are sorted in descending order.
  • When case_sensitive is true, comparisons are case-sensitive.
  • When case_sensitive is false, comparisons are case-insensitive.

Values are compared as strings, not as numbers or dates. For example, ascending order places 10 before 2. Empty or missing sort cells appear first in ascending order and last in descending order. The sort is not stable, so rows having equal sort values may change relative order.

This method requires HasColumnNames to be true and column_name to name an existing column.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SortByColumnIndex
pub fn sort_by_column_index(&self, index: i32, ascending: bool, case_sensitive: bool) -> Result<()>
Introduced in version 9.5.0.83

Sorts the data rows using the values in the column at zero-based index index. The column-name row, when present, is not moved.

  • When ascending is true, rows are sorted in ascending order.
  • When ascending is false, rows are sorted in descending order.
  • When case_sensitive is true, comparisons are case-sensitive.
  • When case_sensitive is false, comparisons are case-insensitive.

Values are compared as strings, not as numbers or dates. Empty and missing sort cells are treated as empty strings. They appear first in ascending order and last in descending order. The sort is not stable, so rows having equal sort values may change relative order.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
XlsxGetSheets
pub fn xlsx_get_sheets(&self, xlsx: &Zip, sheet_names: &StringTable) -> Result<()>
Introduced in version 11.3.0

Gets the worksheet names contained in an Excel .xlsx workbook.

  • xlsx is a Zip object containing the already-opened .xlsx file.
  • sheet_names receives the worksheet names.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
XLSX Get Sheet Names
top
XlsxLoadSheet
pub fn xlsx_load_sheet(&self, zip: &Zip, sheet_name: &str) -> Result<()>
Introduced in version 11.3.0

Loads a worksheet from an Excel .xlsx workbook into this CSV object.

  • zip is a Zip object containing the already-opened .xlsx file.
  • sheet_name is the worksheet name.
  • Pass an empty string in sheet_name to load the workbook's default worksheet.

The XlsxDateFormat property controls the text format used for Excel date cells.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
XLSX Spreadsheet in AI QueryXLSX Convert Sheet to CSV
top