lib/util/util_strlist.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    Copyright (C) Andrew Tridgell 2005
   5    Copyright (C) Jelmer Vernooij 2005
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19 */
  20
  21 #ifndef _SAMBA_UTIL_STRLIST_H
  22 #define _SAMBA_UTIL_STRLIST_H
  23
  24 #include <talloc.h>
  25
  26 /* separators for lists */
  27 #ifndef LIST_SEP
  28 #define LIST_SEP " \t,\n\r"
  29 #endif
  30
  31 /**
  32   build an empty (only NULL terminated) list of strings (for expansion with str_list_add() etc)
  33 */
  34 char **str_list_make_empty(TALLOC_CTX *mem_ctx);
  35
  36 /**
  37   place the only element 'entry' into a new, NULL terminated string list
  38 */
  39 char **str_list_make_single(TALLOC_CTX *mem_ctx,
  40                             const char *entry);
  41
  42 /**
  43   build a null terminated list of strings from a input string and a
  44   separator list. The separator list must contain characters less than
  45   or equal to 0x2f for this to work correctly on multi-byte strings
  46 */
  47 char **str_list_make(TALLOC_CTX *mem_ctx, const char *string,
  48                      const char *sep);
  49
  50 /**
  51  * build a null terminated list of strings from an argv-like input string
  52  * Entries are separated by spaces and can be enclosed by quotes.
  53  * Does NOT support escaping
  54  */
  55 char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string,
  56                            const char *sep);
  57
  58 /**
  59  * join a list back to one string
  60  */
  61 char *str_list_join(TALLOC_CTX *mem_ctx, const char **list,
  62                     char separator);
  63
  64 /** join a list back to one (shell-like) string; entries
  65  * separated by spaces, using quotes where necessary */
  66 char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list,
  67                           char sep);
  68
  69 /**
  70   return the number of elements in a string list
  71 */
  72 size_t str_list_length(const char * const *list);
  73
  74 /**
  75   copy a string list
  76 */
  77 char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
  78
  79 /**
  80    Return true if all the elements of the list match exactly.
  81  */
  82 bool str_list_equal(const char * const *list1,
  83                     const char * const *list2);
  84
  85 /**
  86   add an entry to a string list
  87 */
  88 const char **str_list_add(const char **list, const char *s);
  89
  90 /*
  91  * Extend a list with a printf'ed string
  92  */
  93 void str_list_add_printf(char ***plist, const char *fmt, ...)
  94         PRINTF_ATTRIBUTE(2,3);
  95
  96 /**
  97   remove an entry from a string list
  98 */
  99 void str_list_remove(const char **list, const char *s);
 100
 101 /**
 102   return true if a string is in a list
 103 */
 104 bool str_list_check(const char **list, const char *s);
 105
 106 /**
 107   return true if a string is in a list, case insensitively
 108 */
 109 bool str_list_check_ci(const char **list, const char *s);
 110 /**
 111   append one list to another - expanding list1
 112 */
 113 const char **str_list_append(const char **list1,
 114                              const char * const *list2);
 115
 116 /**
 117  remove duplicate elements from a list
 118 */
 119 const char **str_list_unique(const char **list);
 120
 121 /*
 122   very useful when debugging complex list related code
 123  */
 124 void str_list_show(const char **list);
 125
 126
 127 /**
 128   append one list to another - expanding list1
 129   this assumes the elements of list2 are const pointers, so we can re-use them
 130 */
 131 const char **str_list_append_const(const char **list1,
 132                                    const char **list2);
 133
 134 /**
 135    Add a string to an array of strings.
 136
 137    num should be a pointer to an integer that holds the current
 138    number of elements in strings. It will be updated by this function.
 139  */
 140 bool add_string_to_array(TALLOC_CTX *mem_ctx,
 141                          const char *str, const char ***strings, size_t *num);
 142
 143 /**
 144   add an entry to a string list
 145   this assumes s will not change
 146 */
 147 const char **str_list_add_const(const char **list, const char *s);
 148
 149 /**
 150   copy a string list
 151   this assumes list will not change
 152 */
 153 const char **str_list_copy_const(TALLOC_CTX *mem_ctx,
 154                                  const char **list);
 155
 156 #endif /* _SAMBA_UTIL_STRLIST_H */