a9435fcdfb39c1a13d9b0cf936cf6265a3160931
[pspp-builds.git] / src / libpspp / str.h
1 /* PSPP - computes sample statistics.
2    Copyright (C) 1997-9, 2000 Free Software Foundation, Inc.
3
4    This program is free software; you can redistribute it and/or
5    modify it under the terms of the GNU General Public License as
6    published by the Free Software Foundation; either version 2 of the
7    License, or (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful, but
10    WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    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, write to the Free Software
16    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17    02110-1301, USA. */
18
19 #if !str_h
20 #define str_h 1
21
22 #include <assert.h>
23 #include <stdarg.h>
24 #include <stdbool.h>
25 #include <stdio.h>
26 #include <string.h>
27
28 #include "compiler.h"
29 #include "memcasecmp.h"
30 #include "memmem.h"
31 #include "snprintf.h"
32 #include "stpcpy.h"
33 #include "strcase.h"
34 #include "strftime.h"
35 #include "strstr.h"
36 #include "strtok_r.h"
37 #include "vsnprintf.h"
38 #include "xvasprintf.h"
39 \f
40 /* Miscellaneous. */
41
42 void buf_reverse (char *, size_t);
43 char *buf_find_reverse (const char *, size_t, const char *, size_t);
44 int buf_compare_case (const char *, const char *, size_t);
45 int buf_compare_rpad (const char *, size_t, const char *, size_t);
46 void buf_copy_lpad (char *, size_t, const char *, size_t);
47 void buf_copy_rpad (char *, size_t, const char *, size_t);
48 void buf_copy_str_lpad (char *, size_t, const char *);
49 void buf_copy_str_rpad (char *, size_t, const char *);
50
51 int str_compare_rpad (const char *, const char *);
52 void str_copy_rpad (char *, size_t, const char *);
53 void str_copy_trunc (char *, size_t, const char *);
54 void str_copy_buf_trunc (char *, size_t, const char *, size_t);
55 void str_uppercase (char *);
56 void str_lowercase (char *);
57
58 char *spprintf (char *dst, const char *format, ...);
59
60 void *mempset (void *, int, size_t);
61 \f
62 /* Common character classes for use with substring and string functions. */
63
64 #define CC_SPACES " \t\v\r\n"
65 #define CC_DIGITS "0123456789"
66 #define CC_XDIGITS "0123456789abcdefABCDEF"
67 #define CC_LETTERS "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
68 #define CC_ALNUM CC_LETTERS CC_DIGITS
69 \f
70 /* Substrings. */
71 struct substring 
72   {
73     char *string;
74     size_t length;
75   };
76
77 #define SS_EMPTY_INITIALIZER {NULL, 0}
78 #define SS_LITERAL_INITIALIZER(LITERAL)                 \
79         {(char *) LITERAL, (sizeof LITERAL) - 1}
80
81 /* Constructors.
82    These functions do not allocate any memory, so the substrings
83    they create should not normally be destroyed. */
84 struct substring ss_empty (void);
85 struct substring ss_cstr (const char *);
86 struct substring ss_buffer (const char *, size_t);
87 struct substring ss_substr (struct substring, size_t start, size_t);
88 struct substring ss_head (struct substring, size_t);
89 struct substring ss_tail (struct substring, size_t);
90
91 /* Constructors and destructor that allocate and deallocate
92    memory. */
93 struct pool;
94 void ss_alloc_substring (struct substring *, struct substring);
95 void ss_alloc_uninit (struct substring *, size_t);
96 void ss_alloc_substring_pool (struct substring *, struct substring,
97                               struct pool *);
98 void ss_alloc_uninit_pool (struct substring *, size_t, struct pool *);
99 void ss_dealloc (struct substring *);
100
101 /* Mutators.
102    Functions that advance the beginning of a string should not be
103    used if a substring is to be deallocated. */
104 void ss_truncate (struct substring *, size_t);
105 size_t ss_rtrim (struct substring *, struct substring trim_set);
106 size_t ss_ltrim (struct substring *, struct substring trim_set);
107 void ss_trim (struct substring *, struct substring trim_set);
108 bool ss_chomp (struct substring *, char);
109 bool ss_separate (struct substring src, struct substring delimiters,
110                   size_t *save_idx, struct substring *token);
111 bool ss_tokenize (struct substring src, struct substring delimiters,
112                   size_t *save_idx, struct substring *token);
113 void ss_advance (struct substring *, size_t);
114 bool ss_match_char (struct substring *, char);
115 bool ss_match_string (struct substring *, const struct substring);
116 int ss_get_char (struct substring *);
117 size_t ss_get_chars (struct substring *, size_t cnt, struct substring *);
118 bool ss_get_until (struct substring *, char delimiter, struct substring *);
119 size_t ss_get_long (struct substring *, long *);
120
121 /* Inspectors. */
122 bool ss_is_empty (struct substring);
123 size_t ss_length (struct substring);
124 char *ss_data (struct substring);
125 char *ss_end (struct substring);
126 int ss_at (struct substring, size_t idx);
127 int ss_first (struct substring);
128 int ss_last (struct substring);
129 size_t ss_span (struct substring, struct substring skip_set);
130 size_t ss_cspan (struct substring, struct substring stop_set);
131 size_t ss_find_char (struct substring, char);
132 int ss_compare (struct substring, struct substring);
133 int ss_compare_case (struct substring, struct substring);
134 int ss_equals (struct substring, struct substring);
135 int ss_equals_case (struct substring, struct substring);
136 size_t ss_pointer_to_position (struct substring, const char *);
137 char *ss_xstrdup (struct substring);
138 \f
139 /* Variable length strings. */
140
141 struct string
142   {
143     struct substring ss;
144
145     size_t capacity;    /* Allocated capacity, not including one
146                            extra byte allocated for null terminator. */
147   };
148
149 #define DS_EMPTY_INITIALIZER {SS_EMPTY_INITIALIZER, 0}
150
151 /* Constructors, destructors. */
152 void ds_init_empty (struct string *);
153 void ds_init_string (struct string *, const struct string *);
154 void ds_init_substring (struct string *, struct substring);
155 void ds_init_cstr (struct string *, const char *);
156 void ds_destroy (struct string *);
157 void ds_swap (struct string *, struct string *);
158
159 /* Pools. */
160 struct pool;
161 void ds_register_pool (struct string *, struct pool *);
162 void ds_unregister_pool (struct string *, struct pool *);
163
164 /* Replacement. */
165 void ds_assign_string (struct string *, const struct string *);
166 void ds_assign_substring (struct string *, struct substring);
167 void ds_assign_cstr (struct string *, const char *);
168
169 /* Shrink, extend. */
170 void ds_clear (struct string *);
171 void ds_extend (struct string *, size_t);
172 void ds_shrink (struct string *);
173 void ds_truncate (struct string *, size_t);
174
175 /* Padding, trimming. */
176 size_t ds_rtrim (struct string *, struct substring trim_set);
177 size_t ds_ltrim (struct string *, struct substring trim_set);
178 size_t ds_trim (struct string *, struct substring trim_set);
179 bool ds_chomp (struct string *, char);
180 bool ds_separate (const struct string *src, struct substring delimiters,
181                   size_t *save_idx, struct substring *token);
182 bool ds_tokenize (const struct string *src, struct substring delimiters,
183                   size_t *save_idx, struct substring *token);
184 void ds_rpad (struct string *, size_t length, char pad);
185 void ds_set_length (struct string *, size_t new_length, char pad);
186
187 /* Extracting substrings. */
188 struct substring ds_ss (const struct string *);
189 struct substring ds_substr (const struct string *, size_t start, size_t);
190 struct substring ds_head (const struct string *, size_t);
191 struct substring ds_tail (const struct string *, size_t);
192
193 /* Inspectors. */
194 bool ds_is_empty (const struct string *);
195 size_t ds_length (const struct string *);
196 char *ds_data (const struct string *);
197 char *ds_end (const struct string *);
198 int ds_at (const struct string *, size_t idx);
199 int ds_first (const struct string *);
200 int ds_last (const struct string *);
201 size_t ds_span (const struct string *, struct substring skip_set);
202 size_t ds_cspan (const struct string *, struct substring stop_set);
203 size_t ds_find_char (const struct string *, char);
204 int ds_compare (const struct string *, const struct string *);
205 size_t ds_pointer_to_position (const struct string *, const char *);
206 char *ds_xstrdup (const struct string *);
207
208 size_t ds_capacity (const struct string *);
209 char *ds_cstr (const struct string *);
210
211 /* File input. */
212 bool ds_read_line (struct string *, FILE *);
213 bool ds_read_config_line (struct string *, int *line_number, FILE *);
214 size_t ds_read_stream (struct string *, size_t size, size_t cnt, FILE *stream);
215
216 /* Append. */
217 void ds_put_char (struct string *, int ch);
218 void ds_put_char_multiple (struct string *, int ch, size_t);
219 void ds_put_cstr (struct string *, const char *);
220 void ds_put_substring (struct string *, struct substring);
221 void ds_put_vformat (struct string *st, const char *, va_list)
222      PRINTF_FORMAT (2, 0);
223 void ds_put_format (struct string *, const char *, ...)
224      PRINTF_FORMAT (2, 3);
225 char *ds_put_uninit (struct string *st, size_t incr);
226
227 #endif /* str_h */