src/libpspp/str.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2009, 2010, 2011, 2012, 2014 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 #if !str_h
  18 #define str_h 1
  19
  20 #include <assert.h>
  21 #include <limits.h>
  22 #include <stdarg.h>
  23 #include <stdbool.h>
  24 #include <stdint.h>
  25 #include <stdio.h>
  26 #include <string.h>
  27 #include <unitypes.h>
  28
  29 #include "compiler.h"
  30 #include "memcasecmp.h"
  31 #include "xstrndup.h"
  32 #include "xvasprintf.h"
  33
  34 #include "gl/verify.h"
  35 #include "gl/xalloc.h"
  36 \f
  37 /* Miscellaneous. */
  38
  39 struct substring;
  40
  41 void buf_reverse (char *, size_t);
  42 int buf_compare_case (const char *, const char *, size_t);
  43 int buf_compare_rpad (const char *, size_t, const char *, size_t);
  44 void buf_copy_lpad (char *, size_t, const char *, size_t, char pad);
  45 void buf_copy_rpad (char *, size_t, const char *, size_t, char pad);
  46 void buf_copy_str_lpad (char *, size_t, const char *, char pad);
  47 void buf_copy_str_rpad (char *, size_t, const char *, char pad);
  48
  49 int str_compare_rpad (const char *, const char *);
  50 void str_copy_rpad (char *, size_t, const char *);
  51 void str_copy_trunc (char *, size_t, const char *);
  52 void str_copy_buf_trunc (char *, size_t, const char *, size_t);
  53 void str_uppercase (char *);
  54 void str_lowercase (char *);
  55
  56 /* Maximum number of digits needed to express ULONG_MAX in 26-adic notation. */
  57 #define F26ADIC_STRLEN_MAX 14
  58 verify (ULONG_MAX <= UINT64_MAX);
  59
  60 bool str_format_26adic__ (unsigned long int number, bool uppercase,
  61                           char buffer[], size_t);
  62 void str_format_26adic  (unsigned long int number, bool uppercase,
  63                          char buffer[], size_t);
  64 int str_parse_26adic (const char *str);
  65
  66 void str_ellipsize (struct substring in, char *out, size_t out_size);
  67
  68 static inline char *xstrdup_if_nonnull (const char *);
  69
  70 void *mempset (void *, int, size_t);
  71 \f
  72 /* Common character classes for use with substring and string functions. */
  73
  74 #define CC_SPACES " \t\v\r\n"
  75 #define CC_DIGITS "0123456789"
  76 #define CC_XDIGITS "0123456789abcdefABCDEF"
  77 #define CC_LETTERS "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
  78 #define CC_ALNUM CC_LETTERS CC_DIGITS
  79 \f
  80 /* Substrings. */
  81 struct substring
  82   {
  83     char *string;
  84     size_t length;
  85   };
  86
  87 #define SS_EMPTY_INITIALIZER {NULL, 0}
  88 #define SS_LITERAL_INITIALIZER(LITERAL)                 \
  89         {(char *) LITERAL, (sizeof LITERAL) - 1}
  90
  91 /* Constructors.
  92    These functions do not allocate any memory, so the substrings
  93    they create should not normally be destroyed. */
  94 static inline struct substring ss_empty (void);
  95 static inline struct substring ss_cstr (const char *);
  96 static inline struct substring ss_buffer (const char *, size_t);
  97 struct substring ss_substr (struct substring, size_t start, size_t);
  98 struct substring ss_head (struct substring, size_t);
  99 struct substring ss_tail (struct substring, size_t);
 100
 101 /* Constructors and destructor that allocate and deallocate
 102    memory. */
 103 struct pool;
 104 struct substring ss_clone (struct substring);
 105 struct substring ss_clone_pool (struct substring, struct pool *);
 106 void ss_alloc_uninit (struct substring *, size_t);
 107 void ss_realloc (struct substring *, size_t);
 108 void ss_alloc_uninit_pool (struct substring *, size_t, struct pool *);
 109 void ss_dealloc (struct substring *);
 110
 111 /* Mutators.
 112    Functions that advance the beginning of a string should not be
 113    used if a substring is to be deallocated. */
 114 void ss_swap (struct substring *, struct substring *);
 115 void ss_truncate (struct substring *, size_t);
 116 size_t ss_rtrim (struct substring *, struct substring trim_set);
 117 size_t ss_ltrim (struct substring *, struct substring trim_set);
 118 void ss_trim (struct substring *, struct substring trim_set);
 119 bool ss_chomp_byte (struct substring *, char);
 120 bool ss_chomp (struct substring *, struct substring);
 121 bool ss_separate (struct substring src, struct substring delimiters,
 122                   size_t *save_idx, struct substring *token);
 123 bool ss_tokenize (struct substring src, struct substring delimiters,
 124                   size_t *save_idx, struct substring *token);
 125 void ss_advance (struct substring *, size_t);
 126 bool ss_match_byte (struct substring *, char);
 127 int ss_match_byte_in (struct substring *, struct substring);
 128 bool ss_match_string (struct substring *, const struct substring);
 129 bool ss_match_string_case (struct substring *, const struct substring);
 130 int ss_get_byte (struct substring *);
 131 size_t ss_get_bytes (struct substring *, size_t n, struct substring *);
 132 bool ss_get_until (struct substring *, char delimiter, struct substring *);
 133 size_t ss_get_long (struct substring *, long *);
 134
 135 /* Inspectors. */
 136 bool ss_is_empty (struct substring);
 137 size_t ss_length (struct substring);
 138 char *ss_data (struct substring);
 139 char *ss_end (struct substring);
 140 int ss_at (struct substring, size_t idx);
 141 int ss_first (struct substring);
 142 int ss_last (struct substring);
 143 bool ss_starts_with (struct substring, struct substring prefix);
 144 bool ss_starts_with_case (struct substring, struct substring prefix);
 145 bool ss_ends_with (struct substring, struct substring suffix);
 146 bool ss_ends_with_case (struct substring, struct substring suffix);
 147 size_t ss_span (struct substring, struct substring skip_set);
 148 size_t ss_cspan (struct substring, struct substring stop_set);
 149 size_t ss_find_byte (struct substring, char);
 150 size_t ss_find_substring (struct substring, struct substring);
 151 int ss_compare (struct substring, struct substring);
 152 int ss_compare_rpad (struct substring, struct substring);
 153 int ss_compare_case (struct substring, struct substring);
 154 int ss_equals (struct substring, struct substring);
 155 int ss_equals_case (struct substring, struct substring);
 156 size_t ss_pointer_to_position (struct substring, const char *);
 157 char *ss_xstrdup (struct substring);
 158
 159 /* UTF-8. */
 160 ucs4_t ss_first_mb (struct substring);
 161 int ss_first_mblen (struct substring);
 162 ucs4_t ss_get_mb (struct substring *);
 163 ucs4_t ss_at_mb (struct substring, size_t ofs);
 164 int ss_at_mblen (struct substring, size_t ofs);
 165 size_t ss_utf8_count_columns (struct substring);
 166 struct substring ss_utf8_columns (struct substring, size_t start, size_t n);
 167 \f
 168 /* Variable length strings. */
 169
 170 struct string
 171   {
 172     struct substring ss;
 173
 174     size_t capacity;    /* Allocated capacity, not including one
 175                            extra byte allocated for null terminator. */
 176   };
 177
 178 #define DS_EMPTY_INITIALIZER {SS_EMPTY_INITIALIZER, 0}
 179
 180 /* Constructors, destructors. */
 181 void ds_init_empty (struct string *);
 182 void ds_init_string (struct string *, const struct string *);
 183 void ds_init_substring (struct string *, struct substring);
 184 void ds_init_cstr (struct string *, const char *);
 185 void ds_destroy (struct string *);
 186 void ds_swap (struct string *, struct string *);
 187
 188 /* Pools. */
 189 struct pool;
 190 void ds_register_pool (struct string *, struct pool *);
 191 void ds_unregister_pool (struct string *, struct pool *);
 192
 193 /* Replacement. */
 194 void ds_assign_string (struct string *, const struct string *);
 195 void ds_assign_substring (struct string *, struct substring);
 196 void ds_assign_cstr (struct string *, const char *);
 197
 198 /* Shrink, extend. */
 199 void ds_clear (struct string *);
 200 void ds_extend (struct string *, size_t);
 201 void ds_shrink (struct string *);
 202 void ds_truncate (struct string *, size_t);
 203
 204 /* Padding, trimming. */
 205 size_t ds_rtrim (struct string *, struct substring trim_set);
 206 size_t ds_ltrim (struct string *, struct substring trim_set);
 207 size_t ds_trim (struct string *, struct substring trim_set);
 208 bool ds_chomp_byte (struct string *, char);
 209 bool ds_chomp (struct string *, struct substring);
 210 bool ds_separate (const struct string *src, struct substring delimiters,
 211                   size_t *save_idx, struct substring *token);
 212 bool ds_tokenize (const struct string *src, struct substring delimiters,
 213                   size_t *save_idx, struct substring *token);
 214 void ds_rpad (struct string *, size_t length, char pad);
 215 void ds_set_length (struct string *, size_t new_length, char pad);
 216 void ds_remove (struct string *, size_t start, size_t n);
 217
 218 /* Extracting substrings. */
 219 struct substring ds_ss (const struct string *);
 220 struct substring ds_substr (const struct string *, size_t start, size_t);
 221 struct substring ds_head (const struct string *, size_t);
 222 struct substring ds_tail (const struct string *, size_t);
 223
 224 /* Inspectors. */
 225 bool ds_is_empty (const struct string *);
 226 size_t ds_length (const struct string *);
 227 char *ds_data (const struct string *);
 228 char *ds_end (const struct string *);
 229 int ds_at (const struct string *, size_t idx);
 230 int ds_first (const struct string *);
 231 int ds_last (const struct string *);
 232 bool ds_ends_with (const struct string *, struct substring suffix);
 233 size_t ds_span (const struct string *, struct substring skip_set);
 234 size_t ds_cspan (const struct string *, struct substring stop_set);
 235 size_t ds_find_byte (const struct string *, char);
 236 int ds_compare (const struct string *, const struct string *);
 237 size_t ds_pointer_to_position (const struct string *, const char *);
 238 char *ds_xstrdup (const struct string *);
 239
 240 size_t ds_capacity (const struct string *);
 241 char *ds_cstr (const struct string *);
 242 char *ds_steal_cstr (struct string *);
 243
 244 /* File input. */
 245 bool ds_read_line (struct string *, FILE *, size_t max_length);
 246 bool ds_read_config_line (struct string *, int *line_number, FILE *);
 247 bool ds_read_stream (struct string *, size_t size, size_t n, FILE *stream);
 248
 249 /* Append. */
 250 void ds_put_byte (struct string *, int ch);
 251 void ds_put_byte_multiple (struct string *, int ch, size_t);
 252 void ds_put_unichar (struct string *, ucs4_t uc);
 253 void ds_put_cstr (struct string *, const char *);
 254 void ds_put_substring (struct string *, struct substring);
 255 void ds_put_substring_multiple (struct string *, struct substring, size_t n);
 256 void ds_put_vformat (struct string *st, const char *, va_list)
 257      PRINTF_FORMAT (2, 0);
 258 void ds_put_c_vformat (struct string *st, const char *, va_list)
 259      PRINTF_FORMAT (2, 0);
 260
 261 void ds_put_format (struct string *, const char *, ...)
 262      PRINTF_FORMAT (2, 3);
 263 void ds_put_c_format (struct string *, const char *, ...)
 264      PRINTF_FORMAT (2, 3);
 265
 266 char *ds_put_uninit (struct string *st, size_t incr);
 267
 268 char *ds_splice_uninit (struct string *, size_t ofs, size_t old_len,
 269                         size_t new_len);
 270
 271 /* Other */
 272 /* calls relocate from gnulib on ST */
 273 void ds_relocate (struct string *st);
 274 char *relocate_clone (const char *);
 275 char *relocate_format (const char *, ...)
 276   PRINTF_FORMAT (1, 2) MALLOC_LIKE;
 277
 278 void u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
 279                        const uint8_t *src, size_t src_size,
 280                        char pad);
 281 \f
 282 static inline struct substring
 283 ss_empty (void)
 284 {
 285   struct substring ss;
 286   ss.string = NULL;
 287   ss.length = 0;
 288   return ss;
 289 }
 290
 291 /* Returns a substring whose contents are the given C-style
 292    string CSTR. */
 293 static inline struct substring
 294 ss_cstr (const char *cstr)
 295 {
 296   return ss_buffer (cstr, strlen (cstr));
 297 }
 298
 299 /* Returns a substring whose contents are the N characters in
 300    BUFFER. */
 301 static inline struct substring
 302 ss_buffer (const char *buffer, size_t n)
 303 {
 304   struct substring ss;
 305   ss.string = (char *) buffer;
 306   ss.length = n;
 307   return ss;
 308 }
 309
 310 static inline char *
 311 xstrdup_if_nonnull (const char *s)
 312 {
 313   return s ? xstrdup (s) : NULL;
 314 }
 315
 316 #endif /* str_h */