include/ecoli_strvec.h

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