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