include/ecoli_strvec.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * Vectors of strings.
   7  *
   8  * The ec_strvec API provide helpers to manipulate string vectors.
   9  * When duplicating vectors, the strings are not duplicated in memory,
  10  * a reference counter is used.
  11  */
  12
  13 #ifndef ECOLI_STRVEC_
  14 #define ECOLI_STRVEC_
  15
  16 #include <stdio.h>
  17
  18 /**
  19  * Allocate a new empty string vector.
  20  *
  21  * @return
  22  *   The new strvec object, or NULL on error (errno is set).
  23  */
  24 struct ec_strvec *ec_strvec(void);
  25
  26 #ifndef EC_COUNT_OF
  27 #define EC_COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / \
  28                 ((size_t)(!(sizeof(x) % sizeof(0[x])))))
  29 #endif
  30
  31 /**
  32  * Allocate a new string vector
  33  *
  34  * The string vector is initialized with the list of const strings
  35  * passed as arguments.
  36  *
  37  * @return
  38  *   The new strvec object, or NULL on error (errno is set).
  39  */
  40 #define EC_STRVEC(args...) ({                                           \
  41                         const char *_arr[] = {args};                    \
  42                         ec_strvec_from_array(_arr, EC_COUNT_OF(_arr));  \
  43                 })
  44 /**
  45  * Allocate a new string vector
  46  *
  47  * The string vector is initialized with the array of const strings
  48  * passed as arguments.
  49  *
  50  * @param strarr
  51  *   The array of const strings.
  52  * @param n
  53  *   The number of strings in the array.
  54  * @return
  55  *   The new strvec object, or NULL on error (errno is set).
  56  */
  57 struct ec_strvec *ec_strvec_from_array(const char * const *strarr,
  58         size_t n);
  59
  60 /**
  61  * Set a string in the vector at specified index.
  62  *
  63  * @param strvec
  64  *   The pointer to the string vector.
  65  * @param idx
  66  *   The index of the string to set.
  67  * @param s
  68  *   The string to be set.
  69  * @return
  70  *   0 on success or -1 on error (errno is set).
  71  */
  72 int ec_strvec_set(struct ec_strvec *strvec, size_t idx, const char *s);
  73
  74 /**
  75  * Add a string in a vector.
  76  *
  77  * @param strvec
  78  *   The pointer to the string vector.
  79  * @param s
  80  *   The string to be added at the end of the vector.
  81  * @return
  82  *   0 on success or -1 on error (errno is set).
  83  */
  84 int ec_strvec_add(struct ec_strvec *strvec, const char *s);
  85
  86 /**
  87  * Delete the last entry in the string vector.
  88  *
  89  * @param strvec
  90  *   The pointer to the string vector.
  91  * @param s
  92  *   The string to be added at the end of the vector.
  93  * @return
  94  *   0 on success or -1 on error (errno is set).
  95  */
  96 int ec_strvec_del_last(struct ec_strvec *strvec);
  97
  98 /**
  99  * Duplicate a string vector.
 100  *
 101  * Attributes are duplicated if any.
 102  *
 103  * @param strvec
 104  *   The pointer to the string vector.
 105  * @return
 106  *   The duplicated strvec object, or NULL on error (errno is set).
 107  */
 108 struct ec_strvec *ec_strvec_dup(const struct ec_strvec *strvec);
 109
 110 /**
 111  * Duplicate a part of a string vector.
 112  *
 113  * Attributes are duplicated if any.
 114  *
 115  * @param strvec
 116  *   The pointer to the string vector.
 117  * @param off
 118  *   The index of the first string to duplicate.
 119  * @param
 120  *   The number of strings to duplicate.
 121  * @return
 122  *   The duplicated strvec object, or NULL on error (errno is set).
 123  */
 124 struct ec_strvec *ec_strvec_ndup(const struct ec_strvec *strvec,
 125         size_t off, size_t len);
 126
 127 /**
 128  * Free a string vector.
 129  *
 130  * @param strvec
 131  *   The pointer to the string vector.
 132  */
 133 void ec_strvec_free(struct ec_strvec *strvec);
 134
 135 /**
 136  * Get the length of a string vector.
 137  *
 138  * @param strvec
 139  *   The pointer to the string vector.
 140  * @return
 141  *   The length of the vector.
 142  */
 143 size_t ec_strvec_len(const struct ec_strvec *strvec);
 144
 145 /**
 146  * Get a string element from a vector.
 147  *
 148  * @param strvec
 149  *   The pointer to the string vector.
 150  * @param idx
 151  *   The index of the string to get.
 152  * @return
 153  *   The string stored at given index, or NULL on error (strvec is NULL
 154  *   or invalid index).
 155  */
 156 const char *ec_strvec_val(const struct ec_strvec *strvec, size_t idx);
 157
 158 /**
 159  * Get the attributes of a vector element.
 160  *
 161  * @param strvec
 162  *   The pointer to the string vector.
 163  * @param idx
 164  *   The index of the string to get.
 165  * @return
 166  *   The read-only attributes (dictionnary) of the string at specified
 167  *   index, or NULL if there is no attribute.
 168  */
 169 const struct ec_keyval *ec_strvec_get_attrs(const struct ec_strvec *strvec,
 170         size_t idx);
 171
 172 /**
 173  * Set the attributes of a vector element.
 174  *
 175  * @param strvec
 176  *   The pointer to the string vector.
 177  * @param idx
 178  *   The index of the string to get.
 179  * @param attrs
 180  *   The attributes to be set.
 181  * @return
 182  *   0 on success, -1 on error (errno is set). On error, attrs
 183  *   are freed and must not be used by the caller.
 184  */
 185 int ec_strvec_set_attrs(struct ec_strvec *strvec, size_t idx,
 186                         struct ec_keyval *attrs);
 187
 188 /**
 189  * Compare two string vectors
 190  *
 191  * @param strvec
 192  *   The pointer to the first string vector.
 193  * @param strvec
 194  *   The pointer to the second string vector.
 195  * @return
 196  *   0 if the string vectors are equal.
 197  */
 198 int ec_strvec_cmp(const struct ec_strvec *strvec1,
 199                 const struct ec_strvec *strvec2);
 200
 201 /**
 202  * Sort the string vector.
 203  *
 204  * Attributes are not compared.
 205  *
 206  * @param strvec
 207  *   The pointer to the first string vector.
 208  * @param str_cmp
 209  *   The sort function to use. If NULL, use strcmp.
 210  */
 211 void ec_strvec_sort(struct ec_strvec *strvec,
 212                 int (*str_cmp)(const char *s1, const char *s2));
 213
 214 /**
 215  * Dump a string vector.
 216  *
 217  * @param out
 218  *   The stream where the dump is sent.
 219  * @param strvec
 220  *   The pointer to the string vector.
 221  */
 222 void ec_strvec_dump(FILE *out, const struct ec_strvec *strvec);
 223
 224 #endif