Row

Functions
kv_row_t *	kv_create_row ()
	Creates and initializes a row structure. More...
kv_error_t	kv_row_put_int (kv_row_t *row, const char *name, kv_int_t value)
	Sets an int value for the named field. More...
kv_error_t	kv_row_put_long (kv_row_t *row, const char *name, kv_long_t value)
	Sets a long value for the named field. More...
kv_error_t	kv_row_put_float (kv_row_t *row, const char *name, kv_float_t value)
	Sets a float value for the named field. More...
kv_error_t	kv_row_put_double (kv_row_t *row, const char *name, kv_double_t value)
	Sets a double value for the named field. More...
kv_error_t	kv_row_put_boolean (kv_row_t *row, const char *name, kv_boolean_t value)
	Sets a boolean value for the named field. More...
kv_error_t	kv_row_put_string (kv_row_t *row, const char *name, const char *value)
	Sets a string value for the named field. More...
kv_error_t	kv_row_put_bytes (kv_row_t *row, const char *name, const unsigned char *bytes, kv_int_t size)
	Sets a byte array value for the named field. More...
kv_error_t	kv_row_put_bytes_copy (kv_row_t *row, const char *name, const unsigned char *bytes, kv_int_t size)
	Sets a byte array value for the named field. More...
kv_array_t *	kv_row_put_array (kv_row_t *row, const char *name)
	Creates an array for the named field. More...
kv_array_t *	kv_row_put_sized_array (kv_row_t *row, const char *name, kv_int_t size)
	Creates an array with initial size for the named field. More...
kv_map_t *	kv_row_put_map (kv_row_t *row, const char *name)
	Creates a map for the named field. More...
kv_record_t *	kv_row_put_record (kv_row_t *row, const char *name)
	Creates a record for the named field. More...
kv_error_t	kv_row_put_null (kv_row_t *row, const char *name)
	Sets a NULL value for the named field. More...
kv_field_t **	kv_row_get_fields (const kv_row_t *row, kv_int_t *num)
	Returns all field values of the given row handle. More...
kv_field_t *	kv_row_get_field (const kv_row_t *row, const char *name)
	Returns the value of the named field in a row. More...
const char *	kv_field_get_name (const kv_field_t *field)
	Returns the name of a field value. More...
kv_field_type_enum	kv_field_get_type (const kv_field_t *field)
	Returns the type of a field value. More...
kv_boolean_t	kv_field_is_null (const kv_field_t *field)
	Returns whether or not a field value is a NULL value. More...
kv_error_t	kv_field_as_int (const kv_field_t *field, kv_int_t *value)
	Returns an int value for the specified field value. More...
kv_error_t	kv_field_as_long (const kv_field_t *field, kv_long_t *value)
	Returns a long value for the specified field value. More...
kv_error_t	kv_field_as_float (const kv_field_t *field, kv_float_t *value)
	Returns a float value for the specified field value. More...
kv_error_t	kv_field_as_double (const kv_field_t *field, kv_double_t *value)
	Returns a double value for the specified field value. More...
kv_error_t	kv_field_as_boolean (const kv_field_t *field, kv_boolean_t *value)
	Returns a boolean value for the specified field value. More...
kv_error_t	kv_field_as_string (const kv_field_t *field, const char **value)
	Returns a string value for the specified field value. More...
kv_error_t	kv_field_as_bytes (const kv_field_t *field, unsigned char **bytes, kv_int_t *size)
	Returns a byte value for the specified field value. More...
kv_error_t	kv_field_as_array (const kv_field_t *field, kv_array_t **value)
	Returns an array value handle for the specified field value. More...
kv_error_t	kv_field_as_map (const kv_field_t *field, kv_map_t **value)
	Returns a map value handle for the specified field value. More...
kv_error_t	kv_field_as_record (const kv_field_t *field, kv_record_t **value)
	Returns a record value handle for the specified field value. More...
kv_error_t	kv_row_get_int (const kv_row_t *row, const char *name, kv_int_t *value)
	Returns an int value for the named field in a row. More...
kv_error_t	kv_row_get_long (const kv_row_t *row, const char *name, kv_long_t *value)
	Returns a long value for the named field in a row. More...
kv_error_t	kv_row_get_float (const kv_row_t *row, const char *name, kv_float_t *value)
	Returns a float value for the named field in a row. More...
kv_error_t	kv_row_get_double (const kv_row_t *row, const char *name, kv_double_t *value)
	Returns a double value for the named field in a row. More...
kv_error_t	kv_row_get_boolean (const kv_row_t *row, const char *name, kv_boolean_t *value)
	Returns a boolean value for the named field in a row. More...
kv_error_t	kv_row_get_string (const kv_row_t *row, const char *name, const char **value)
	Returns a string value for the named field in a row. More...
kv_error_t	kv_row_get_bytes (const kv_row_t *row, const char *name, const unsigned char **bytes, kv_int_t *size)
	Returns the byte value of the named field in a row. More...
kv_error_t	kv_row_get_array (const kv_row_t *row, const char *name, kv_array_t **value)
	Returns the array value handle for the named field in a row. More...
kv_error_t	kv_row_get_map (const kv_row_t *row, const char *name, kv_map_t **value)
	Returns the map value handle for the named field in a row. More...
kv_error_t	kv_row_get_record (const kv_row_t *row, const char *name, kv_record_t **value)
	Returns the record value handle for the named field in a row. More...
kv_error_t	kv_row_set_ttl_of_hours (kv_row_t *row, kv_long_t hours)
	Sets time to live (TTL) using a period of hours for the row. If not set, the table default value will be used. If no expiration time is desired, hours=0 should be used. More...
kv_error_t	kv_row_set_ttl_of_days (kv_row_t *row, kv_long_t days)
	Sets time to live (TTL) using a period of days for the row. If not set, the table default value will be used. If no expiration time is desired, days=0 should be used. More...
kv_error_t	kv_row_set_use_table_ttl (kv_row_t *row, kv_boolean_t flag)
	Sets whether to use table default TTL during update. If the flag is KV_TRUE and the operation updates a record, the the record's expiration time will be updated to table default TTL, otherwise the the record's expiration time will not be changed. By default, this property is KV_FALSE. More...
kv_long_t	kv_row_get_ttl_value (const kv_row_t *row)
	Gets the numeric duration associated with the row. -1 indicates that the row's TTL is not set. More...
kv_ttl_timeunit_enum	kv_row_get_ttl_timeunit (const kv_row_t *row)
	Gets the kv_ttl_timeunit_enum associated with the row. -1 indicates that the row's TTL is not set. More...
kv_boolean_t	kv_row_get_use_table_ttl (const kv_row_t *row)
	Gets whether to use table default TTL during update. Returns KV_TRUE if the absolute expiration time will be updated to table default TTL during update operations, otherwise return KV_FALSE. More...
kv_error_t	kv_copy_row (const kv_row_t *from, kv_row_t **to)
	Copies a row structure. More...
void	kv_release_row (kv_row_t **rowp)
	Releases the resources used by the row structure. More...

Detailed Description

Function Documentation

kv_error_t kv_copy_row	(	const kv_row_t *	from,
		kv_row_t **	to
	)

Copies a row structure.

Parameters

[in]	from	The row structure to be copied.
[in]	to	The output row structure, it should be released using kv_release_row().

kv_row_t* kv_create_row

(

)

Creates and initializes a row structure.

Returns

The returned row structure that must be freed using kv_release_row().

kv_error_t kv_field_as_array	(	const kv_field_t *	field,
		kv_array_t **	value
	)

Returns an array value handle for the specified field value.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output array handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_boolean	(	const kv_field_t *	field,
		kv_boolean_t *	value
	)

Returns a boolean value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_bytes	(	const kv_field_t *	field,
		unsigned char **	bytes,
		kv_int_t *	size
	)

Returns a byte value for the specified field value.

Parameters

[in]	field	The field value handle.
[out]	bytes	The output bytes. The returned data is owned by the field value handle and must not be freed by the caller.
[out]	size	The size of bytes.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_double	(	const kv_field_t *	field,
		kv_double_t *	value
	)

Returns a double value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_float	(	const kv_field_t *	field,
		kv_float_t *	value
	)

Returns a float value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_int	(	const kv_field_t *	field,
		kv_int_t *	value
	)

Returns an int value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_long	(	const kv_field_t *	field,
		kv_long_t *	value
	)

Returns a long value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_map	(	const kv_field_t *	field,
		kv_map_t **	value
	)

Returns a map value handle for the specified field value.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output map handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_record	(	const kv_field_t *	field,
		kv_record_t **	value
	)

Returns a record value handle for the specified field value.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output record handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_field_as_string	(	const kv_field_t *	field,
		const char **	value
	)

Returns a string value for the specified field value.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	field	The field value handle.
[out]	value	A pointer to the output value. The returned data is owned by the field value handle and must not be freed by the caller.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

const char* kv_field_get_name

(

const kv_field_t *

field

)

Returns the name of a field value.

Parameters

[in]

field

The field value handle.

Returns

The name of the field.

kv_field_type_enum kv_field_get_type

(

const kv_field_t *

field

)

Returns the type of a field value.

Parameters

[in]

field

The field value handle.

Returns

The type of field.

kv_boolean_t kv_field_is_null

(

const kv_field_t *

field

)

Returns whether or not a field value is a NULL value.

Parameters

[in]

field

The field value handle.

Returns

KV_TRUE if it is a NULL value, KV_FALSE otherwise.

void kv_release_row

(

kv_row_t **

rowp

)

Releases the resources used by the row structure.

Parameters

[in]

rowp

A pointer to the row handle to release

kv_error_t kv_row_get_array	(	const kv_row_t *	row,
		const char *	name,
		kv_array_t **	value
	)

Returns the array value handle for the named field in a row.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output array handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_boolean	(	const kv_row_t *	row,
		const char *	name,
		kv_boolean_t *	value
	)

Returns a boolean value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_bytes	(	const kv_row_t *	row,
		const char *	name,
		const unsigned char **	bytes,
		kv_int_t *	size
	)

Returns the byte value of the named field in a row.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	bytes	The output byte array. The returned data is owned by the row and must not be freed by the caller.
[out]	size	The output size of bytes.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_double	(	const kv_row_t *	row,
		const char *	name,
		kv_double_t *	value
	)

Returns a double value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_field_t* kv_row_get_field	(	const kv_row_t *	row,
		const char *	name
	)

Returns the value of the named field in a row.

Note

The returned data is owned by the row handle. Its data is valid until the row is modified or released, and it will released implicitly when the row is released.

Parameters

[in]	row	The row handle.
[in]	name	The name of field.

Returns

The field value handle if the field exists, otherwise NULL.

kv_field_t** kv_row_get_fields	(	const kv_row_t *	row,
		kv_int_t *	num
	)

Returns all field values of the given row handle.

Note

The returned handle is owned by the row handle. Its data is valid until the row is modified or released, and it will released implicitly when the row is released.

Parameters

[in]	row	The row handle.
[out]	num	The number of fields returned.

Returns

A list of fields.

kv_error_t kv_row_get_float	(	const kv_row_t *	row,
		const char *	name,
		kv_float_t *	value
	)

Returns a float value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_int	(	const kv_row_t *	row,
		const char *	name,
		kv_int_t *	value
	)

Returns an int value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_long	(	const kv_row_t *	row,
		const char *	name,
		kv_long_t *	value
	)

Returns a long value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output value.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_map	(	const kv_row_t *	row,
		const char *	name,
		kv_map_t **	value
	)

Returns the map value handle for the named field in a row.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output map handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_record	(	const kv_row_t *	row,
		const char *	name,
		kv_record_t **	value
	)

Returns the record value handle for the named field in a row.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	The output record handle.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_get_string	(	const kv_row_t *	row,
		const char *	name,
		const char **	value
	)

Returns a string value for the named field in a row.

Note

Performs an implicit cast and returns an error code if the field cannot be cast to the desired type without loss of information.

Parameters

[in]	row	The row handle.
[in]	name	The field name.
[out]	value	A pointer to the output UTF-8 encoded string.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_ttl_timeunit_enum kv_row_get_ttl_timeunit

(

const kv_row_t *

row

)

Gets the kv_ttl_timeunit_enum associated with the row. -1 indicates that the row's TTL is not set.

Parameters

[in]

row

The row handle.

Returns

The kv_ttl_timeunit_enum associated with the row, or an error code (a negative number) if the row is NULL.

kv_long_t kv_row_get_ttl_value

(

const kv_row_t *

row

)

Gets the numeric duration associated with the row. -1 indicates that the row's TTL is not set.

Parameters

[in]

row

The row handle.

Returns

The numeric duration value associated with the row, or an error code (a negative number) if the row is NULL.

kv_boolean_t kv_row_get_use_table_ttl

(

const kv_row_t *

row

)

Gets whether to use table default TTL during update. Returns KV_TRUE if the absolute expiration time will be updated to table default TTL during update operations, otherwise return KV_FALSE.

Parameters

[in]

row

The row handle.

Returns

A kv_boolean_t value indicating whether the update operation will update an existing record's expiration time to table default TTL, or KV_FALSE if row is NULL.

kv_array_t* kv_row_put_array	(	kv_row_t *	row,
		const char *	name
	)

Creates an array for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.

Returns

An empty array value handle on success, otherwise NULL.

kv_error_t kv_row_put_boolean	(	kv_row_t *	row,
		const char *	name,
		kv_boolean_t	value
	)

Sets a boolean value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The boolean value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_bytes	(	kv_row_t *	row,
		const char *	name,
		const unsigned char *	bytes,
		kv_int_t	size
	)

Sets a byte array value for the named field.

This function differs from kv_row_put_bytes_copy() in that it does not copy the contents of the bytes passed to the function. Therefore, the bytes should not be released or modified until the row structure in this function is released.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	bytes	The byte array to be set.
[in]	size	The size of bytes.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_bytes_copy	(	kv_row_t *	row,
		const char *	name,
		const unsigned char *	bytes,
		kv_int_t	size
	)

Sets a byte array value for the named field.

This function differs from kv_row_put_bytes() in that it copies the contents of the bytes passed to the function, so that the buffer can be released, or modified and then reused in whatever way is required by the application.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	bytes	The byte array to be set.
[in]	size	The size of bytes.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_double	(	kv_row_t *	row,
		const char *	name,
		kv_double_t	value
	)

Sets a double value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The double value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_float	(	kv_row_t *	row,
		const char *	name,
		kv_float_t	value
	)

Sets a float value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The float value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_int	(	kv_row_t *	row,
		const char *	name,
		kv_int_t	value
	)

Sets an int value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The int value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_put_long	(	kv_row_t *	row,
		const char *	name,
		kv_long_t	value
	)

Sets a long value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The long value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_map_t* kv_row_put_map	(	kv_row_t *	row,
		const char *	name
	)

Creates a map for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.

Returns

An empty map value handle on success, otherwise NULL.

kv_error_t kv_row_put_null	(	kv_row_t *	row,
		const char *	name
	)

Sets a NULL value for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_record_t* kv_row_put_record	(	kv_row_t *	row,
		const char *	name
	)

Creates a record for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.

Returns

An empty record value handle on success, otherwise NULL.

kv_array_t* kv_row_put_sized_array	(	kv_row_t *	row,
		const char *	name,
		kv_int_t	size
	)

Creates an array with initial size for the named field.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	size	The initial size of the array.

Returns

An empty array value handle, sized appropriately, on success, otherwise NULL.

kv_error_t kv_row_put_string	(	kv_row_t *	row,
		const char *	name,
		const char *	value
	)

Sets a string value for the named field.

Note

The string must be a valid UTF-8 encoded string.

Parameters

[in]	row	The row handle.
[in]	name	The name of the field to be set.
[in]	value	The string value to be set.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_set_ttl_of_days	(	kv_row_t *	row,
		kv_long_t	days
	)

Sets time to live (TTL) using a period of days for the row. If not set, the table default value will be used. If no expiration time is desired, days=0 should be used.

Parameters

[in]	row	The row handle.
[in]	days	The number of days in the duration, must be a non-negative long, zero indicates that the row should not expire.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_set_ttl_of_hours	(	kv_row_t *	row,
		kv_long_t	hours
	)

Sets time to live (TTL) using a period of hours for the row. If not set, the table default value will be used. If no expiration time is desired, hours=0 should be used.

Parameters

[in]	row	The row handle.
[in]	hours	The number of hours in the duration, must be a non-negative long, zero indicates that the row should not expire.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_row_set_use_table_ttl	(	kv_row_t *	row,
		kv_boolean_t	flag
	)

Sets whether to use table default TTL during update. If the flag is KV_TRUE and the operation updates a record, the the record's expiration time will be updated to table default TTL, otherwise the the record's expiration time will not be changed. By default, this property is KV_FALSE.

Parameters

[in]	row	The row handle.
[in]	flag	Set to KV_TRUE if attempt to update the row's TTL to table default TTL.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.