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 all backslash characters, '\' in a string, by inserting a second '\'.
 286 </para>
 287
 288 @source:
 289 @exceptions:
 290 @Returns: a newly allocated copy of @string, with all backslash characters
 291 escaped using a second backslash.
 292 <!-- # Unused Parameters # -->
 293 @string: a string to escape the backslashes in.
 294
 295
 296 <!-- ##### FUNCTION g_strcompress ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @source:
 302 @Returns:
 303
 304
 305 <!-- ##### FUNCTION g_strcanon ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @string:
 311 @valid_chars:
 312 @subsitutor:
 313 @Returns:
 314
 315
 316 <!-- ##### FUNCTION g_strsplit ##### -->
 317 <para>
 318 Splits a string into a maximum of @max_tokens pieces, using the given
 319 @delimiter. If @max_tokens is reached, the final string in the returned
 320 string array contains the remainder of @string.
 321 </para>
 322
 323 @string: a string to split.
 324 @delimiter: a string which specifies the places at which to split the string.
 325 The delimiter is not included in any of the resulting strings, unless
 326 max_tokens is reached.
 327 @max_tokens: the maximum number of strings to split @string into. If this is
 328 less than 1, the string is split completely.
 329 @Returns: a newly-allocated array of strings. Use g_strfreev() to free it.
 330
 331
 332 <!-- ##### FUNCTION g_strfreev ##### -->
 333 <para>
 334 Frees a NULL-terminated array of strings, and the array itself.
 335 </para>
 336
 337 @str_array: a NULL-terminated array of strings to free.
 338
 339
 340 <!-- ##### FUNCTION g_strconcat ##### -->
 341 <para>
 342 Concatenates all of the given strings into one long string.
 343 The returned string should be freed when no longer needed.
 344 </para>
 345
 346 @string1: The first string to add, which must not be NULL.
 347 @Varargs: a NULL-terminated list of strings to append to the string.
 348 @Returns: a newly-allocated string containing all the string arguments.
 349
 350
 351 <!-- ##### FUNCTION g_strjoin ##### -->
 352 <para>
 353 Joins a number of strings together to form one long string, with the optional
 354 @separator inserted between each of them.
 355 </para>
 356
 357 @separator: a string to insert between each of the strings, or NULL.
 358 @Varargs: a NULL-terminated list of strings to join.
 359 @Returns: a newly-allocated string containing all of the strings joined
 360 together, with @separator between them.
 361
 362
 363 <!-- ##### FUNCTION g_strjoinv ##### -->
 364 <para>
 365 Joins a number of strings together to form one long string, with the optional
 366 @separator inserted between each of them.
 367 </para>
 368
 369 @separator: a string to insert between each of the strings, or NULL.
 370 @str_array: a NULL-terminated array of strings to join.
 371 @Returns: a newly-allocated string containing all of the strings joined
 372 together, with @separator between them.
 373
 374
 375 <!-- ##### FUNCTION g_strerror ##### -->
 376 <para>
 377 Returns a string corresponding to the given error code, e.g. "no such process".
 378 This function is included since not all platforms support the
 379 <function>strerror()</function> function.
 380 </para>
 381
 382 @errnum: the system error number. See the standard C %errno
 383 documentation.
 384 @Returns: a string describing the error code.
 385 If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
 386 The string can only be used until the next call to g_strerror.
 387
 388
 389 <!-- ##### FUNCTION g_strsignal ##### -->
 390 <para>
 391 Returns a string describing the given signal, e.g. "Segmentation fault".
 392 This function is included since not all platforms support the
 393 <function>strsignal()</function> function.
 394 </para>
 395
 396 @signum: the signal number. See the <literal>signal</literal>
 397 documentation.
 398 @Returns: a string describing the signal.
 399 If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
 400 The string can only be used until the next call to g_strsignal.
 401
 402