1 /* Dynamically allocated strings 2 3 Copyright (c) 2001-2012 Free Software Foundation, Inc. 4 5 This file is part of GNU Zile. 6 7 GNU Zile is free software; you can redistribute it and/or modify it 8 under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 3, or (at your option) 10 any later version. 11 12 GNU Zile is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with GNU Zile; see the file COPYING. If not, write to the 19 Free Software Foundation, Fifth Floor, 51 Franklin Street, Boston, 20 MA 02111-1301, USA. */ 21 22 #ifndef ASTR_H 23 #define ASTR_H 24 25 #include <stddef.h> 26 #include <stdio.h> 27 #include <stdarg.h> 28 29 /* 30 * The astr library provides dynamically allocated null-terminated C 31 * strings. 32 * 33 * The string type, astr, is a pointer type. 34 * 35 * String positions start at zero, as with ordinary C strings. 36 * 37 * Where not otherwise specified, the functions return the first 38 * argument string, usually named as in the function prototype. 39 */ 40 41 /* 42 * The opaque string type. 43 */ 44 typedef struct astr *astr; 45 typedef struct astr const *const_astr; 46 47 /* 48 * Allocate a new string with zero length. 49 */ 50 astr astr_new (void); 51 52 /* 53 * Make a new string from a C null-terminated string. 54 */ 55 astr astr_new_cstr (const char *s); 56 57 /* 58 * Make a new constant string from a counted C string. 59 */ 60 const_astr const_astr_new_nstr (const char *s, size_t n); 61 62 /* 63 * Convert as into a C null-terminated string. 64 * as[0] to as[astr_len (as) - 1] inclusive may be read. 65 */ 66 _GL_ATTRIBUTE_PURE const char *astr_cstr (const_astr as); 67 68 /* 69 * Return the length of the argument string `as'. 70 */ 71 _GL_ATTRIBUTE_PURE size_t astr_len (const_astr as); 72 73 /* 74 * Return the `pos'th character of `as'. 75 */ 76 _GL_ATTRIBUTE_PURE char astr_get (const_astr as, size_t pos); 77 78 /* 79 * Return a new astr consisting of `size' characters from string `as' 80 * starting from position `pos'. 81 */ 82 astr astr_substr (const_astr as, size_t pos, size_t size); 83 84 /* 85 * Assign the contents of the argument string to the string `as'. 86 */ 87 astr astr_cpy (astr as, const_astr src); 88 astr astr_cpy_cstr (astr as, const char *s); 89 90 /* 91 * Append the contents of the argument string or character to `as'. 92 */ 93 astr astr_cat (astr as, const_astr src); 94 astr astr_cat_cstr (astr as, const char *s); 95 astr astr_cat_nstr (astr as, const char *s, size_t len); 96 astr astr_cat_char (astr as, int c); 97 98 /* 99 * Overwrite `size' characters of `as', starting at `pos', with the 100 * argument string. 101 */ 102 astr astr_replace_nstr (astr as, size_t pos, const char *s, size_t size); 103 104 /* 105 * Remove `size' chars from `as' at position `pos'. 106 */ 107 astr astr_remove (astr as, size_t pos, size_t size); 108 109 /* 110 * Insert gap of `size' characters in `as' at position `pos'. 111 */ 112 astr astr_insert (astr as, size_t pos, size_t size); 113 114 /* 115 * Move `n' chars in `as' from position `from' to `to'. 116 */ 117 astr astr_move (astr as, size_t to, size_t from, size_t n); 118 119 /* 120 * Set `n' chars in `as' at position `pos' to `c'. 121 */ 122 astr astr_set (astr as, size_t pos, int c, size_t n); 123 124 /* 125 * Truncate `as' to position `pos'. 126 */ 127 astr astr_truncate (astr as, size_t pos); 128 129 /* 130 * Read file contents into an astr. 131 * Returns NULL if the file doesn't exist, or other error. 132 */ 133 astr astr_readf (const char *filename); 134 135 /* 136 * Format text into a string and return it. 137 */ 138 _GL_ATTRIBUTE_FORMAT_PRINTF(1, 0) astr astr_vfmt (const char *fmt, va_list ap); 139 _GL_ATTRIBUTE_FORMAT_PRINTF(1, 2) astr astr_fmt (const char *fmt, ...); 140 141 /* Enumeration for casing. */ 142 typedef enum { 143 case_upper = 1, 144 case_lower, 145 case_capitalized, 146 } casing; 147 148 /* 149 * Recase as according to newcase. 150 */ 151 astr astr_recase (astr as, casing newcase); 152 153 #endif /* !ASTR_H */ 154