docs/reference/glib/tmpl/strings.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Strings
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 text buffers which grow automatically as text is added.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GString is similar to a standard C string, except that it grows automatically
  10 as text is appended or inserted. Also, it stores the length of the string, so
  11 can be used for binary data with embedded nul bytes.
  12 </para>
  13
  14 <!-- ##### SECTION See_Also ##### -->
  15 <para>
  16
  17 </para>
  18
  19 <!-- ##### SECTION Stability_Level ##### -->
  20
  21
  22 <!-- ##### STRUCT GString ##### -->
  23 <para>
  24 The #GString struct contains the public fields of a #GString.
  25 The <structfield>str</structfield> field points to the character data.
  26 It may move as text is added.
  27 The <structfield>len</structfield> field contains the length of the string,
  28 not including the terminating nul byte.
  29 </para>
  30 <para>
  31 The <structfield>str</structfield> field is nul-terminated and so can be used as an ordinary C
  32 string. But it may be moved when text is appended or inserted into the
  33 string.
  34 </para>
  35
  36 @str:
  37 @len:
  38 @allocated_len:
  39
  40 <!-- ##### FUNCTION g_string_new ##### -->
  41 <para>
  42 Creates a new #GString, initialized with the given string.
  43 </para>
  44
  45 @init: the initial text to copy into the string.
  46 @Returns: the new #GString.
  47
  48
  49 <!-- ##### FUNCTION g_string_new_len ##### -->
  50 <para>
  51 Creates a new #GString with @len bytes of the @init buffer.  Because a length is
  52 provided, @init need not be nul-terminated, and can contain embedded nul bytes.
  53 </para>
  54
  55 @init: initial contents of string.
  56 @len: length of @init to use.
  57 @Returns: a new #GString.
  58
  59
  60 <!-- ##### FUNCTION g_string_sized_new ##### -->
  61 <para>
  62 Creates a new #GString, with enough space for @dfl_size bytes.
  63 This is useful if you are going to add a lot of text to the string and
  64 don't want it to be reallocated too often.
  65 </para>
  66
  67 @dfl_size: the default size of the space allocated to hold the string.
  68 @Returns: the new #GString.
  69
  70
  71 <!-- ##### FUNCTION g_string_assign ##### -->
  72 <para>
  73 Copies the bytes from a string into a #GString, destroying any previous
  74 contents. It is rather like the standard strcpy() function, except that
  75 you do not have to worry about having enough space to copy the string.
  76 </para>
  77
  78 @string: the destination #GString. Its current contents are destroyed.
  79 @rval: the string to copy into @string
  80 @Returns: the destination #GString.
  81 <!-- # Unused Parameters # -->
  82 @val: the string to copy into @string.
  83
  84
  85 <!-- ##### MACRO g_string_sprintf ##### -->
  86 <para>
  87 Writes a formatted string into a #GString.
  88 This is similar to the standard sprintf() function,
  89 except that the #GString buffer automatically expands to contain the results.
  90 The previous contents of the #GString are destroyed.
  91 </para>
  92
  93 @Deprecated: This function has been renamed to g_string_printf().
  94 @string: a #GString.
  95 @format: the string format. See the sprintf() documentation.
  96 @Varargs: the parameters to insert into the format string.
  97
  98
  99 <!-- ##### MACRO g_string_sprintfa ##### -->
 100 <para>
 101 Appends a formatted string onto the end of a #GString.
 102 This function is is similar to g_string_sprintf() except that
 103 the text is appended to the #GString.
 104 </para>
 105
 106 @Deprecated: This function has been renamed to g_string_append_printf().
 107 @string: a #GString.
 108 @format: the string format. See the sprintf() documentation.
 109 @Varargs: the parameters to insert into the format string.
 110
 111
 112 <!-- ##### FUNCTION g_string_printf ##### -->
 113 <para>
 114 Writes a formatted string into a #GString.
 115 This is similar to the standard sprintf() function,
 116 except that the #GString buffer automatically expands to contain the results.
 117 The previous contents of the #GString are destroyed.
 118 </para>
 119
 120 @string: a #GString.
 121 @format: the string format. See the printf() documentation.
 122 @Varargs: the parameters to insert into the format string.
 123
 124
 125 <!-- ##### FUNCTION g_string_append_printf ##### -->
 126 <para>
 127 Appends a formatted string onto the end of a #GString.
 128 This function is is similar to g_string_printf() except that
 129 the text is appended to the #GString.
 130 </para>
 131
 132 @string: a #GString.
 133 @format: the string format. See the printf() documentation.
 134 @Varargs: the parameters to insert into the format string.
 135
 136
 137 <!-- ##### FUNCTION g_string_append ##### -->
 138 <para>
 139 Adds a string onto the end of a #GString, expanding it if necessary.
 140 </para>
 141
 142 @string: a #GString.
 143 @val: the string to append onto the end of the #GString.
 144 @Returns: the #GString.
 145
 146
 147 <!-- ##### FUNCTION g_string_append_c ##### -->
 148 <para>
 149 Adds a byte onto the end of a #GString, expanding it if necessary.
 150 </para>
 151
 152 @string: a #GString.
 153 @c: the byte to append onto the end of the #GString.
 154 @Returns: the #GString.
 155
 156
 157 <!-- ##### FUNCTION g_string_append_unichar ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @string:
 163 @wc:
 164 @Returns:
 165
 166
 167 <!-- ##### FUNCTION g_string_append_len ##### -->
 168 <para>
 169 Appends @len bytes of @val to @string. Because @len is provided,
 170 @val may contain embedded nuls and need not be nul-terminated.
 171 </para>
 172
 173 @string: a #GString.
 174 @val: bytes to append.
 175 @len: number of bytes of @val to use.
 176 @Returns: the #GString.
 177
 178
 179 <!-- ##### FUNCTION g_string_prepend ##### -->
 180 <para>
 181 Adds a string on to the start of a #GString, expanding it if necessary.
 182 </para>
 183
 184 @string: a #GString.
 185 @val: the string to prepend on the start of the #GString.
 186 @Returns: the #GString.
 187
 188
 189 <!-- ##### FUNCTION g_string_prepend_c ##### -->
 190 <para>
 191 Adds a byte onto the start of a #GString, expanding it if necessary.
 192 </para>
 193
 194 @string: a #GString.
 195 @c: the byte to prepend on the start of the #GString.
 196 @Returns: the #GString.
 197
 198
 199 <!-- ##### FUNCTION g_string_prepend_unichar ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @string:
 205 @wc:
 206 @Returns:
 207
 208
 209 <!-- ##### FUNCTION g_string_prepend_len ##### -->
 210 <para>
 211 Prepends @len bytes of @val to @string. Because @len is provided,
 212 @val may contain embedded nuls and need not be nul-terminated.
 213 </para>
 214
 215 @string: a #GString.
 216 @val: bytes to prepend.
 217 @len: number of bytes in @val to prepend.
 218 @Returns: the #GString passed in.
 219
 220
 221 <!-- ##### FUNCTION g_string_insert ##### -->
 222 <para>
 223 Inserts a copy of a string into a #GString, expanding it if necessary.
 224 </para>
 225
 226 @string: a #GString.
 227 @pos: the position to insert the copy of the string.
 228 @val: the string to insert.
 229 @Returns: the #GString.
 230
 231
 232 <!-- ##### FUNCTION g_string_insert_c ##### -->
 233 <para>
 234 Inserts a byte into a #GString, expanding it if necessary.
 235 </para>
 236
 237 @string: a #GString.
 238 @pos: the position to insert the byte.
 239 @c: the byte to insert.
 240 @Returns: the #GString.
 241
 242
 243 <!-- ##### FUNCTION g_string_insert_unichar ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @string:
 249 @pos:
 250 @wc:
 251 @Returns:
 252
 253
 254 <!-- ##### FUNCTION g_string_insert_len ##### -->
 255 <para>
 256 Inserts @len bytes of @val into @string at @pos.  Because @len is provided, @val
 257  may contain embedded nuls and need not be nul-terminated. If @pos is -1, bytes are inserted at the end of the string.
 258 </para>
 259
 260 @string: a #GString.
 261 @pos: position in @string where insertion should happen, or -1 for at the end.
 262 @val: bytes to insert.
 263 @len: number of bytes of @val to insert.
 264 @Returns: the #GString.
 265
 266
 267 <!-- ##### FUNCTION g_string_erase ##### -->
 268 <para>
 269 Removes @len bytes from a #GString, starting at position @pos.
 270 The rest of the #GString is shifted down to fill the gap.
 271 </para>
 272
 273 @string: a #GString.
 274 @pos: the position of the content to remove.
 275 @len: the number of bytes to remove, or -1 to remove all
 276       following bytes.
 277 @Returns: the #GString.
 278
 279
 280 <!-- ##### FUNCTION g_string_truncate ##### -->
 281 <para>
 282 Cuts off the end of the GString, leaving the first @len bytes.
 283 </para>
 284
 285 @string: a #GString.
 286 @len: the new size of the #GString.
 287 @Returns: the #GString.
 288
 289
 290 <!-- ##### FUNCTION g_string_set_size ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @string:
 296 @len:
 297 @Returns:
 298
 299
 300 <!-- ##### FUNCTION g_string_free ##### -->
 301 <para>
 302 Frees the memory allocated for the #GString.
 303 If @free_segment is %TRUE it also frees the character data.
 304 </para>
 305
 306 @string: a #GString.
 307 @free_segment: if %TRUE the actual character data is freed as well.
 308 @Returns: the character data of @string (i.e. %NULL if @free_segment is %TRUE)
 309
 310
 311 <!-- ##### FUNCTION g_string_up ##### -->
 312 <para>
 313 </para>
 314
 315 @string:
 316 @Returns:
 317
 318
 319 <!-- ##### FUNCTION g_string_down ##### -->
 320 <para>
 321 </para>
 322
 323 @string:
 324 @Returns:
 325
 326
 327 <!-- ##### FUNCTION g_string_hash ##### -->
 328 <para>
 329 Creates a hash code for @str; for use with #GHashTable.
 330 </para>
 331
 332 @str: a string to hash.
 333 @Returns: hash code for @str.
 334
 335
 336 <!-- ##### FUNCTION g_string_equal ##### -->
 337 <para>
 338 Compares two strings for equality, returning %TRUE if they are equal.
 339 For use with #GHashTable.
 340 </para>
 341
 342 @v: a #GString.
 343 @v2: another #GString.
 344 @Returns: %TRUE if they strings are the same length and contain the same bytes.
 345
 346