src/libpspp/str.h

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