include/inn/vector.h

   1 /*  $Id: vector.h 5450 2002-04-23 06:06:10Z rra $
   2 **
   3 **  Vector handling (counted lists of char *'s).
   4 **
   5 **  Written by Russ Allbery <rra@stanford.edu>
   6 **  This work is hereby placed in the public domain by its author.
   7 **
   8 **  A vector is a simple array of char *'s combined with a count.  It's a
   9 **  convenient way of managing a list of strings, as well as a reasonable
  10 **  output data structure for functions that split up a string.  There are
  11 **  two basic types of vectors, regular vectors (in which case strings are
  12 **  copied when put into a vector and freed when the vector is freed) and
  13 **  cvectors or const vectors (where each pointer is a const char * to some
  14 **  external string that isn't freed when the vector is freed).
  15 **
  16 **  There are two interfaces here, one for vectors and one for cvectors,
  17 **  with the basic operations being the same between the two.
  18 */
  19
  20 #ifndef INN_VECTOR_H
  21 #define INN_VECTOR_H 1
  22
  23 #include <inn/defines.h>
  24
  25 struct vector {
  26     size_t count;
  27     size_t allocated;
  28     char **strings;
  29 };
  30
  31 struct cvector {
  32     size_t count;
  33     size_t allocated;
  34     const char **strings;
  35 };
  36
  37 BEGIN_DECLS
  38
  39 /* Create a new, empty vector. */
  40 struct vector *vector_new(void);
  41 struct cvector *cvector_new(void);
  42
  43 /* Add a string to a vector.  Resizes the vector if necessary. */
  44 void vector_add(struct vector *, const char *string);
  45 void cvector_add(struct cvector *, const char *string);
  46
  47 /* Resize the array of strings to hold size entries.  Saves reallocation work
  48    in vector_add if it's known in advance how many entries there will be. */
  49 void vector_resize(struct vector *, size_t size);
  50 void cvector_resize(struct cvector *, size_t size);
  51
  52 /* Reset the number of elements to zero, freeing all of the strings for a
  53    regular vector, but not freeing the strings array (to cut down on memory
  54    allocations if the vector will be reused). */
  55 void vector_clear(struct vector *);
  56 void cvector_clear(struct cvector *);
  57
  58 /* Free the vector and all resources allocated for it. */
  59 void vector_free(struct vector *);
  60 void cvector_free(struct cvector *);
  61
  62 /* Split functions build a vector from a string.  vector_split splits on a
  63    specified character, while vector_split_space splits on any sequence of
  64    spaces or tabs (not any sequence of whitespace, as just spaces or tabs is
  65    more useful for INN).  The cvector versions destructively modify the
  66    provided string in-place to insert nul characters between the strings.  If
  67    the vector argument is NULL, a new vector is allocated; otherwise, the
  68    provided one is reused.
  69
  70    Empty strings will yield zero-length vectors.  Adjacent delimiters are
  71    treated as a single delimiter by *_split_space, but *not* by *_split, so
  72    callers of *_split should be prepared for zero-length strings in the
  73    vector. */
  74 struct vector *vector_split(const char *string, char sep, struct vector *);
  75 struct vector *vector_split_space(const char *string, struct vector *);
  76 struct cvector *cvector_split(char *string, char sep, struct cvector *);
  77 struct cvector *cvector_split_space(char *string, struct cvector *);
  78
  79 /* Build a string from a vector by joining its components together with the
  80    specified string as separator.  Returns a newly allocated string; caller is
  81    responsible for freeing. */
  82 char *vector_join(const struct vector *, const char *seperator);
  83 char *cvector_join(const struct cvector *, const char *separator);
  84
  85 END_DECLS
  86
  87 #endif /* INN_VECTOR_H */