libecoli/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  * Add a string in a vector.
  62  *
  63  * @param strvec
  64  *   The pointer to the string vector.
  65  * @param s
  66  *   The string to be added at the end of the vector.
  67  * @return
  68  *   0 on success or -1 on error (errno is set).
  69  */
  70 int ec_strvec_add(struct ec_strvec *strvec, const char *s);
  71
  72 /**
  73  * Delete the last entry in the string 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_del_last(struct ec_strvec *strvec);
  83
  84 /**
  85  * Duplicate a string vector.
  86  *
  87  * @param strvec
  88  *   The pointer to the string vector.
  89  * @return
  90  *   The duplicated strvec object, or NULL on error (errno is set).
  91  */
  92 struct ec_strvec *ec_strvec_dup(const struct ec_strvec *strvec);
  93
  94 /**
  95  * Duplicate a part of a string vector.
  96  *
  97  * @param strvec
  98  *   The pointer to the string vector.
  99  * @param off
 100  *   The index of the first string to duplicate.
 101  * @param
 102  *   The number of strings to duplicate.
 103  * @return
 104  *   The duplicated strvec object, or NULL on error (errno is set).
 105  */
 106 struct ec_strvec *ec_strvec_ndup(const struct ec_strvec *strvec,
 107         size_t off, size_t len);
 108
 109 /**
 110  * Free a string vector.
 111  *
 112  * @param strvec
 113  *   The pointer to the string vector.
 114  */
 115 void ec_strvec_free(struct ec_strvec *strvec);
 116
 117 /**
 118  * Get the length of a string vector.
 119  *
 120  * @param strvec
 121  *   The pointer to the string vector.
 122  * @return
 123  *   The length of the vector.
 124  */
 125 size_t ec_strvec_len(const struct ec_strvec *strvec);
 126
 127 /**
 128  * Get a string element from a vector.
 129  *
 130  * @param strvec
 131  *   The pointer to the string vector.
 132  * @param idx
 133  *   The index of the string to get.
 134  * @return
 135  *   The string stored at given index, or NULL on error (strvec is NULL
 136  *   or invalid index).
 137  */
 138 const char *ec_strvec_val(const struct ec_strvec *strvec, size_t idx);
 139
 140 /**
 141  * Compare two string vectors
 142  *
 143  * @param strvec
 144  *   The pointer to the first string vector.
 145  * @param strvec
 146  *   The pointer to the second string vector.
 147  * @return
 148  *   0 if the string vectors are equal.
 149  */
 150 int ec_strvec_cmp(const struct ec_strvec *strvec1,
 151                 const struct ec_strvec *strvec2);
 152
 153 /**
 154  * Sort the string vector.
 155  *
 156  * @param strvec
 157  *   The pointer to the first string vector.
 158  * @param str_cmp
 159  *   The sort function to use. If NULL, use strcmp.
 160  */
 161 void ec_strvec_sort(struct ec_strvec *strvec,
 162                 int (*str_cmp)(const char *s1, const char *s2));
 163
 164 /**
 165  * Dump a string vector.
 166  *
 167  * @param out
 168  *   The stream where the dump is sent.
 169  * @param strvec
 170  *   The pointer to the string vector.
 171  */
 172 void ec_strvec_dump(FILE *out, const struct ec_strvec *strvec);
 173
 174 #endif