String map

Data Structures
struct	sg_strmap

Typedefs
typedef int(*	sg_strmap_iter_cb) (void *cls, struct sg_strmap *pair)
typedef int(*	sg_strmap_sort_cb) (void *cls, struct sg_strmap *pair_a, struct sg_strmap *pair_b)

Functions
const char *	sg_strmap_name (struct sg_strmap *pair)
const char *	sg_strmap_val (struct sg_strmap *pair)
int	sg_strmap_add (struct sg_strmap **map, const char *name, const char *val)
int	sg_strmap_set (struct sg_strmap **map, const char *name, const char *val)
int	sg_strmap_find (struct sg_strmap *map, const char *name, struct sg_strmap **pair)
const char *	sg_strmap_get (struct sg_strmap *map, const char *name)
int	sg_strmap_rm (struct sg_strmap **map, const char *name)
int	sg_strmap_iter (struct sg_strmap *map, sg_strmap_iter_cb cb, void *cls)
int	sg_strmap_sort (struct sg_strmap **map, sg_strmap_sort_cb cb, void *cls)
unsigned int	sg_strmap_count (struct sg_strmap *map)
int	sg_strmap_next (struct sg_strmap **next)
void	sg_strmap_cleanup (struct sg_strmap **map)

Detailed Description

String map handle and its related functions.

Typedef Documentation

sg_strmap_iter_cb

typedef int(* sg_strmap_iter_cb) (void *cls, struct sg_strmap *pair)

Callback signature used by sg_strmap_iter() to iterate pairs of strings.

Parameters

[out]	cls	User-defined closure.
[out]	pair	Current iterated pair.

Return values

0	Success.
E<ERROR>	User-defined error to stop pairs iteration.

sg_strmap_sort_cb

typedef int(* sg_strmap_sort_cb) (void *cls, struct sg_strmap *pair_a, struct sg_strmap *pair_b)

Callback signature used by sg_strmap_sort() to sort pairs of strings.

Parameters

[out]	cls	User-defined closure.
[out]	pair_a	Current left pair (A).
[out]	pair_b	Current right pair (B).

Return values

-1	A < B.
0	A == B.
1	A > B.

Function Documentation

sg_strmap_name()

const char * sg_strmap_name

(

struct sg_strmap *

pair

)

Returns a name from the pair.

Parameters

[in]

pair

Pair of name-value.

Returns

Name as a null-terminated string.

Return values

NULL	If the pair is null and set the errno to EINVAL.

Examples

example_strmap.c.

sg_strmap_val()

const char * sg_strmap_val

(

struct sg_strmap *

pair

)

Returns a value from the pair.

Parameters

[in]

pair

Pair of name-value.

Returns

Value as a null-terminated string.

Return values

NULL	If the pair is null and set the errno to EINVAL.

Examples

example_httpsrv_sse.c, and example_strmap.c.

sg_strmap_add()

int sg_strmap_add	(	struct sg_strmap **	map,
		const char *	name,
		const char *	val
	)

Adds a pair of name-value to the string map.

Parameters

[in,out]	map	Pairs map pointer to add a new pair.
[in]	name	Pair name.
[in]	val	Pair value.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.

Note

It cannot check if a name already exists in a pair added to the map, then the uniqueness must be managed by the application.

sg_strmap_set()

int sg_strmap_set	(	struct sg_strmap **	map,
		const char *	name,
		const char *	val
	)

Sets a pair of name-value to the string map.

Parameters

[in,out]	map	Pairs map pointer to set a new pair.
[in]	name	Pair name.
[in]	val	Pair value.

Return values

0	Success.
EINVAL	Invalid argument.
ENOMEM	Out of memory.

Note

If a name already exists in a pair previously added into the map, then the function replaces its value, otherwise it is added as a new pair.

Examples

example_httpsrv_sse.c, and example_strmap.c.

sg_strmap_find()

int sg_strmap_find	(	struct sg_strmap *	map,
		const char *	name,
		struct sg_strmap **	pair
	)

Finds a pair by name.

Parameters

[in]	map	Pairs map.
[in]	name	Name to find the pair.
[in,out]	pair	Pointer of the variable to store the found pair.

Return values

0	Success.
EINVAL	Invalid argument.
ENOENT	Pair not found.
ENOMEM	Out of memory.

Examples

example_httpsrv_sse.c, and example_strmap.c.

sg_strmap_get()

const char * sg_strmap_get	(	struct sg_strmap *	map,
		const char *	name
	)

Gets a pair by name and returns the value.

Parameters

[in]	map	Pairs map.
[in]	name	Name to get the pair.

Returns

Pair value as a null-terminated string.

Return values

NULL	If map or name is null or pair is not found.

Examples

example_httpcomp.c, example_httpcookie.c, example_httpreq_form.c, and example_httpuplds.c.

sg_strmap_rm()

int sg_strmap_rm	(	struct sg_strmap **	map,
		const char *	name
	)

Removes a pair by name.

Parameters

[in]	map	Pointer to the pairs map.
[in]	name	Name to find and then remove the pair.

Return values

0	Success.
EINVAL	Invalid argument.
ENOENT	Pair already removed.
ENOMEM	Out of memory.

sg_strmap_iter()

int sg_strmap_iter	(	struct sg_strmap *	map,
		sg_strmap_iter_cb	cb,
		void *	cls
	)

Iterates over pairs map.

Parameters

[in]	map	Pairs map.
[in]	cb	Callback to iterate the pairs.
[in,out]	cls	User-specified value.

Return values

0	Success.
EINVAL	Invalid argument.

Returns

Callback result when it is different from 0.

Examples

example_strmap.c.

sg_strmap_sort()

int sg_strmap_sort	(	struct sg_strmap **	map,
		sg_strmap_sort_cb	cb,
		void *	cls
	)

Sorts the pairs map.

Parameters

[in,out]	map	Pointer to the pairs map.
[in]	cb	Callback to sort the pairs.
[in,out]	cls	User-specified value.

Return values

0	Success.
EINVAL	Invalid argument.

Examples

example_strmap.c.

sg_strmap_count()

unsigned int sg_strmap_count

(

struct sg_strmap *

map

)

Counts the total pairs in the map.

Parameters

[in]

map

Pairs map.

Returns

Total of pairs.

Return values

0	If the list is empty or null.

Examples

example_httpuplds.c.

sg_strmap_next()

int sg_strmap_next

(

struct sg_strmap **

next

)

Returns the next pair in the map.

Parameters

[in,out]

next

Pointer to the next pair.

Return values

0	Success.
EINVAL	Invalid argument.

sg_strmap_cleanup()

void sg_strmap_cleanup

(

struct sg_strmap **

map

)

Cleans the entire map.

Parameters

[in,out]

map

Pointer to the pairs map.

Examples

example_strmap.c.