String vector

Helpers for strings vectors manipulation. More...

Macros
#define	EC_STRVEC(args...)
#define	EC_STRVEC_ATTR_START   "start"
#define	EC_STRVEC_ATTR_END   "end"

Enumerations
enum	ec_strvec_flag_t { EC_STRVEC_STRICT = 0x1 , EC_STRVEC_TRAILSP = 0x2 }

Functions
struct ec_strvec *	ec_strvec (void)
struct ec_strvec *	ec_strvec_from_array (const char *const *strarr, size_t n)
struct ec_strvec *	ec_strvec_sh_lex_str (const char *str, ec_strvec_flag_t flags, char *unclosed_quote)
int	ec_strvec_set (struct ec_strvec *strvec, size_t idx, const char *s)
int	ec_strvec_add (struct ec_strvec *strvec, const char *s)
int	ec_strvec_del_last (struct ec_strvec *strvec)
struct ec_strvec *	ec_strvec_dup (const struct ec_strvec *strvec)
struct ec_strvec *	ec_strvec_ndup (const struct ec_strvec *strvec, size_t off, size_t len)
void	ec_strvec_free (struct ec_strvec *strvec)
size_t	ec_strvec_len (const struct ec_strvec *strvec)
const char *	ec_strvec_val (const struct ec_strvec *strvec, size_t idx)
const struct ec_dict *	ec_strvec_get_attrs (const struct ec_strvec *strvec, size_t idx)
int	ec_strvec_set_attrs (struct ec_strvec *strvec, size_t idx, struct ec_dict *attrs)
int	ec_strvec_cmp (const struct ec_strvec *strvec1, const struct ec_strvec *strvec2)
void	ec_strvec_sort (struct ec_strvec *strvec, int(*str_cmp)(const char *s1, const char *s2))
void	ec_strvec_dump (FILE *out, const struct ec_strvec *strvec)

Detailed Description

Helpers for strings vectors manipulation.

The ec_strvec API provides helpers to manipulate string vectors. When duplicating vectors, the strings are not duplicated in memory, a reference counter is used.

Macro Definition Documentation

EC_STRVEC

#define EC_STRVEC

(

args...

)

Value:

({                                                                                         \
    const char *_arr[] = {args};                                                       \
    ec_strvec_from_array(_arr, EC_COUNT_OF(_arr));                                     \
})

Allocate a new string vector.

The string vector is initialized with the list of const strings passed as arguments.

Returns

The new strvec object, or NULL on error (errno is set).

Definition at line 39 of file strvec.h.

EC_STRVEC_ATTR_START

#define EC_STRVEC_ATTR_START   "start"

All elements of the vector returned by ec_strvec_sh_lex_str() have two attributes accessible via ec_strvec_get_attrs(). The start index in the original line passed to ec_strvec_sh_lex_str().

Definition at line 80 of file strvec.h.

EC_STRVEC_ATTR_END

#define EC_STRVEC_ATTR_END   "end"

The end index in the original line passed to ec_strvec_sh_lex_str().

Definition at line 82 of file strvec.h.

Enumeration Type Documentation

ec_strvec_flag_t

enum ec_strvec_flag_t

Options for ec_strvec_sh_lex_str().

Enumerator
EC_STRVEC_STRICT	Fail if a quote is not closed properly or if the provided string ends with an unterminated escape sequence.
EC_STRVEC_TRAILSP	If there is trailing white space, add an empty element to the output string vector.

Definition at line 62 of file strvec.h.

Function Documentation

ec_strvec()

struct ec_strvec * ec_strvec

(

void

)

Allocate a new empty string vector.

Returns

The new strvec object, or NULL on error (errno is set).

Examples

parse-yaml/parse-yaml.c, and pool-editline/main.c.

ec_strvec_from_array()

struct ec_strvec * ec_strvec_from_array	(	const char *const *	strarr,
		size_t	n )

Allocate a new string vector.

The string vector is initialized with the array of const strings passed as arguments.

Parameters

strarr	The array of const strings.
n	The number of strings in the array.

Returns

The new strvec object, or NULL on error (errno is set).

Examples

parse-yaml/parse-yaml.c.

ec_strvec_sh_lex_str()

struct ec_strvec * ec_strvec_sh_lex_str	(	const char *	str,
		ec_strvec_flag_t	flags,
		char *	unclosed_quote )

Split a string into multiple tokens following basic shell lexing rules.

Parameters

str	The string to split.
flags	Options for controlling behavior.
unclosed_quote	If not NULL and if the provided string has an unterminated quote. The opening quote will be stored here.

Returns

The new strvec object, or NULL on error (errno is set).

ec_strvec_set()

int ec_strvec_set	(	struct ec_strvec *	strvec,
		size_t	idx,
		const char *	s )

Set a string in the vector at specified index.

Parameters

strvec	The pointer to the string vector.
idx	The index of the string to set.
s	The string to be set.

Returns

0 on success or -1 on error (errno is set).

ec_strvec_add()

int ec_strvec_add	(	struct ec_strvec *	strvec,
		const char *	s )

Add a string in a vector.

Parameters

strvec	The pointer to the string vector.
s	The string to be added at the end of the vector.

Returns

0 on success or -1 on error (errno is set).

ec_strvec_del_last()

int ec_strvec_del_last

(

struct ec_strvec *

strvec

)

Delete the last entry in the string vector.

Parameters

strvec

The pointer to the string vector.

Returns

0 on success or -1 on error (errno is set).

ec_strvec_dup()

struct ec_strvec * ec_strvec_dup

(

const struct ec_strvec *

strvec

)

Duplicate a string vector.

Attributes are duplicated if any.

Parameters

strvec

The pointer to the string vector.

Returns

The duplicated strvec object, or NULL on error (errno is set).

ec_strvec_ndup()

struct ec_strvec * ec_strvec_ndup	(	const struct ec_strvec *	strvec,
		size_t	off,
		size_t	len )

Duplicate a part of a string vector.

Attributes are duplicated if any.

Parameters

strvec	The pointer to the string vector.
off	The index of the first string to duplicate.
len	The number of strings to duplicate.

Returns

The duplicated strvec object, or NULL on error (errno is set).

ec_strvec_free()

void ec_strvec_free

(

struct ec_strvec *

strvec

)

Free a string vector.

Parameters

strvec

The pointer to the string vector.

Examples

parse-yaml/parse-yaml.c, and pool-editline/main.c.

ec_strvec_len()

size_t ec_strvec_len

(

const struct ec_strvec *

strvec

)

Get the length of a string vector.

Parameters

strvec

The pointer to the string vector.

Returns

The length of the vector.

Examples

parse-yaml/parse-yaml.c, and pool-editline/main.c.

ec_strvec_val()

const char * ec_strvec_val	(	const struct ec_strvec *	strvec,
		size_t	idx )

Get a string element from a vector.

Parameters

strvec	The pointer to the string vector.
idx	The index of the string to get.

Returns

The string stored at given index, or NULL on error (strvec is NULL or invalid index).

Examples

extension-editline/main.c, parse-yaml/parse-yaml.c, pool-editline/main.c, and simple-editline/main.c.

ec_strvec_get_attrs()

const struct ec_dict * ec_strvec_get_attrs	(	const struct ec_strvec *	strvec,
		size_t	idx )

Get the attributes of a vector element.

Parameters

strvec	The pointer to the string vector.
idx	The index of the string to get.

Returns

The read-only attributes (dictionary) of the string at specified index, or NULL if there is no attribute.

ec_strvec_set_attrs()

int ec_strvec_set_attrs	(	struct ec_strvec *	strvec,
		size_t	idx,
		struct ec_dict *	attrs )

Set the attributes of a vector element.

Parameters

strvec	The pointer to the string vector.
idx	The index of the string to get.
attrs	The attributes to be set.

Returns

0 on success, -1 on error (errno is set). On error, attrs are freed and must not be used by the caller.

ec_strvec_cmp()

int ec_strvec_cmp	(	const struct ec_strvec *	strvec1,
		const struct ec_strvec *	strvec2 )

Compare two string vectors.

Parameters

strvec1	The pointer to the first string vector.
strvec2	The pointer to the second string vector.

Returns

0 if the string vectors are equal.

ec_strvec_sort()

void ec_strvec_sort	(	struct ec_strvec *	strvec,
		int(*	str_cmp )(const char *s1, const char *s2) )

Sort the string vector.

Attributes are not compared.

Parameters

strvec	The pointer to the first string vector.
str_cmp	The sort function to use. If NULL, use strcmp.

ec_strvec_dump()

void ec_strvec_dump	(	FILE *	out,
		const struct ec_strvec *	strvec )

Dump a string vector.

Parameters

out	The stream where the dump is sent.
strvec	The pointer to the string vector.