Result Set

Functions
int	kdbc_next (kdbc_result *rs)
	Advance to the next row.
int	kdbc_col_count (kdbc_result *rs)
	Get the number of columns in the result set.
const char *	kdbc_col_name (kdbc_result *rs, int col)
	Get a column name by index.
const char *	kdbc_col_label (kdbc_result *rs, int col)
	Get a column label (alias) by index.
kdbc_type	kdbc_col_type (kdbc_result *rs, int col)
	Get the type of a column value in the current row.
int	kdbc_is_null (kdbc_result *rs, int col)
	Check if a column value is NULL.
int64_t	kdbc_get_long (kdbc_result *rs, int col)
	Get a column value as a 64-bit integer.
double	kdbc_get_double (kdbc_result *rs, int col)
	Get a column value as a double.
const char *	kdbc_get_string (kdbc_result *rs, int col)
	Get a column value as a UTF-8 string.
const void *	kdbc_get_blob (kdbc_result *rs, int col, size_t *out_len)
	Get a column value as a binary blob.
int	kdbc_get_timestamp (kdbc_result *rs, int col, int *year, int *month, int *day, int *hour, int *minute, int *second, int *usec)
	Get a column value as a timestamp (date + time).
int	kdbc_get_date (kdbc_result *rs, int col, int *year, int *month, int *day)
	Get a column value as a date (no time component).
int	kdbc_get_time (kdbc_result *rs, int col, int *hour, int *minute, int *second, int *usec)
	Get a column value as a time (no date component).
void	kdbc_result_close (kdbc_result *rs)
	Close a result set and free resources.

Detailed Description

Navigate rows and retrieve column values from query results.

All column indices are 1-indexed. String and blob pointers are valid until the next kdbc_next() call or kdbc_result_close().

kdbc_result *rs = kdbc_execute_query(conn, "SELECT id, name FROM users");
while (kdbc_next(rs) == 1) {
    int64_t id = kdbc_get_long(rs, 1);
    const char *name = kdbc_get_string(rs, 2);
    if (!kdbc_is_null(rs, 2))
        printf("%lld: %s\n", (long long)id, name);
}
kdbc_result_close(rs);

Function Documentation

kdbc_next()

int kdbc_next

(

kdbc_result *

rs

)

Advance to the next row.

Parameters

rs	A result set.

Returns

1 if a row is available, 0 if no more rows, KDBC_ERROR on failure.

kdbc_col_count()

int kdbc_col_count

(

kdbc_result *

rs

)

Get the number of columns in the result set.

Parameters

rs	A result set.

Returns

Column count.

kdbc_col_name()

const char * kdbc_col_name	(	kdbc_result *	rs,
		int	col )

Get a column name by index.

Parameters

rs	A result set.
col	Column index (1-indexed).

Returns

Column name, or NULL if index is invalid.

kdbc_col_label()

const char * kdbc_col_label	(	kdbc_result *	rs,
		int	col )

Get a column label (alias) by index.

Falls back to the column name if no alias was specified in the query.

Parameters

rs	A result set.
col	Column index (1-indexed).

Returns

Column label, or NULL if index is invalid.

kdbc_col_type()

kdbc_type kdbc_col_type	(	kdbc_result *	rs,
		int	col )

Get the type of a column value in the current row.

Lets a caller retrieve a value with the getter that matches the column instead of guessing from the text form — a text column holding digits is KDBC_TYPE_STRING, not a number, and a binary column is KDBC_TYPE_BLOB rather than whatever its bytes look like as text.

Databases that type values per row rather than per column (SQLite) report the type of the value in the current row, so call this after kdbc_next.

Parameters

rs	A result set.
col	Column index (1-indexed).

Returns

The column type, or KDBC_TYPE_STRING when the index is invalid or the driver cannot report one.

kdbc_is_null()

int kdbc_is_null	(	kdbc_result *	rs,
		int	col )

Check if a column value is NULL.

Call this after a kdbc_get_* function to distinguish NULL from zero or empty string.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

1 if the value is NULL, 0 otherwise.

kdbc_get_long()

int64_t kdbc_get_long	(	kdbc_result *	rs,
		int	col )

Get a column value as a 64-bit integer.

For type mismatches, reasonable conversions are attempted. Check kdbc_is_null() to distinguish NULL from 0.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The integer value (0 if NULL or conversion failed).

kdbc_get_double()

double kdbc_get_double	(	kdbc_result *	rs,
		int	col )

Get a column value as a double.

Check kdbc_is_null() to distinguish NULL from 0.0.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The double value (0.0 if NULL or conversion failed).

kdbc_get_string()

const char * kdbc_get_string	(	kdbc_result *	rs,
		int	col )

Get a column value as a UTF-8 string.

The returned pointer is valid until the next kdbc_next() call or kdbc_result_close().

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The string value, or NULL if the column is NULL.

kdbc_get_blob()

const void * kdbc_get_blob	(	kdbc_result *	rs,
		int	col,
		size_t *	out_len )

Get a column value as a binary blob.

The returned pointer is valid until the next kdbc_next() call or kdbc_result_close().

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
out_len	Output: blob size in bytes.

Returns

Pointer to the blob data, or NULL if the column is NULL.

kdbc_get_timestamp()

int kdbc_get_timestamp	(	kdbc_result *	rs,
		int	col,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	minute,
		int *	second,
		int *	usec )

Get a column value as a timestamp (date + time).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
year	Output: year.
month	Output: month (1–12).
day	Output: day (1–31).
hour	Output: hour (0–23).
minute	Output: minute (0–59).
second	Output: second (0–59).
usec	Output: microseconds (0–999999).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_get_date()

int kdbc_get_date	(	kdbc_result *	rs,
		int	col,
		int *	year,
		int *	month,
		int *	day )

Get a column value as a date (no time component).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
year	Output: year.
month	Output: month (1–12).
day	Output: day (1–31).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_get_time()

int kdbc_get_time	(	kdbc_result *	rs,
		int	col,
		int *	hour,
		int *	minute,
		int *	second,
		int *	usec )

Get a column value as a time (no date component).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
hour	Output: hour (0–23).
minute	Output: minute (0–59).
second	Output: second (0–59).
usec	Output: microseconds (0–999999).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_result_close()

void kdbc_result_close

(

kdbc_result *

rs

)

Close a result set and free resources.

Safe to call with NULL (no-op).

Parameters

rs	The result set to close, or NULL.