Csv C Library Reference

Csv

Create/Dispose

HCkCsv CkCsv_Create(void);

Creates an instance of the CkCsv object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkCsv_Dispose(HCkCsv handle);

Objects created by calling CkCsv_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

BOOL CkCsv_getCrlf(HCkCsv handle);
void CkCsv_putCrlf(HCkCsv handle, BOOL newVal);

If true, then CRLF line endings are used when saving the CSV to a file or to a string (i.e. for the methods SaveFile, SaveFile2, SaveToString). If false then bare LF line-endings are used.

void CkCsv_getDelimiter(HCkCsv handle, HCkString retval);
void CkCsv_putDelimiter(HCkCsv handle, const char *newVal);

The character that separates fields in a record. It is a comma by default. If the Delimiter property is not explicitly set, the CSV component will detect the delimiter when loading a CSV. (Semicolons are typically used in locales where the comma is used as a decimal point.)

BOOL CkCsv_getHasColumnNames(HCkCsv handle);
void CkCsv_putHasColumnNames(HCkCsv handle, BOOL newVal);

Set to true prior to loading a CSV if the 1st record contains column names. This allows the CSV parser to correctly load the column names and not treat them as data.

void CkCsv_getLastErrorHtml(HCkCsv handle, HCkString retval);

To be documented soon.Error information in HTML format for the last method called.

void CkCsv_getLastErrorText(HCkCsv handle, HCkString retval);

Error information in plain-text format for the last method called.

void CkCsv_getLastErrorXml(HCkCsv handle, HCkString retval);

Error information in XML format for the last method called.

int CkCsv_getNumColumns(HCkCsv handle);

The number of columns in the 1st row, which may be the row containing column names if HasColumnNames is true.

int CkCsv_getNumRows(HCkCsv handle);

The number of data rows. If the CSV has column names, the 1st row is not included in the count. Also, empty lines containing only whitespace characters that follow the last non-empty row are not included.

BOOL CkCsv_getUtf8(HCkCsv handle);
void CkCsv_putUtf8(HCkCsv handle, BOOL newVal);

To be documented soon...

C "Methods"

BOOL CkCsv_GetCell(HCkCsv handle, int row, int col, HCkString outStr);

Returns the contents of the cell at row, col. Indexing begins at 0. (The topmost/leftmost cell is at 0,0)

BOOL CkCsv_GetColumnName(HCkCsv handle, int index, HCkString outStr);

Returns the name of the Nth column.

int CkCsv_GetIndex(HCkCsv handle, const char *columnName);

Returns the column index for a given column.

int CkCsv_GetNumCols(HCkCsv handle, int row);

Returns the number of columns for a specific row. If the row is larger than the number of rows in the CSV, a zero is returned.

BOOL CkCsv_LoadFile(HCkCsv handle, const char *filename);

Loads a CSV from a file. It is assumed that the CSV file contains ANSI characters.

Returns TRUE for success, FALSE for failure.

BOOL CkCsv_LoadFile2(HCkCsv handle, const char *filename, const char *charset);

Loads a CSV from a file. The charset specifies the character encoding of the CSV file. A list of supported character encodings may be found on this page: Supported Charsets.

Returns TRUE for success, FALSE for failure.

BOOL CkCsv_LoadFromString(HCkCsv handle, const char *csvData);

Loads a CSV document from an in-memory string variable.

Returns TRUE for success, FALSE for failure.

BOOL CkCsv_SaveFile(HCkCsv handle, const char *filename);

Saves a CSV to a file. The output file is written using the ANSI character encoding.

Returns TRUE for success, FALSE for failure.

BOOL CkCsv_SaveFile2(HCkCsv handle, const char *filename, const char *charset);

Saves a CSV to a file. The charset specifies the character encoding to use for the CSV file. The text data is converted to this charset when saving. A list of supported character encodings may be found on this page: Supported Charsets.

Returns TRUE for success, FALSE for failure.

BOOL CkCsv_SaveLastError(HCkCsv handle, const char *filename);

Saves the last error information to an XML formatted file.

BOOL CkCsv_SaveToString(HCkCsv handle, HCkString outStr);

Writes the entire CSV document to a string variable.

BOOL CkCsv_SetCell(HCkCsv handle, int row, int col, const char *content);

Sets the contents for a single cell in the CSV. The content may include any characters including CRLF's, double-quotes, and the delimiter character. The Save* methods automatically double-quote fields with special chars when saving. The Load* methods automatically parse double-quoted and/or escaped fields correctly when loading.

BOOL CkCsv_SetColumnName(HCkCsv handle, int index, const char *columnName);

Sets the name of the Nth column. The first column is at index 0. This method would only return false if an invalid index is passed (such as a negative number).

Returns TRUE for success, FALSE for failure.

const char *CkCsv_delimiter(HCkCsv handle);

The character that separates fields in a record. It is a comma by default. If the Delimiter property is not explicitly set, the CSV component will detect the delimiter when loading a CSV. (Semicolons are typically used in locales where the comma is used as a decimal point.)

const char *CkCsv_getCell(HCkCsv handle, int row, int col);

Returns the contents of the cell at row, col. Indexing begins at 0. (The topmost/leftmost cell is at 0,0)

const char *CkCsv_getColumnName(HCkCsv handle, int index);

Returns the name of the Nth column.

const char *CkCsv_lastErrorHtml(HCkCsv handle);

Error information in HTML format for the last method called.

const char *CkCsv_lastErrorText(HCkCsv handle);

Error information in plain-text format for the last method called.

const char *CkCsv_lastErrorXml(HCkCsv handle);

Error information in XML format for the last method called.

const char *CkCsv_saveToString(HCkCsv handle);

Writes the entire CSV document to a string variable.