From 1858c03571a12a996e90c45fd3583dd9abf45557 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 1 Jul 2003 22:15:54 +0000 Subject: [PATCH] Broken pipe... --- docs/reference/glib/tmpl/string_utils.sgml | 67 ++++++++++++++++++------------ 1 file changed, 40 insertions(+), 27 deletions(-) diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index b08e4e9..1464c04 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -16,7 +16,20 @@ the header gprintf.h which is not included in glib.h (otherwise using glib.h would drag in stdio.h), so you'll have to explicitly include <glib/gprintf.h> -in order to use the printf() functions. +in order to use the GLib printf() functions. + + +While you may use the printf() functions to format UTF-8 strings, notice that +the precision of a %Ns parameter is interpreted as the +number of bytes, not characters to print. +On top of that, the GNU libc implementation of the printf() functions has the "feature" +that it checks that the string given for the %Ns parameter +consists of a whole number of characters in the current encoding. So, unless you +are sure you are always going to be in an UTF-8 locale or your know your text is restricted +to ASCII, avoid using %Ns. +If your intention is to format strings for a certain number of columns, then +%Ns is not a correct solution anyway, since it fails to take +wide characters (see g_unichar_iswide()) into account. @@ -149,10 +162,10 @@ an even better idea. -Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing +Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing nul-termination for @dest. The total size of @dest won't exceed -@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or -strncat(), but for real security g_strconcat() is harder to mess up. +@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or +strncat(), but for real security g_strconcat() is harder to mess up. @dest: destination buffer, already containing one nul-terminated string @@ -163,20 +176,21 @@ nul-termination for @dest. The total size of @dest won't exceed -Similar to the standard C sprintf() function +Similar to the standard C sprintf() function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed. -@format: the standard sprintf() format string. +@format: a standard printf() format string, but notice + string precision pitfalls. @Varargs: the parameters to insert into the format string. @Returns: a newly-allocated string holding the result. -Similar to the standard C vsprintf() function +Similar to the standard C vsprintf() function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed. @@ -186,7 +200,8 @@ See also g_vasprintf(), which offers the same functionality, but additionally returns the length of the allocated string. -@format: the standard sprintf() format string. +@format: a standard printf() format string, but notice + string precision pitfalls. @args: the list of parameters to insert into the format string. @Returns: a newly-allocated string holding the result. @@ -290,12 +305,10 @@ returns the length of the allocated string. -Calculates the maximum space needed to store the output of the -sprintf() function. +Calculates the maximum space needed to store the output of the sprintf() function. -@format: the format string. See the printf() -documentation. +@format: the format string. See the printf() documentation. @args: the parameters to be inserted into the format string. @Returns: the maximum space needed to store the formatted string. @@ -305,7 +318,7 @@ documentation. Determines whether a character is alphanumeric. -Unlike the standard C library isalnum() function, this only +Unlike the standard C library isalnum() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -322,7 +335,7 @@ possibly non-ASCII character in. Determines whether a character is alphabetic (i.e. a letter). -Unlike the standard C library isalpha() function, this only +Unlike the standard C library isalpha() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -339,7 +352,7 @@ possibly non-ASCII character in. Determines whether a character is a control character. -Unlike the standard C library iscntrl() function, this only +Unlike the standard C library iscntrl() function, this only recognizes standard ASCII control characters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -356,7 +369,7 @@ possibly non-ASCII character in. Determines whether a character is digit (0-9). -Unlike the standard C library isdigit() function, +Unlike the standard C library isdigit() function, this takes a char, not an int, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. @@ -371,7 +384,7 @@ non-ASCII character in. Determines whether a character is a printing character and not a space. -Unlike the standard C library isgraph() function, +Unlike the standard C library isgraph() function, this only recognizes standard ASCII characters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -388,7 +401,7 @@ possibly non-ASCII character in. Determines whether a character is an ASCII lower case letter. -Unlike the standard C library islower() function, +Unlike the standard C library islower() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -405,7 +418,7 @@ before passing a possibly non-ASCII character in. Determines whether a character is a printing character. -Unlike the standard C library isprint() function, +Unlike the standard C library isprint() function, this only recognizes standard ASCII characters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -422,7 +435,7 @@ possibly non-ASCII character in. Determines whether a character is a punctuation character. -Unlike the standard C library ispunct() function, +Unlike the standard C library ispunct() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -439,7 +452,7 @@ possibly non-ASCII character in. Determines whether a character is a white-space character. -Unlike the standard C library isspace() function, +Unlike the standard C library isspace() function, this only recognizes standard ASCII white-space and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -456,7 +469,7 @@ possibly non-ASCII character in. Determines whether a character is an ASCII upper case letter. -Unlike the standard C library isupper() function, +Unlike the standard C library isupper() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard library function, this takes a char, not an int, @@ -473,7 +486,7 @@ before passing a possibly non-ASCII character in. Determines whether a character is a hexadecimal-digit character. -Unlike the standard C library isxdigit() function, +Unlike the standard C library isxdigit() function, this takes a char, not an int, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. @@ -623,7 +636,7 @@ Reverses all of the bytes in a string. For example, g_strreverse ("abcdef") will result in "fedcba". -Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. +Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use g_utf8_strreverse(). @string: the string to reverse. @@ -811,7 +824,7 @@ nesting such as g_ascii_strup (g_strcanon (str, "abc", '?')). -@str_array: +@str_array: @@ -855,7 +868,7 @@ together, with @separator between them. Returns a string corresponding to the given error code, e.g. "no such process". This function is included since not all platforms support the -strerror() function. +strerror() function. @errnum: the system error number. See the standard C %errno @@ -869,7 +882,7 @@ The string can only be used until the next call to g_strerror. Returns a string describing the given signal, e.g. "Segmentation fault". This function is included since not all platforms support the -strsignal() function. +strsignal() function. @signum: the signal number. See the signal -- 2.7.4