Csv Pascal Reference Documentation
Csv
Current Version: 11.5.0
Chilkat.Csv
Load CSV data, modify cells, add rows, delete rows or columns, and write
the updated table back to a file or string.
Use a header row to access fields by column name instead of only by
numeric column index.
Read and update individual cells, insert columns, remove data, find
matching rows, and sort the table as needed.
Work with comma-separated data or other delimiter-separated formats by
configuring the delimiter character.
Control quoted fields, forced quoting, output line endings, explicit
character encodings, and UTF-8 BOM emission.
Load worksheet data from an opened
For an extended overview, see
Csv Class Overview.
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
Header and named columns
Cell and row operations
Delimiter control
Quoting and output formatting
Excel worksheet loading
.xlsx ZIP container when
CSV-style access to spreadsheet content is needed.
Create / Free
uses
Chilkat.Csv;
var
obj: TCsv;
begin
obj := TCsv.Create;
try
if not obj.IsValid then
raise Exception.Create('Failed to create a TCsv instance.');
// ... use obj ...
finally
obj.Free;
end;
end;
Allocates the underlying CkCsv object and returns a new TCsv instance. Simply adding Chilkat.Csv to the unit's uses clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check obj.IsValid after calling Create; it is False if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed).
Every TCsv created by calling Create should eventually be released by calling .Free (inherited from TObject). The destructor automatically disposes the underlying CkCsv handle. A native (unmanaged) memory leak occurs if the object is never freed.
Properties
AutoTrim
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.
Crlf
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.
topDebugLogFilePath
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.
Delimiter
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.
EnableQuotes
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.
EscapeBackslash
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.
topHasColumnNames
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.
LastErrorHtml
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.
topLastErrorText
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.
LastErrorXml
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.
topLastMethodSuccess
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.
NumColumns
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.
NumRows
The number of data rows in the CSV.
- When
HasColumnNamesisTrue, 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.
UncommonOptions
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.
VerboseLogging
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.
Version
XlsxDateFormat
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.
Methods
DeleteColumn
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 True for success, False for failure.
DeleteColumnByName
Deletes the column named by columnName. 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 True for success, False for failure.
DeleteRow
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 True for success, False for failure.
GetCell
col: Integer): 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
rowis negative or beyond the available data rows,nilis returned andLastMethodSuccessisFalse. - If
colis negative,nilis returned andLastMethodSuccessisFalse. - If
rowis valid butcolis beyond the number of fields in that row, an empty string is returned andLastMethodSuccessisTrue.
When AutoTrim is True, surrounding whitespace is removed from the
returned value without changing the stored cell content.
Returns True for success, False for failure.
GetCellByName
const columnName: string): string;
Returns the contents of the cell at data row rowIndex in the column named by columnName.
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 columnName should contain the trimmed name. If duplicate lookup
names exist, the last matching column is used.
If the row or column name is invalid, nil is returned and
LastMethodSuccess is False. When AutoTrim is True,
surrounding whitespace is removed from the returned cell value.
Returns True for success, False for failure.
GetColumnName
Returns the original, untrimmed name of the column at zero-based index index.
The first column is at index 0.
Returns True for success, False for failure.
GetIndex
Returns the zero-based index of the column named by columnName, 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 columnName should contain the trimmed name. If duplicate lookup
names exist, the index of the last matching column is returned.
GetNumCols
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.
InsertColumn
Inserts one empty field into each existing row and, when present, into the
column-name row. index is a zero-based insertion position.
- If
indexis within a row, the empty field is inserted before that position. - If
indexis 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 True for success, False for failure.
LoadFile
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 True for success, False for failure.
topLoadFile2
const charset: string): Boolean;
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 True for success, False for failure.
LoadFromString
Clears the current contents and loads the CSV text contained in csvData. 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 csvData
rather than necessarily causing the load to fail.
Returns True for success, False for failure.
RowMatches
const matchPattern: string;
caseSensitive: Boolean): Boolean;
Compares the complete data row at zero-based index rowIndex with the wildcard
pattern in matchPattern. 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
caseSensitiveisTrue, matching is case-sensitive. - When
caseSensitiveisFalse, matching is case-insensitive. AutoTrimdoes not alter the row used for matching.
Returns True when the row matches matchPattern. Returns False when it does not
match or when rowIndex is outside the available data rows.
SaveFile
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 True for success, False for failure.
topSaveFile2
const charset: string): Boolean;
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 True for success, False for failure.
SaveToSb
function SaveToSb(sb: TChilkatBase): Boolean;
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 True for success, False for failure.
topSaveToString
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 True for success, False for failure.
topSetCell
col: Integer;
const content: string): Boolean;
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 True for success, False for failure.
SetCellByName
const columnName: string;
const contentStr: string): Boolean;
Sets the cell at zero-based data row rowIndex in the column named by columnName to contentStr.
This method requires HasColumnNames to be True and requires columnName
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. contentStr may contain delimiters,
quotation marks, CR, and LF when EnableQuotes is True.
Returns True for success, False for failure.
SetColumnName
const columnName: string): Boolean;
Sets the name of the column at zero-based index index to columnName. 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 True for success, False for failure.
SortByColumn
ascending: Boolean;
caseSensitive: Boolean): Boolean;
Sorts the data rows using the values in the column named by columnName. The
column-name row is not moved.
- When
ascendingisTrue, rows are sorted in ascending order. - When
ascendingisFalse, rows are sorted in descending order. - When
caseSensitiveisTrue, comparisons are case-sensitive. - When
caseSensitiveisFalse, 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 columnName to name an
existing column.
Returns True for success, False for failure.
topSortByColumnIndex
ascending: Boolean;
caseSensitive: Boolean): Boolean;
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
ascendingisTrue, rows are sorted in ascending order. - When
ascendingisFalse, rows are sorted in descending order. - When
caseSensitiveisTrue, comparisons are case-sensitive. - When
caseSensitiveisFalse, 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 True for success, False for failure.
topXlsxGetSheets
// sheetNames is a TStringTable object.
function XlsxGetSheets(xlsx: TChilkatBase;
sheetNames: TChilkatBase): Boolean;
Gets the worksheet names contained in an Excel .xlsx workbook.
xlsxis aZipobject containing the already-opened.xlsxfile.sheetNamesreceives the worksheet names.
Returns True for success, False for failure.
XlsxLoadSheet
function XlsxLoadSheet(zip: TChilkatBase;
const sheetName: string): Boolean;
Loads a worksheet from an Excel .xlsx workbook into this CSV object.
zipis aZipobject containing the already-opened.xlsxfile.sheetNameis the worksheet name.- Pass an empty string in
sheetNameto load the workbook's default worksheet.
The XlsxDateFormat property controls the text format used for
Excel date cells.
Returns True for success, False for failure.