Map

Functions
kv_error_t	kv_map_put_int (kv_map_t *map, const char *name, kv_int_t value)
	Sets an int value for the named field. More...
kv_error_t	kv_map_put_long (kv_map_t *map, const char *name, kv_long_t value)
	Sets a long value for the named field. More...
kv_error_t	kv_map_put_float (kv_map_t *map, const char *name, kv_float_t value)
	Sets a float value for the named field. More...
kv_error_t	kv_map_put_double (kv_map_t *map, const char *name, kv_double_t value)
	Sets a double value for the named field. More...
kv_error_t	kv_map_put_boolean (kv_map_t *map, const char *name, kv_boolean_t value)
	Sets a boolean value for the named field. More...
kv_error_t	kv_map_put_string (kv_map_t *map, const char *name, const char *value)
	Sets a string value for the named field. More...
kv_error_t	kv_map_put_bytes (kv_map_t *map, 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_map_put_bytes_copy (kv_map_t *map, 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_map_put_array (kv_map_t *map, const char *name)
	Creates a nested array for the named field. More...
kv_array_t *	kv_map_put_sized_array (kv_map_t *map, const char *name, kv_int_t size)
	Creates a nested array with initial size for the named field. More...
kv_map_t *	kv_map_put_map (kv_map_t *map, const char *name)
	Creates a nested map for the named field. More...
kv_record_t *	kv_map_put_record (kv_map_t *map, const char *name)
	Creates a nested record for the named field. More...
kv_error_t	kv_map_put_null (kv_map_t *map, const char *name)
	Sets a NULL value for the named field. More...
const char **	kv_map_get_keys (kv_map_t *map, kv_int_t *num)
	Returns all keys in the map. More...
kv_error_t	kv_map_get_int (const kv_map_t *map, const char *name, kv_int_t *value)
	Returns an int for a named field in a map. More...
kv_error_t	kv_map_get_long (const kv_map_t *map, const char *name, kv_long_t *value)
	Returns a long for a named field in a map. More...
kv_error_t	kv_map_get_float (const kv_map_t *map, const char *name, kv_float_t *value)
	Returns a float for a named field in a map. More...
kv_error_t	kv_map_get_double (const kv_map_t *map, const char *name, kv_double_t *value)
	Returns a double for a named field in a map. More...
kv_error_t	kv_map_get_boolean (const kv_map_t *map, const char *name, kv_boolean_t *value)
	Returns a boolean for a named field in a map. More...
kv_error_t	kv_map_get_string (const kv_map_t *map, const char *name, const char **value)
	Returns a string for a named field in a map. More...
kv_error_t	kv_map_get_bytes (const kv_map_t *map, const char *name, const unsigned char **bytes, kv_int_t *size)
	Returns a bytes value for a named field in a map. More...
kv_error_t	kv_map_get_array (const kv_map_t *map, const char *name, kv_array_t **value)
	Returns a nested array for a named field in a map. More...
kv_error_t	kv_map_get_map (const kv_map_t *map, const char *name, kv_map_t **value)
	Returns a nested map for a named field in a map. More...
kv_error_t	kv_map_get_record (const kv_map_t *map, const char *name, kv_record_t **value)
	Returns a nested record for a named field in a map. More...
kv_field_t *	kv_map_get_field (const kv_map_t *map, const char *name)
	Returns a field value for a named field in a map. More...

Detailed Description

Function Documentation

kv_error_t kv_map_get_array	(	const kv_map_t *	map,
		const char *	name,
		kv_array_t **	value
	)

Returns a nested array for a named field in a map.

Parameters

[in]	map	The map handle.
[in]	name	The field name.
[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_map_get_boolean	(	const kv_map_t *	map,
		const char *	name,
		kv_boolean_t *	value
	)

Returns a boolean for a named field in a map.

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]	map	The map handle.
[in]	name	The field name.
[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_map_get_bytes	(	const kv_map_t *	map,
		const char *	name,
		const unsigned char **	bytes,
		kv_int_t *	size
	)

Returns a bytes value for a named field in a map.

Parameters

[in]	map	The map handle.
[in]	name	The field name.
[out]	bytes	The output byte array.
[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_map_get_double	(	const kv_map_t *	map,
		const char *	name,
		kv_double_t *	value
	)

Returns a double for a named field in a map.

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]	map	The map handle.
[in]	name	The field name.
[out]	value	A pointer to the output value.

Returns

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

kv_field_t* kv_map_get_field	(	const kv_map_t *	map,
		const char *	name
	)

Returns a field value for a named field in a map.

Parameters

[in]	map	The map handle.
[in]	name	The field name.

Returns

The output field, or NULL if it does not exist.

kv_error_t kv_map_get_float	(	const kv_map_t *	map,
		const char *	name,
		kv_float_t *	value
	)

Returns a float for a named field in a map.

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]	map	The map handle.
[in]	name	The field name.
[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_map_get_int	(	const kv_map_t *	map,
		const char *	name,
		kv_int_t *	value
	)

Returns an int for a named field in a map.

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]	map	The map handle.
[in]	name	The field name.
[out]	value	A pointer to the output value.

Returns

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

const char** kv_map_get_keys	(	kv_map_t *	map,
		kv_int_t *	num
	)

Returns all keys in the map.

Note

The returned keys array is owned by the map handle. It is valid until the map is modified or released, and will be released implicitly when the map handle is released.

Parameters

[in]	map	The map handle.
[out]	num	The size of the returned key array.

Returns

An array of map key strings on success, and NULL if the map value is empty or on failure.

kv_error_t kv_map_get_long	(	const kv_map_t *	map,
		const char *	name,
		kv_long_t *	value
	)

Returns a long for a named field in a map.

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]	map	The map handle.
[in]	name	The field name.
[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_map_get_map	(	const kv_map_t *	map,
		const char *	name,
		kv_map_t **	value
	)

Returns a nested map for a named field in a map.

Parameters

[in]	map	The map handle.
[in]	name	The field name.
[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_map_get_record	(	const kv_map_t *	map,
		const char *	name,
		kv_record_t **	value
	)

Returns a nested record for a named field in a map.

Parameters

[in]	map	The map handle.
[in]	name	The field name.
[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_map_get_string	(	const kv_map_t *	map,
		const char *	name,
		const char **	value
	)

Returns a string for a named field in a map.

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]	map	The map 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_array_t* kv_map_put_array	(	kv_map_t *	map,
		const char *	name
	)

Creates a nested array for the named field.

Parameters

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

Returns

An empty array value handle on success, otherwise NULL.

kv_error_t kv_map_put_boolean	(	kv_map_t *	map,
		const char *	name,
		kv_boolean_t	value
	)

Sets a boolean value for the named field.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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

kv_error_t kv_map_put_bytes	(	kv_map_t *	map,
		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_map_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 map structure in this function is released.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	bytes	The byte array value 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_map_put_bytes_copy	(	kv_map_t *	map,
		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_map_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]	map	The map handle.
[in]	name	The name of field to be set.
[in]	bytes	The byte array value 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_map_put_double	(	kv_map_t *	map,
		const char *	name,
		kv_double_t	value
	)

Sets a double value for the named field.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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

kv_error_t kv_map_put_float	(	kv_map_t *	map,
		const char *	name,
		kv_float_t	value
	)

Sets a float value for the named field.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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

kv_error_t kv_map_put_int	(	kv_map_t *	map,
		const char *	name,
		kv_int_t	value
	)

Sets an int value for the named field.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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

kv_error_t kv_map_put_long	(	kv_map_t *	map,
		const char *	name,
		kv_long_t	value
	)

Sets a long value for the named field.

Parameters

[in]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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

kv_map_t* kv_map_put_map	(	kv_map_t *	map,
		const char *	name
	)

Creates a nested map for the named field.

Parameters

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

Returns

An empty map handle on success, otherwise NULL.

kv_error_t kv_map_put_null	(	kv_map_t *	map,
		const char *	name
	)

Sets a NULL value for the named field.

Note

This function can only be used on the map value that are part of an index key, it will fail if use on a regular map value.

Parameters

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

Returns

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

kv_record_t* kv_map_put_record	(	kv_map_t *	map,
		const char *	name
	)

Creates a nested record for the named field.

Parameters

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

Returns

An empty record handle on success, otherwise NULL.

kv_array_t* kv_map_put_sized_array	(	kv_map_t *	map,
		const char *	name,
		kv_int_t	size
	)

Creates a nested array with initial size for the named field.

Parameters

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

Returns

An empty array value handle, initialized based on the specified size, on success, otherwise NULL.

kv_error_t kv_map_put_string	(	kv_map_t *	map,
		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]	map	The map handle.
[in]	name	The name of field to be set.
[in]	value	The value to be set.

Returns

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