GLib Reference Manual
<<< Previous PageHomeUpNext Page >>>

String Utility Functions

Name

String Utility Functions -- various string-related functions.

Synopsis


#include <glib.h>


gchar*      g_strdup                        (const gchar *str);
gchar*      g_strndup                       (const gchar *str,
                                             guint n);
gchar*      g_strnfill                      (guint length,
                                             gchar fill_char);

gchar*      g_strdup_printf                 (const gchar *format,
                                             ...);
gchar*      g_strdup_vprintf                (const gchar *format,
                                             va_list args);
gint        g_snprintf                      (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             ...);
gint        g_vsnprintf                     (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             va_list args);
guint       g_printf_string_upper_bound     (const gchar *format,
                                             va_list args);

void        g_strup                         (gchar *string);
void        g_strdown                       (gchar *string);

gint        g_strcasecmp                    (const gchar *s1,
                                             const gchar *s2);
gint        g_strncasecmp                   (const gchar *s1,
                                             const gchar *s2,
                                             guint n);

void        g_strreverse                    (gchar *string);
gdouble     g_strtod                        (const gchar *nptr,
                                             gchar **endptr);

gchar*      g_strchug                       (gchar *string);
gchar*      g_strchomp                      (gchar *string);
#define     g_strstrip                      ( string )

gchar*      g_strdelimit                    (gchar *string,
                                             const gchar *delimiters,
                                             gchar new_delimiter);
#define     G_STR_DELIMITERS
gchar*      g_strescape                     (gchar *string);
gchar**     g_strsplit                      (const gchar *string,
                                             const gchar *delimiter,
                                             gint max_tokens);
void        g_strfreev                      (gchar **str_array);
gchar*      g_strconcat                     (const gchar *string1,
                                             ...);
gchar*      g_strjoin                       (const gchar *separator,
                                             ...);
gchar*      g_strjoinv                      (const gchar *separator,
                                             gchar **str_array);

gchar*      g_strerror                      (gint errnum);
gchar*      g_strsignal                     (gint signum);

Description

This section describes a number of utility functions for creating, duplicating, and manipulating strings.

Details

g_strdup ()

gchar*      g_strdup                        (const gchar *str);

Duplicates a string. The returned string should be freed when no longer needed.

str :the string to duplicate.
Returns :a newly-allocated copy of str.

g_strndup ()

gchar*      g_strndup                       (const gchar *str,
                                             guint n);

Duplicates the first n characters of a string, returning a newly-allocated buffer n + 1 characters long which will always be null-terminated. If str is less than n characters long the buffer is padded with nulls. The returned value should be freed when no longer needed.

str :the string to duplicate part of.
n :the maximum number of characters to copy from str.
Returns :a newly-allocated buffer containing the first n characters of str, null-terminated.

g_strnfill ()

gchar*      g_strnfill                      (guint length,
                                             gchar fill_char);

Creates a new string length characters long filled with fill_char. The returned string should be freed when no longer needed.

length :the length of the new string.
fill_char :the character to fill the string with.
Returns :a newly-allocated string filled the fill_char.

g_strdup_printf ()

gchar*      g_strdup_printf                 (const gchar *format,
                                             ...);

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.
... :the parameters to insert into the format string.
Returns :a newly-allocated string holding the result.

g_strdup_vprintf ()

gchar*      g_strdup_vprintf                (const gchar *format,
                                             va_list args);

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.

format :the standard sprintf() format string.
args :the list of parameters to insert into the format string.
Returns :a newly-allocated string holding the result.

g_snprintf ()

gint        g_snprintf                      (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             ...);

A safer form of the standard sprintf() function. The output is guaranteed to not exceed n characters (including the terminating NULL character), so it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_printf().

Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be NULL-terminated.

string :the buffer to hold the output.
n :the maximum number of characters to produce (including the terminating null character).
format :the format string. See the sprintf() documentation.
... :the arguments to insert in the output.
Returns :the length of the output string.

g_vsnprintf ()

gint        g_vsnprintf                     (gchar *string,
                                             gulong n,
                                             gchar const *format,
                                             va_list args);

A safer form of the standard vsprintf() function. The output is guaranteed to not exceed n characters (including the terminating NULL character), so it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_vprintf().

Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be NULL-terminated.

string :the buffer to hold the output.
n :the maximum number of characters to produce (including the terminating null character).
format :the format string. See the sprintf() documentation.
args :the list of arguments to insert in the output.
Returns :the length of the output string.

g_printf_string_upper_bound ()

guint       g_printf_string_upper_bound     (const gchar *format,
                                             va_list args);

Calculates the maximum space needed to store the output of the sprintf() function.

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.

g_strup ()

void        g_strup                         (gchar *string);

Converts a string to upper case.

string :the string to convert.

g_strdown ()

void        g_strdown                       (gchar *string);

Converts a string to lower case.

string :the string to convert.

g_strcasecmp ()

gint        g_strcasecmp                    (const gchar *s1,
                                             const gchar *s2);

A case-insensitive string comparison, corresponding to the standard strcasecmp() function on platforms which support it.

s1 :a string.
s2 :a string to compare with s1.
Returns :0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

g_strncasecmp ()

gint        g_strncasecmp                   (const gchar *s1,
                                             const gchar *s2,
                                             guint n);

A case-insensitive string comparison, corresponding to the standard strncasecmp() function on platforms which support it. It is similar to g_strcasecmp() except it only compares the first n characters of the strings.

s1 :a string.
s2 :a string to compare with s1.
n :the maximum number of characters to compare.
Returns :0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

g_strreverse ()

void        g_strreverse                    (gchar *string);

Reverses all of the characters in a string. For example, g_strreverse ("abcdef") would be "fedcba".

string :the string to reverse.

g_strtod ()

gdouble     g_strtod                        (const gchar *nptr,
                                             gchar **endptr);

Converts a string to a gdouble value. It calls the standard strtod() function to handle the conversion, but if the string is not completely converted it attempts the conversion again in the "C" locale, and returns the best match.

nptr :the string to convert to a numeric value.
endptr :if non-NULL, it returns the character after the last character used in the conversion.
Returns :the gdouble value.

g_strchug ()

gchar*      g_strchug                       (gchar *string);

Removes leading whitespace from a string, by moving the rest of the characters forward.

string :a string to remove the leading whitespace from.
Returns :string.

g_strchomp ()

gchar*      g_strchomp                      (gchar *string);

Removes trailing whitespace from a string.

string :a string to remove the trailing whitespace from.
Returns :string.

g_strstrip()

#define     g_strstrip( string )

Removes leading and trailing whitespace from a string.

string :a string to remove the leading and trailing whitespace from.

g_strdelimit ()

gchar*      g_strdelimit                    (gchar *string,
                                             const gchar *delimiters,
                                             gchar new_delimiter);

Converts any delimiter characters in string to new_delimiter. Any characters in string which are found in delimiters are changed to the new_delimiter character.

string :the string to convert.
delimiters :a string containing the current delimiters, or NULL to use the standard delimiters defined in G_STR_DELIMITERS.
new_delimiter :the new delimiter character.
Returns : 

G_STR_DELIMITERS

#define	 G_STR_DELIMITERS	"_-|> <."

The standard delimiters, used in g_strdelimit.

g_strescape ()

gchar*      g_strescape                     (gchar *string);

Escapes all backslash characters, '\' in a string, by inserting a second '\'.

string :a string to escape the backslashes in.
Returns :a newly allocated copy of string, with all backslash characters escaped using a second backslash.

g_strsplit ()

gchar**     g_strsplit                      (const gchar *string,
                                             const gchar *delimiter,
                                             gint max_tokens);

Splits a string into a maximum of max_tokens pieces, using the given delimiter. If max_tokens is reached, the final string in the returned string array contains the remainder of string.

string :a string to split.
delimiter :a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless max_tokens is reached.
max_tokens :the maximum number of strings to split string into. If this is less than 1, the string is split completely.
Returns :a newly-allocated array of strings. Use g_strfreev() to free it.

g_strfreev ()

void        g_strfreev                      (gchar **str_array);

Frees a NULL-terminated array of strings, and the array itself.

str_array :a NULL-terminated array of strings to free.

g_strconcat ()

gchar*      g_strconcat                     (const gchar *string1,
                                             ...);

Concatenates all of the given strings into one long string. The returned string should be freed when no longer needed.

string1 :The first string to add, which must not be NULL.
... :a NULL-terminated list of strings to append to the string.
Returns :a newly-allocated string containing all the string arguments.

g_strjoin ()

gchar*      g_strjoin                       (const gchar *separator,
                                             ...);

Joins a number of strings together to form one long string, with the optional separator inserted between each of them.

separator :a string to insert between each of the strings, or NULL.
... :a NULL-terminated list of strings to join.
Returns :a newly-allocated string containing all of the strings joined together, with separator between them.

g_strjoinv ()

gchar*      g_strjoinv                      (const gchar *separator,
                                             gchar **str_array);

Joins a number of strings together to form one long string, with the optional separator inserted between each of them.

separator :a string to insert between each of the strings, or NULL.
str_array :a NULL-terminated array of strings to join.
Returns :a newly-allocated string containing all of the strings joined together, with separator between them.

g_strerror ()

gchar*      g_strerror                      (gint errnum);

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.

errnum :the system error number. See the standard C errno documentation.
Returns :a string describing the error code. If the error code is unknown, it returns "unknown error (<code>)". The string can only be used until the next call to g_strerror.

g_strsignal ()

gchar*      g_strsignal                     (gint signum);

Returns a string describing the given signal, e.g. "Segmentation fault". This function is included since not all platforms support the strsignal() function.

signum :the signal number. See the signal documentation.
Returns :a string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)". The string can only be used until the next call to g_strsignal.



<<< Previous PageHomeUpNext Page >>>
GLib UtilitiesDate and Time Functions