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   remove an entry from a string list
  92 */
  93 void str_list_remove(const char **list, const char *s);
  94
  95 /**
  96   return true if a string is in a list
  97 */
  98 bool str_list_check(const char **list, const char *s);
  99
 100 /**
 101   return true if a string is in a list, case insensitively
 102 */
 103 bool str_list_check_ci(const char **list, const char *s);
 104 /**
 105   append one list to another - expanding list1
 106 */
 107 const char **str_list_append(const char **list1,
 108                              const char * const *list2);
 109
 110 /**
 111  remove duplicate elements from a list
 112 */
 113 const char **str_list_unique(const char **list);
 114
 115 /*
 116   very useful when debugging complex list related code
 117  */
 118 void str_list_show(const char **list);
 119
 120
 121 /**
 122   append one list to another - expanding list1
 123   this assumes the elements of list2 are const pointers, so we can re-use them
 124 */
 125 const char **str_list_append_const(const char **list1,
 126                                    const char **list2);
 127
 128 /**
 129    Add a string to an array of strings.
 130
 131    num should be a pointer to an integer that holds the current
 132    number of elements in strings. It will be updated by this function.
 133  */
 134 bool add_string_to_array(TALLOC_CTX *mem_ctx,
 135                          const char *str, const char ***strings, size_t *num);
 136
 137 /**
 138   add an entry to a string list
 139   this assumes s will not change
 140 */
 141 const char **str_list_add_const(const char **list, const char *s);
 142
 143 /**
 144   copy a string list
 145   this assumes list will not change
 146 */
 147 const char **str_list_copy_const(TALLOC_CTX *mem_ctx,
 148                                  const char **list);
 149
 150 #endif /* _SAMBA_UTIL_STRLIST_H */