docs/reference/glib/tmpl/string_utils.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 String Utility Functions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 various string-related functions.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 This section describes a number of utility functions for creating,
  10 duplicating, and manipulating strings.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### FUNCTION g_strdup ##### -->
  19 <para>
  20 Duplicates a string.
  21 The returned string should be freed when no longer needed.
  22 </para>
  23
  24 @str: the string to duplicate.
  25 @Returns: a newly-allocated copy of @str.
  26
  27
  28 <!-- ##### FUNCTION g_strndup ##### -->
  29 <para>
  30 Duplicates the first @n characters of a string, returning a newly-allocated
  31 buffer @n + 1 characters long which will always be null-terminated.
  32 If @str is less than @n characters long the buffer is padded with nulls.
  33 The returned value should be freed when no longer needed.
  34 </para>
  35
  36 @str: the string to duplicate part of.
  37 @n: the maximum number of characters to copy from @str.
  38 @Returns: a newly-allocated buffer containing the first @n characters of @str,
  39 null-terminated.
  40
  41
  42 <!-- ##### FUNCTION g_strnfill ##### -->
  43 <para>
  44 Creates a new string @length characters long filled with @fill_char.
  45 The returned string should be freed when no longer needed.
  46 </para>
  47
  48 @length: the length of the new string.
  49 @fill_char: the character to fill the string with.
  50 @Returns: a newly-allocated string filled the @fill_char.
  51
  52
  53 <!-- ##### FUNCTION g_strlcpy ##### -->
  54 <para>
  55
  56 </para>
  57
  58 @dest:
  59 @src:
  60 @dest_size:
  61 @Returns:
  62
  63
  64 <!-- ##### FUNCTION g_strlcat ##### -->
  65 <para>
  66
  67 </para>
  68
  69 @dest:
  70 @src:
  71 @dest_size:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION g_strdup_printf ##### -->
  76 <para>
  77 Similar to the standard C <function>sprintf()</function> function
  78 but safer, since it calculates the maximum space required and allocates
  79 memory to hold the result.
  80 The returned string should be freed when no longer needed.
  81 </para>
  82
  83 @format: the standard <function>sprintf()</function> format string.
  84 @Varargs: the parameters to insert into the format string.
  85 @Returns: a newly-allocated string holding the result.
  86
  87
  88 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
  89 <para>
  90 Similar to the standard C <function>vsprintf()</function> function
  91 but safer, since it calculates the maximum space required and allocates
  92 memory to hold the result.
  93 The returned string should be freed when no longer needed.
  94 </para>
  95
  96 @format: the standard <function>sprintf()</function> format string.
  97 @args: the list of parameters to insert into the format string.
  98 @Returns: a newly-allocated string holding the result.
  99
 100
 101 <!-- ##### FUNCTION g_snprintf ##### -->
 102 <para>
 103 A safer form of the standard <function>sprintf()</function> function.
 104 The output is guaranteed to not exceed @n characters (including the
 105 terminating NULL character), so it is easy to ensure that a buffer overflow
 106 cannot occur.
 107 </para>
 108 <para>
 109 See also g_strdup_printf().
 110 </para>
 111 <note>
 112 <para>
 113 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 114 was truncated, and the truncated string may not be NULL-terminated.
 115 </para>
 116 </note>
 117
 118 @string: the buffer to hold the output.
 119 @n: the maximum number of characters to produce (including the terminating null
 120 character).
 121 @format: the format string. See the <function>sprintf()</function>
 122 documentation.
 123 @Varargs: the arguments to insert in the output.
 124 @Returns: the length of the output string.
 125
 126
 127 <!-- ##### FUNCTION g_vsnprintf ##### -->
 128 <para>
 129 A safer form of the standard <function>vsprintf()</function> function.
 130 The output is guaranteed to not exceed @n characters (including the
 131 terminating NULL character), so it is easy to ensure that a buffer overflow
 132 cannot occur.
 133 </para>
 134 <para>
 135 See also g_strdup_vprintf().
 136 </para>
 137 <note>
 138 <para>
 139 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 140 was truncated, and the truncated string may not be NULL-terminated.
 141 </para>
 142 </note>
 143
 144 @string: the buffer to hold the output.
 145 @n: the maximum number of characters to produce (including the terminating null
 146 character).
 147 @format: the format string. See the <function>sprintf()</function>
 148 documentation.
 149 @args: the list of arguments to insert in the output.
 150 @Returns: the length of the output string.
 151
 152
 153 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
 154 <para>
 155 Calculates the maximum space needed to store the output of the
 156 <function>sprintf()</function> function.
 157 </para>
 158
 159 @format: the format string. See the <function>printf()</function>
 160 documentation.
 161 @args: the parameters to be inserted into the format string.
 162 @Returns: the maximum space needed to store the formatted string.
 163
 164
 165 <!-- ##### FUNCTION g_strup ##### -->
 166 <para>
 167 Converts a string to upper case.
 168 </para>
 169
 170 @string: the string to convert.
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION g_strdown ##### -->
 175 <para>
 176 Converts a string to lower case.
 177 </para>
 178
 179 @string: the string to convert.
 180 @Returns:
 181
 182
 183 <!-- ##### FUNCTION g_strcasecmp ##### -->
 184 <para>
 185 A case-insensitive string comparison, corresponding to the standard
 186 <function>strcasecmp()</function> function on platforms which support it.
 187 </para>
 188
 189 @s1: a string.
 190 @s2: a string to compare with @s1.
 191 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 192 value if @s1 > @s2.
 193
 194
 195 <!-- ##### FUNCTION g_strncasecmp ##### -->
 196 <para>
 197 A case-insensitive string comparison, corresponding to the standard
 198 <function>strncasecmp()</function> function on platforms which support it.
 199 It is similar to g_strcasecmp() except it only compares the first @n characters
 200 of the strings.
 201 </para>
 202
 203 @s1: a string.
 204 @s2: a string to compare with @s1.
 205 @n: the maximum number of characters to compare.
 206 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 207 value if @s1 > @s2.
 208
 209
 210 <!-- ##### FUNCTION g_strreverse ##### -->
 211 <para>
 212 Reverses all of the characters in a string.
 213 For example, g_strreverse ("abcdef") would be "fedcba".
 214 </para>
 215
 216 @string: the string to reverse.
 217 @Returns:
 218
 219
 220 <!-- ##### FUNCTION g_strtod ##### -->
 221 <para>
 222 Converts a string to a gdouble value.
 223 It calls the standard <function>strtod()</function> function
 224 to handle the conversion, but if the string is not completely converted
 225 it attempts the conversion again in the "C" locale, and returns the best
 226 match.
 227 </para>
 228
 229 @nptr: the string to convert to a numeric value.
 230 @endptr: if non-NULL, it returns the character after the last character used
 231 in the conversion.
 232 @Returns: the gdouble value.
 233
 234
 235 <!-- ##### FUNCTION g_strchug ##### -->
 236 <para>
 237 Removes leading whitespace from a string, by moving the rest of the
 238 characters forward.
 239 </para>
 240
 241 @string: a string to remove the leading whitespace from.
 242 @Returns: @string.
 243
 244
 245 <!-- ##### FUNCTION g_strchomp ##### -->
 246 <para>
 247 Removes trailing whitespace from a string.
 248 </para>
 249
 250 @string: a string to remove the trailing whitespace from.
 251 @Returns: @string.
 252
 253
 254 <!-- ##### MACRO g_strstrip ##### -->
 255 <para>
 256 Removes leading and trailing whitespace from a string.
 257 </para>
 258
 259 @string: a string to remove the leading and trailing whitespace from.
 260
 261
 262 <!-- ##### FUNCTION g_strdelimit ##### -->
 263 <para>
 264 Converts any delimiter characters in @string to @new_delimiter.
 265 Any characters in @string which are found in @delimiters are changed
 266 to the @new_delimiter character.
 267 </para>
 268
 269 @string: the string to convert.
 270 @delimiters: a string containing the current delimiters, or NULL to use the
 271 standard delimiters defined in #G_STR_DELIMITERS.
 272 @new_delimiter: the new delimiter character.
 273 @Returns:
 274
 275
 276 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
 277 <para>
 278 The standard delimiters, used in #g_strdelimit.
 279 </para>
 280
 281
 282
 283 <!-- ##### FUNCTION g_strescape ##### -->
 284 <para>
 285 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
 286 '&quot;' in the string @source by inserting a '\' before
 287 them. Additionally all characters in the range 0x01-0x1F (everything
 288 below SPACE) and in the range 0x80-0xFF (all non-ASCII chars) are
 289 replaced with a '\' followed by their octal representation. Characters
 290 supplied in @exceptions are not escaped.
 291 </para>
 292
 293 <para>
 294 g_strcompress() does the reverse conversion.
 295 </para>
 296
 297 @source: a string to escape.
 298 @exceptions: a string of characters not to escape in @source.
 299 @Returns: a newly allocated copy of @source with certain
 300 characters escaped. See above.
 301
 302
 303 <!-- ##### FUNCTION g_strcompress ##### -->
 304 <para>
 305 Replaces all escaped characters with their one byte equivalent. It
 306 does the reverse conversion of g_strescape().
 307 </para>
 308
 309 @source: a string to compress.
 310 @Returns: a newly allocated copy of @source with all escaped
 311 character compressed.
 312
 313
 314 <!-- ##### FUNCTION g_strcanon ##### -->
 315 <para>
 316
 317 </para>
 318
 319 @string:
 320 @valid_chars:
 321 @subsitutor:
 322 @Returns:
 323
 324
 325 <!-- ##### FUNCTION g_strsplit ##### -->
 326 <para>
 327 Splits a string into a maximum of @max_tokens pieces, using the given
 328 @delimiter. If @max_tokens is reached, the final string in the returned
 329 string array contains the remainder of @string.
 330 </para>
 331
 332 @string: a string to split.
 333 @delimiter: a string which specifies the places at which to split the string.
 334 The delimiter is not included in any of the resulting strings, unless
 335 max_tokens is reached.
 336 @max_tokens: the maximum number of strings to split @string into. If this is
 337 less than 1, the string is split completely.
 338 @Returns: a newly-allocated array of strings. Use g_strfreev() to free it.
 339
 340
 341 <!-- ##### FUNCTION g_strfreev ##### -->
 342 <para>
 343 Frees a NULL-terminated array of strings, and the array itself.
 344 </para>
 345
 346 @str_array: a NULL-terminated array of strings to free.
 347
 348
 349 <!-- ##### FUNCTION g_strconcat ##### -->
 350 <para>
 351 Concatenates all of the given strings into one long string.
 352 The returned string should be freed when no longer needed.
 353 </para>
 354
 355 @string1: The first string to add, which must not be NULL.
 356 @Varargs: a NULL-terminated list of strings to append to the string.
 357 @Returns: a newly-allocated string containing all the string arguments.
 358
 359
 360 <!-- ##### FUNCTION g_strjoin ##### -->
 361 <para>
 362 Joins a number of strings together to form one long string, with the optional
 363 @separator inserted between each of them.
 364 </para>
 365
 366 @separator: a string to insert between each of the strings, or NULL.
 367 @Varargs: a NULL-terminated list of strings to join.
 368 @Returns: a newly-allocated string containing all of the strings joined
 369 together, with @separator between them.
 370
 371
 372 <!-- ##### FUNCTION g_strjoinv ##### -->
 373 <para>
 374 Joins a number of strings together to form one long string, with the optional
 375 @separator inserted between each of them.
 376 </para>
 377
 378 @separator: a string to insert between each of the strings, or NULL.
 379 @str_array: a NULL-terminated array of strings to join.
 380 @Returns: a newly-allocated string containing all of the strings joined
 381 together, with @separator between them.
 382
 383
 384 <!-- ##### FUNCTION g_strerror ##### -->
 385 <para>
 386 Returns a string corresponding to the given error code, e.g. "no such process".
 387 This function is included since not all platforms support the
 388 <function>strerror()</function> function.
 389 </para>
 390
 391 @errnum: the system error number. See the standard C %errno
 392 documentation.
 393 @Returns: a string describing the error code.
 394 If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
 395 The string can only be used until the next call to g_strerror.
 396
 397
 398 <!-- ##### FUNCTION g_strsignal ##### -->
 399 <para>
 400 Returns a string describing the given signal, e.g. "Segmentation fault".
 401 This function is included since not all platforms support the
 402 <function>strsignal()</function> function.
 403 </para>
 404
 405 @signum: the signal number. See the <literal>signal</literal>
 406 documentation.
 407 @Returns: a string describing the signal.
 408 If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
 409 The string can only be used until the next call to g_strsignal.
 410
 411