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