string-array: New functions for comparing string arrays.
[pspp] / src / libpspp / string-array.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2010 Free Software Foundation, Inc.
3
4    This program is free software: you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation, either version 3 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
16
17 #ifndef LIBPSPP_STRING_ARRAY_H
18 #define LIBPSPP_STRING_ARRAY_H
19
20 #include <stdbool.h>
21 #include <stddef.h>
22 #include "libpspp/str.h"
23
24 /* An unordered array of strings.
25
26    Not opaque by any means. */
27 struct string_array
28   {
29     char **strings;
30     size_t n;
31     size_t allocated;
32   };
33
34 /* Suitable for use as the initializer for a string_array named ARRAY.  Typical
35    usage:
36        struct string_array array = STRING_ARRAY_INITIALIZER;
37    STRING_ARRAY_INITIALIZER is an alternative to calling string_array_init. */
38 #define STRING_ARRAY_INITIALIZER { NULL, 0, 0 }
39
40 void string_array_init (struct string_array *);
41 void string_array_clone (struct string_array *, const struct string_array *);
42 void string_array_swap (struct string_array *, struct string_array *);
43 void string_array_destroy (struct string_array *);
44
45 static inline size_t string_array_count (const struct string_array *);
46 static inline bool string_array_is_empty (const struct string_array *);
47
48 bool string_array_contains (const struct string_array *, const char *);
49 size_t string_array_find (const struct string_array *, const char *);
50
51 void string_array_append (struct string_array *, const char *);
52 void string_array_append_nocopy (struct string_array *, char *);
53 void string_array_insert (struct string_array *, const char *, size_t before);
54 void string_array_insert_nocopy (struct string_array *, char *, size_t before);
55 void string_array_delete (struct string_array *, size_t idx);
56 char *string_array_delete_nofree (struct string_array *, size_t idx);
57
58 void string_array_clear (struct string_array *);
59
60 void string_array_terminate_null (struct string_array *);
61 void string_array_shrink (struct string_array *);
62
63 void string_array_sort (struct string_array *);
64 void string_array_uniq (struct string_array *);
65
66 bool string_array_equal (const struct string_array *,
67                          const struct string_array *);
68 bool string_array_equal_case (const struct string_array *,
69                               const struct string_array *);
70
71 void string_array_parse (struct string_array *, struct substring string,
72                          struct substring delimiters);
73 char *string_array_join (const struct string_array *, const char *separator);
74
75 /* Macros for conveniently iterating through a string_array, e.g. to print all
76    of the strings in "my_array":
77
78    const char *string;
79    size_t idx;
80
81    STRING_ARRAY_FOR_EACH (string, idx, &my_array)
82      puts (string);
83 */
84 #define STRING_ARRAY_FOR_EACH(STRING, IDX, ARRAY)                  \
85   for ((IDX) = 0;                                                  \
86        ((IDX) < (ARRAY)->n                                         \
87         ? ((STRING) = (ARRAY)->strings[IDX], true)                 \
88         : false);                                                  \
89        (IDX)++)
90 \f
91 /* Returns the number of strings currently in ARRAY. */
92 static inline size_t
93 string_array_count (const struct string_array *array)
94 {
95   return array->n;
96 }
97
98 /* Returns true if ARRAY currently contains no strings, false otherwise. */
99 static inline bool
100 string_array_is_empty (const struct string_array *array)
101 {
102   return array->n == 0;
103 }
104
105 #endif /* libpspp/string-array.h */