Loading...
Searching...
No Matches
String vector

Helpers for strings vectors manipulation. More...

## Macros

#define | EC_STRVEC(args...)
| Allocate a new string vector.
#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().
#define | EC_STRVEC_ATTR_END "end"
| The end index in the original line passed to ec_strvec_sh_lex_str().

## Enumerations

enum | ec_strvec_flag_t { EC_STRVEC_STRICT = 0x1 , EC_STRVEC_TRAILSP = 0x2 }
| Options for ec_strvec_sh_lex_str(). More...

## Functions

struct ec_strvec * | ec_strvec (void)
| Allocate a new empty string vector.
struct ec_strvec * | ec_strvec_from_array (const char *const *strarr, size_t n)
| Allocate a new string vector.
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.
int | ec_strvec_set (struct ec_strvec *strvec, size_t idx, const char *s)
| Set a string in the vector at specified index.
int | ec_strvec_add (struct ec_strvec *strvec, const char *s)
| Add a string in a vector.
int | ec_strvec_del_last (struct ec_strvec *strvec)
| Delete the last entry in the string vector.
struct ec_strvec * | ec_strvec_dup (const struct ec_strvec *strvec)
| Duplicate a string vector.
struct ec_strvec * | ec_strvec_ndup (const struct ec_strvec *strvec, size_t off, size_t len)
| Duplicate a part of a string vector.
void | ec_strvec_free (struct ec_strvec *strvec)
| Free a string vector.
size_t | ec_strvec_len (const struct ec_strvec *strvec)
| Get the length of a string vector.
const char * | ec_strvec_val (const struct ec_strvec *strvec, size_t idx)
| Get a string element from a vector.
const struct ec_dict * | ec_strvec_get_attrs (const struct ec_strvec *strvec, size_t idx)
| Get the attributes of a vector element.
int | ec_strvec_set_attrs (struct ec_strvec *strvec, size_t idx, struct ec_dict *attrs)
| Set the attributes of a vector element.
int | ec_strvec_cmp (const struct ec_strvec *strvec1, const struct ec_strvec *strvec2)
| Compare two string vectors.
void | ec_strvec_sort (struct ec_strvec *strvec, int(*str_cmp)(const char *s1, const char *s2))
| Sort the string vector.
void | ec_strvec_dump (FILE *out, const struct ec_strvec *strvec)
| Dump a string vector.

## 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)); \
})
EC_COUNT_OF
#define EC_COUNT_OF(x)
Count number of elements in an array.
Definition utils.h:31

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.