Строковые сервисные функции

String Utility Functions — Варианты строковых функций.

Краткое описание

#include <glib.h> #include <glib/gprintf.h> gchar* g_strdup (const gchar *str); gchar* g_strndup (const gchar *str, gsize n); gchar** g_strdupv (gchar **str_array); gchar* g_strnfill (gsize length, gchar fill_char); gchar* g_stpcpy (gchar *dest, const char *src); gchar* g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gchar* g_strrstr (const gchar *haystack, const gchar *needle); gchar* g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gboolean g_str_has_prefix (const gchar *str, const gchar *prefix); gboolean g_str_has_suffix (const gchar *str, const gchar *suffix); gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size); gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size); gchar* g_strdup_printf (const gchar *format, ...); gchar* g_strdup_vprintf (const gchar *format, va_list args); gint g_printf (gchar const *format, ...); gint g_vprintf (gchar const *format, va_list args); gint g_fprintf (FILE *file, gchar const *format, ...); gint g_vfprintf (FILE *file, gchar const *format, va_list args); gint g_sprintf (gchar *string, gchar const *format, ...); gint g_vsprintf (gchar *string, gchar const *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); gint g_vasprintf (gchar **string, gchar const *format, va_list args); gsize g_printf_string_upper_bound (const gchar *format, va_list args); gboolean g_ascii_isalnum (gchar c); gboolean g_ascii_isalpha (gchar c); gboolean g_ascii_iscntrl (gchar c); gboolean g_ascii_isdigit (gchar c); gboolean g_ascii_isgraph (gchar c); gboolean g_ascii_islower (gchar c); gboolean g_ascii_isprint (gchar c); gboolean g_ascii_ispunct (gchar c); gboolean g_ascii_isspace (gchar c); gboolean g_ascii_isupper (gchar c); gboolean g_ascii_isxdigit (gchar c); gint g_ascii_digit_value (gchar c); gint g_ascii_xdigit_value (gchar c); gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2); gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n); gchar* g_ascii_strup (const gchar *str, gssize len); gchar* g_ascii_strdown (const gchar *str, gssize len); gchar g_ascii_tolower (gchar c); gchar g_ascii_toupper (gchar c); GString* g_string_ascii_up (GString *string); GString* g_string_ascii_down (GString *string); gchar* g_strup (gchar *string); gchar* g_strdown (gchar *string); gint g_strcasecmp (const gchar *s1, const gchar *s2); gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n); gchar* g_strreverse (gchar *string); gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base); guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base); #define G_ASCII_DTOSTR_BUF_SIZE gdouble g_ascii_strtod (const gchar *nptr, gchar **endptr); gchar* g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d); gchar* g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d); 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 (const gchar *source, const gchar *exceptions); gchar* g_strcompress (const gchar *source); gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor); gchar** g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens); gchar** g_strsplit_set (const gchar *string, const gchar *delimiters, 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); guint g_strv_length (gchar **str_array); const gchar* g_strerror (gint errnum); const gchar* g_strsignal (gint signum);

Описание

Этот раздел описывает множество сервисных функций для создания, дублирования и манипулирования строками.

Помните что функции g_printf(), g_fprintf(), g_sprintf(), g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() и g_vsnprintf() объявлены в заголовочном файле gprintf.h который не включён в glib.h (иначе использование glib.h привлекло бы stdio.h), поэтому вы должны явно включить <glib/gprintf.h> чтобы использовать GLib printf() функции.

Во время использования printf() функций для строк формата UTF-8, обратите внимание что точность параметра %Ns интерпретируется в количество байт, а не символов для печати. В добавок к этому, реализация GNU libc printf() функций имеет "особеность" прверять что полученная строка для %Ns параметра состоит из целого числа символов в текущей кодировке. Поэтому если вы не уверены что всегда используется UTF-8 locale или знаете что ваш текст находится в ASCII, избегайте использования %Ns. Если вы намереваетесь отформатировать строки в несколько столбцов, то %Ns не подходит для этого в любом случае, так как он не принимает во внимание широкие символы (смотрите g_unichar_iswide()).

Детали

g_strdup ()

gchar* g_strdup (const gchar *str);

Дублирует строку. Если параметр str равен NULL возвращает NULL. Возвращаемая строка должна освобождаться когда больше не нужна.

str : строка для дублирования.
Возвращает : вновь распределённая копия str.

g_strndup ()

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

Дублирует первые n символов строки, возвращает вновь распределённый буфер длиной n + 1 символ который всегда nul-terminated. Если str меньше чем n символов, буфер дополняется нулями (nuls). Если str равен NULL возвращается NULL. Возвращаемая строка должна освобождаться когда больше не нужна.

str : строка для частичного дублирования.
n : максимальное количество символов для копирования из строки str.
Возвращает : вновь распределённый буфер содержащий первые n символов строки str, nul-завершённый.

g_strdupv ()

gchar** g_strdupv (gchar **str_array);

Копирует NULL-завершённый массив строк. Новый массив освобождается сначала освобождая каждую строку, затем непосредственно сам массив. g_strfreev() делает это за вас. Если вызвать с значением NULL, g_strdupv() просто вернёт NULL.

str_array : NULL-завершённый массив строк.
Возвращает : новый NULL-завершённый массив строк.

g_strnfill ()

gchar* g_strnfill (gsize length, gchar fill_char);

Создаёт новую строку длинной length символов на всю длину заполненную символами fill_char. Возвращаемая строка должна освобождаться когда больше не нужна.

length : длина новой строки.
fill_char : символ для заполнения строки.
Возвращает : вновь распределённая строка заполненная fill_char.

g_stpcpy ()

gchar* g_stpcpy (gchar *dest, const char *src);

Копирует nul-завершённую строку в буфер dest, включая замыкающий nul и возвращает указатель на завершающий nul байт. Это полезно при соединении нескольких строк вместе без необходимости неоднократного сканирования конца.

dest : буфер назначения.
src : исходная строка.
Возвращает : указатель на завершающий нулевой байт.

g_strstr_len ()

gchar* g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);

Ищет строку haystack до первого появления строки needle, ограничивая длину поиска значением haystack_len.

haystack : строка.
haystack_len : максимальная длина haystack.
needle : строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_strrstr ()

gchar* g_strrstr (const gchar *haystack, const gchar *needle);

Ищет строку haystack до последнего совпадения строки needle.

haystack : nul-завершённая строка.
needle : nul-завершённая строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_strrstr_len ()

gchar* g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);

Ищет строку haystack до последнего совпадения строки needle, ограничивая длину поиска значением haystack_len.

haystack : nul-завершённая строка.
haystack_len : максимальная длина haystack.
needle : nul-завершённая строка для поиска.
Возвращает : указатель на найденное совпадение, или NULL если ничего не найдено.

g_str_has_prefix ()

gboolean g_str_has_prefix (const gchar *str, const gchar *prefix);

Определяет начинается ли строка str с префикса prefix.

str : nul-завершённая строка.
prefix : nul-завершённый префикс для поиска.
Возвращает : TRUE если str начинается с prefix, иначе FALSE.

Начиная с версии 2.2


g_str_has_suffix ()

gboolean g_str_has_suffix (const gchar *str, const gchar *suffix);

Определяет заканчивается ли строка str суффиксом suffix.

str : nul-завершённая строка.
suffix : nul-завершённый суффикс для поиска.
Возвращает : TRUE если str заканчивается suffix, иначе FALSE.

Начиная с версии 2.2


g_strlcpy ()

gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size);

Переносимая оболочка для вызова strlcpy() на системах которые имеют эту функцию она просто вызывает её, а на системах где нет strlcpy() эмулирует её. Копирует src в dest; dest гарантированно будет nul-завершённой; src должна быть nul-terminated; dest_size является размером буфера, а не количеством символов для копирования. Предостережение: strlcpy() более безопасна чем strcpy() или strncpy(), но если вы действительно хотите избежать проблем, то лучше используйте g_strdup().

dest : буфер назначения
src : исходный буфер
dest_size : длина dest в байтах
Возвращает : длина src

g_strlcat ()

gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size);

Переносимая оболочка функции strlcat(), на системах где нет этой функции она её эмулирует. Добавляет nul-завершённую строку src в dest, гарантирует nul-заврершённую dest. Полный размер dest не превышает dest_size. Предостережение: это возможно более безопасная альтернатива для strcat() или strncat(), но для действительно безопасного соединения лучше использовать g_strconcat().

dest : буфер назначения, уже содержащий одну nul-завершённую строку
src : исходный буфер
dest_size : длина буфера dest в байтах (не размер существующей строки внутри dest)
Возвращает : длина src плюс начальная длина строки в dest

g_strdup_printf ()

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

Аналогична для стандартной C функции sprintf() но безопасней, так как она рассчитывает максимальное требуемое пространство и распределяет память содержащую результат. Возвращаемая строка должна освобождаться когда больше не нужна.

format : стандартная строка формата printf(), но помните опасность строковой точности.
... : параметры вставляемые в форматируемую строку.
Возвращает : вновь распределённая строка содержащая результат.

g_strdup_vprintf ()

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

Похожа на стандартную C функцию vsprintf() но безопасней, так как она рассчитывает максимальное требуемое свободное пространство и распределяет память содержащую результат. Возвращаемая строка должна освобождаться когда больше не нужна.

Смотрите также g_vasprintf(), которая отличается некоторой функциональностью, но дополняет возвращаемый результат длинной распредделённой строки.

format : стандартная строка формата printf(), но помните проблемы точности строк.
args : список параметров для вставки в форматируемую строку.
Возвращает : вновь распределённая строка содержащая результат.

g_printf ()

gint g_printf (gchar const *format, ...);

Реализация стандартной функции printf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод (output).
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vprintf ()

gint g_vprintf (gchar const *format, va_list args);

Реализация стандартной функции vprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов вставляемых в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_fprintf ()

gint g_fprintf (FILE *file, gchar const *format, ...);

Реализация стандартной функции fprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

file : поток для записи.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы вставляемые в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vfprintf ()

gint g_vfprintf (FILE *file, gchar const *format, va_list args);

Реализация стандартной функции fprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

file : попыток для записи.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_sprintf ()

gint g_sprintf (gchar *string, gchar const *format, ...);

Реализация стандартной функции sprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_vsprintf ()

gint g_vsprintf (gchar *string, gchar const *format, va_list args);

Реализация стандартной функции vsprintf() которая поддерживает параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов вставляемых в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.2


g_snprintf ()

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

Более безопасный вариант стандартной функции sprintf(). Гарантирует что вывод не превысит n символов (включая завершающий нулевой символ (nul character)), поэтому переполнение буфера невозможно.

Смотрите также g_strdup_printf().

В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.

Возвращаемое значение g_snprintf() согласуется с функцией snprintf() как стандартизировано в ISO C99. Помните что это отличается от традиционной snprintf(), которая возвращает длину строки вывода.

Форматируемая строка может содержать параметры позиционирования, как определено в Single Unix Specification.

string : буфер для содержания вывода.
n : максимальное количество производимых символов (включая символ завершения nul).
format : стандартная строка формата printf(), но помните о проблеме точности строк.
... : аргументы для вставки в вывод.
Возвращает : количество произведённых символов если бы буфер был достаточно большим.

g_vsnprintf ()

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

Более безопасный вариант стандартной функции vsprintf(). Вывод гарантировано не превысит n символов (включая завершающий символ), поэтому переполнение буфера не возможно.

Смотрите также g_strdup_vprintf().

В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.

Возвращаемое значение g_vsnprintf() согласуется с функцией vsnprintf() как стандартизировано в ISO C99. Помните что это отличается от традиционной vsnprintf(), которая возвращает длину строки вывода.

Форматируемая строка может содержать параметры позиционирования, как описано в Single Unix Specification.

string : буфер для вывода.
n : максимальное количество символов (включая завершающий nul символ).
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество символов которые должны быть произведены если буфер окажется больше чем необходимо.

g_vasprintf ()

gint g_vasprintf (gchar **string, gchar const *format, va_list args);

Реализация функции GNU vasprintf() которая поддерживает параметры позиционирования, как описано в Single Unix Specification. Эта функция похожа на g_vsprintf(), но она распределяет строку содержащую вывод, а не помещает вывод в буфер распределённый вами заранее.

string : расположение для возвращаемой вновь распределённой строки.
format : стандартная строка формата printf(), но помните о проблеме точности строк.
args : список аргументов для вставки в вывод.
Возвращает : количество напечатанных символов.

Начиная с версии 2.4


g_printf_string_upper_bound ()

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

Расчитывает необходимое пространство необходимое для сохранения вывода функции sprintf().

format : форматируемая строка. Смотрите документацию printf().
args : параметры для вставки в форматируемую строку.
Возвращает : максимальное пространство необходимое для сохранения форматируемой строки.

g_ascii_isalnum ()

gboolean g_ascii_isalnum (gchar c);

Определяет являются ли символы алфавитно-цифровыми.

В отличие от стандартной библиотечной C функции isalnum(), эта функция распознаёт только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в конце файла EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c алфавитно-цифровой символ ASCII.

g_ascii_isalpha ()

gboolean g_ascii_isalpha (gchar c);

Определяет является ли символ алфавитным (то есть буквой).

В отличие от стандартной библиотечной функции isalpha(), эта распознаёт только стандартные ASCII буквы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является алфавитным ASCII символом.

g_ascii_iscntrl ()

gboolean g_ascii_iscntrl (gchar c);

Определяет является ли символ управляющим символом.

В отличие от стандартной библиотечной функции iscntrl(), эта рассматривает только стандартные символы управления ASCII и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной функции, эта принимает char, вместо int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является управляющим символом ASCII.

g_ascii_isdigit ()

gboolean g_ascii_isdigit (gchar c);

Определяет является ли символ цифрой (0-9).

В отличие от стандартной библиотечной функции isdigit(), эта принимает char, вместо int, поэтому не вызывается в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c является ASCII цифрой.

g_ascii_isgraph ()

gboolean g_ascii_isgraph (gchar c);

Определяет является ли символ печатным и не прбелом.

В отличие от стандартной библиотечной функции isgraph(), эта распознаёт только стандартные символы ASCII и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, вместо int, поэтому не должна вызываться в конце файла EOF и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII печатный символ отличающийся от пробела.

g_ascii_islower ()

gboolean g_ascii_islower (gchar c);

Определяет является ли символ буквой ASCII в нижнем регистре.

В отличие от стандартной библиотечной функции islower(), эта принимает только стандартные ASCII символы и игнорирует локаль (locale), возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её на EOF, и нет необходимости приведения к guchar перед помещением возможно не-ASCII символа в функцию.

c : любой символ
Возвращает : TRUE если c это ASCII символ в нижнем регистре

g_ascii_isprint ()

gboolean g_ascii_isprint (gchar c);

Определяет является ли символ печатным символом.

В отличие от стандартной библиотечной функции isprint(), эта принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это печатный ASCII символ.

g_ascii_ispunct ()

gboolean g_ascii_ispunct (gchar c);

Определяет является ли символ символом пунктуации.

В отличие от стандартной библиотечной функции ispunct(), это принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII символ пунктуации.

g_ascii_isspace ()

gboolean g_ascii_isspace (gchar c);

Определяет является ли символ символом табуляции, пробела или символом пустой строки (white-space character).

В отличие от стандартной библиотечной функции isspace(), эта принимает только стандартные ASCII символы white-space и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int, поэтому не вызывайте её в EOF и не нужно приводить тип к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII white-space символ

g_ascii_isupper ()

gboolean g_ascii_isupper (gchar c);

Определяет является ли символ символом ASCII верхнего регистра.

В отличие от стандартной библиотечной функции isupper(), это принимает только стандартные ASCII символы и игнорирует локаль, возвращает FALSE для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает тип char, а не int, поэтому не вызывайте её в EOF и не нужно приводить тип к guchar перед помещением возможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII символ верхнего регистра

g_ascii_isxdigit ()

gboolean g_ascii_isxdigit (gchar c);

Определяет является ли символ шестнадцатеричным-цифровым символом.

В отличие от стандартной библиотечной функции isxdigit(), эта принимает тип char, а не int, поэтому не нужно вызывать её в EOF и не нужно приводить тип к guchar перед помещением вохможно не-ASCII символа.

c : любой символ
Возвращает : TRUE если c это ASCII шестнадцатеричный-цифровой символ.

g_ascii_digit_value ()

gint g_ascii_digit_value (gchar c);

Определяет числовое значение символа в виде десятичной цифры. Отличается от g_unichar_digit_value() потому что принимает тип char, поэтому не беспокойтесь о дополнительном знаке (+ или -) если символы со знаком.

c : ASCII символ.
Возвращает : Если c десятичная цифра (согласно g_ascii_isdigit()), её числовое значение. Иначе, -1.

g_ascii_xdigit_value ()

gint g_ascii_xdigit_value (gchar c);

Определяет числовое значение символа как шестнадцатеричное число. Отличается от g_unichar_xdigit_value() так как принимает символ, поэтому нет смысла беспокоится о знаке если символы со знаком.

c : ASCII символ.
Возвращает : Если c шестнадцатеричное число (согласно g_ascii_isxdigit()), его числовое значение. Иначе, -1.

g_ascii_strcasecmp ()

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

Сравнивает две строки, игнорирует регистр ASCII символов.

В отличие от BSD функции strcasecmp(), эта принимает только стандартные ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII байты как будто они не буквы.

Эта функция должна использоваться только в строках кодировка байт которых соответствует ASCII литерам всегда представляя самих себя. Это включает UTF-8 и ISO-8859-* символы, но не двойную кодировку байт как в Windows Codepage 932, где завершающий байт двух-байтовых символов включает все ASCII буквы. Если вы сравниваете две CP932 строки используя эту функцию, то вы получите неправильный результат.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_ascii_strncasecmp ()

gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n);

Сравнивает s1 и s2, игнорирует регистр ASCII символов и любые символы после первых n в каждой строке.

В отличие от BSD функции strcasecmp(), эта функция понимает только стандартные ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII символы как не буквы.

Тоже самое предупреждение как и для g_ascii_strcasecmp(): Используйте эту функцию только для строк известной кодировки где байты соответствуют ASCII литерам и представляют самих себя.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
n : количество символов для сравнения.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_ascii_strup ()

gchar* g_ascii_strup (const gchar *str, gssize len);

Конвертирует все символы нижнего регистра ASCII букв в верхний регистр букв ASCII.

str : строка.
len : длина str в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределёная строка, все символы нижнего регистра в str преобразуются в верхний регистр, семантика которой точно соответствует g_ascii_toupper(). (Помните что это отличается от старой g_strup(), которая изменяла строку на месте.)

g_ascii_strdown ()

gchar* g_ascii_strdown (const gchar *str, gssize len);

Конвертирует все символы ASCII верхнего регистра в символы ASCII нижнего регистра.

str : строка.
len : длина str в байтах, или -1 если str nul-завершённая.
Возвращает : вновь распределённая строка, все символы верхнего регистра str конвертированы в символы нижнего регистра, с семантикой точно соответствующей g_ascii_tolower(). (Помните это не похоже на старую g_strdown(), которая изменялся строку на месте.)

g_ascii_tolower ()

gchar g_ascii_tolower (gchar c);

Конвертирует символ в нижний регистр ASCII.

В отличие от стандартной библиотечной функции tolower(), эта принимает только стандартные ASCII буквы и игнорирует локаль, возвращает все не-ASCII символы не изменёнными, даже если они являются буквами нижнего регистра в специальном наборе символов. Также в отличие от стандартной библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому не вызывайте её в EOF и не беспокойтесь о приведении типа к guchar перед помещением возможно не-ASCII символа.

c : любой символ.
Возвращает : результат конвертации c в нижний регистр. Если c не ASCII буква верхнего регистра, c возвращается не изменённым.

g_ascii_toupper ()

gchar g_ascii_toupper (gchar c);

Ковертирует символ в ASCII верхнего регистра.

В отличие от стандартной библиотечной функции toupper(), эта принимает только стандартные ASCII буквы и игнорирует локаль, возвращает все не-ASCII символы без изменений, даже если они являются символами верхнего регистра в специальном наборе символов. Также в отличие от стандартной библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому не вызывайте её в EOF и не беспокойтесь о приведении типа к guchar перед помещением в неё возможно не-ASCII символа.

c : любой символ.
Возвращает : результат конвертации c в верхний регистр. Если c не ASCII буква нижнего регистра, c возвращается без изменений.

g_string_ascii_up ()

GString* g_string_ascii_up (GString *string);

Конвертирует все буквы ASCII нижнего регистра в буквы верхнего регистра ASCII.

string : GString
Возвращает : помещённый указатель на string, в которой все символы нижнего регистра конвертированы в верхний регистр на месте, с семантикой которая соответствует g_ascii_toupper.

g_string_ascii_down ()

GString* g_string_ascii_down (GString *string);

Конвертирует все буквы верхнего регистра ASCII в нижний регистр букв ASCII.

string : GString
Возвращает : помещённый указатель на string, в которой все символы верхнего регистра конвертированы в нижний регистр на месте, с семантикой соответствующей g_ascii_tolower.

g_strup ()

gchar* g_strup (gchar *string);

Внимание

g_strup устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция неисправна по причинам обсуждаемым в документации g_strncasecmp() - используйте вместо неё g_ascii_strup() или g_utf8_strup().

Конвертирует строку в верхний регистр.

string : строка для конвертации.
Возвращает : конвертированную строку

g_strdown ()

gchar* g_strdown (gchar *string);

Внимание

g_strdown устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция полностью неисправна по причинам обсуждаемым в документации g_strncasecmp() - используйте вместо неё g_ascii_strdown() или g_utf8_strdown().

Конвертирует строку в нижний регистр.

string : строка для конвертации.
Возвращает : строка

g_strcasecmp ()

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

Внимание

g_strcasecmp устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Смотрите g_strncasecmp() для обсуждения причины по которой не рекомендуется использовать эту функцию и чем её заменить.

Не чувствительное к регистру сравнение строк, соответствует стандартной функции strcasecmp() на платформах которые поддерживают её.

s1 : строка.
s2 : a строка для сравнения с s1.
Возвращает : 0 если строки соответсвуют, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_strncasecmp ()

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

Внимание

g_strncasecmp устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Проблема g_strncasecmp() в том что она вызывает для сравнения toupper()/tolower(). Эти функции являются локаль-специфичными (locale-specific) и оперируют одним байтом. Однако, это не позволяет правильно обрабатывать возможности I18N так как требуются многобайтные символы. Поэтому g_strncasecmp() не работает правильно если ваша строка гарантировано в ASCII, так как это зависит от локали (locale-sensitive), и она неправильно работает если ваша строка локализована, так как она не работает на большинстве кодировок, включая UTF-8, EUC-JP, и т.д..

Пэтому есть две заменяющие функции: g_ascii_strncasecmp(), которая работает только в ASCII и не зависит от локали, а так же g_utf8_casefold(), которая хорошо подходит для сортировки без учета регистра UTF-8.

Сравнение строк без учёта регистра, соответствует стандартной функции strncasecmp() на платформах которые её поддерживают. Она похожа на g_strcasecmp() за исключением того что сравнивает только первые n символов в строках.

s1 : строка.
s2 : a строка для сравнения с s1.
n : максимальное число символов для сравнения.
Возвращает : 0 если строки эквивалентны, отрицательное значение если s1 < s2, или положительное значение если s1 > s2.

g_strreverse ()

gchar* g_strreverse (gchar *string);

Переворачивает строку. Например, g_strreverse ("abcdef") выдаст результат "fedcba".

Помните что g_strreverse() не работает в UTF-8 строках содержащих многобайтные символы. Для этих случаев используйте g_utf8_strreverse().

указатель помещённый как string.
string : строка для переворота.
Возвращает :

g_ascii_strtoll ()

gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base);

Конвертирует строку в значение gint64. Эта функция ведёт себя как стандартная функция strtoll() выполняемая в C локали. Она выполняет это без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется когда читаются конфигурационные файлы или другой не пользовательский ввод который должен быть независим от локали. Для обработки пользовательского ввода вы должны обычно использовать чувствительную к локали (locale-sensitive) системную функцию strtoll().

Если текущее значение вызвало бы переполнение буфера, возвращается G_MAXINT64 или G_MININT64, а ERANGE сохраняется в errno. Если base вне допустимого диапазона, возвращается ноль, а EINVAL сохраняется в errno. Если преобразование строки не удалось, возвращается ноль, а endptr возвращает nptr (если endptr это не-NULL).

nptr : строка для конвертации в числовое значение.
endptr : если не-NULL, возвращается символ после последнего символа используемого в преобразовании.
base : используется для преобразования, 2..36 или 0
Возвращает : gint64 значение или ноль при ошибке.

Начиная с версии 2.12


g_ascii_strtoull ()

guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base);

Конвертирует строку в значение guint64. Эта функция ведёт себя также как стандартная strtoull() выполняющаяся в C локали. Она работает без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется при чтении конфигурационных файлов или другого не пользовательского ввода который должен быть независимым от локали. Для обработки пользовательского ввода вы должны обычно использовать чувствительную к локали (locale-sensitive) системную функцию strtoull().

Если правильное значение вызывает переполнение буфера, то возвращается G_MAXUINT64, а ERANGE сохраняется в errno. Если base вне допустимого диапазона, возвращается ноль, а EINVAL сохраняется в errno. Если преобразование строки не удалось, возвращается ноль, а endptr возвращает nptr (если endptr не-NULL).

nptr : строка для конвертации to a numeric value.
endptr : если не-NULL, возвращается символ после последнего используемого при конвертации.
base : используется для преобразования, 2..36 или 0
Возвращает : значение guint64 или ноль в error.

Начиная с версии 2.2


G_ASCII_DTOSTR_BUF_SIZE

#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)

Правильный размер буфера для помещения в g_ascii_dtostr(). Этого гарантированно достаточно для всего вывода функции в системах с 64bit IEEE-совместимым doubles.

Обычное использование выглядит так:

char buf[G_ASCII_DTOSTR_BUF_SIZE]; fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));


g_ascii_strtod ()

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

Конвертирует строку в gdouble значение. Эта функция ведёт себя как стандартная функция strtod() работающая в C лосали. Она работает без фактического изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).

Эта функция обычно используется когда читаются конфигурационные файлы или другой не пользовательский ввод который должен быть не зависим от локали. Для обработки ввода пользователя вы должны обычно использовать чувствительную к локали системную функцию strtod().

Для конвертации из gdouble в строку чувствительным к локали способом, используйте g_ascii_dtostr().

Если правильное значение вызвало бы переполнение буфера, возвращается плюс или минус HUGE_VAL (соответсвенно значению со знаком), а ERANGE сохраняется в errno. Если правильное значение вызвало бы антипереполнение буфера (underflow), возвращается ноль и ERANGE сохраняется в errno.

Эта функция сбрасывает errno перед вызовом strtod() так, чтобы вы могли надёжно обнаружить переполнение или антипереполнение буфера.

nptr : строка для конвертации to a numeric value.
endptr : если не-NULL, возвращает символ после последнего символа используемого в конвертации.
Возвращает : gdouble значение.

g_ascii_dtostr ()

gchar* g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d);

Конвертирует gdouble в строку, используя '.' как десятичную точку.

Эта функция генерирует достаточно точно конвертированную с помощью g_ascii_strtod() строку, получая то же машинное число (machine-number) (на машинах с IEEE совместимым 64bit doubles). Гарантирует что результирующая строка не будет больше чем G_ASCII_DTOSTR_BUF_SIZE байт.

buffer : Буфер для размещения строки результата
buf_len : Размер буфера.
d : gdouble для конвертации
Возвращает : Указатель на буфер с конвертированной строкой.

g_ascii_formatd ()

gchar* g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d);

Конвертирует gdouble в строку, используя '.' как десятичную точку. Для форматирования числа вы помещаете строку формата в стиле printf(). Допускаются спецификаторы преобразования 'e', 'E', 'f', 'F', 'g' и 'G'.

Если вы просто хотите преобразовать в последовательную форму значение в строке, используйте g_ascii_dtostr().

buffer : Буфер для размещения строки результата
buf_len : Размер буфера.
format : Формат в стиле printf() используемый для конвертации.
d : gdouble для конвертации
Возвращает : Указатель на буфер с конвертированной строкой.

g_strtod ()

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

Конвертирует строку в gdouble значение. Она вызывает стандартную функцию strtod() для обработки конвертации, но если строка конвертирована не полностью она пытается конвертировать снова с помощью g_ascii_strtod() и возвращает лучшее соответствие.

Эта функция должна использоваться редко. В обычных ситуациях когда читаются числа не для применения человеком используется g_ascii_strtod(). Вы должны её использовать только когда знаете что ожидается оба формата чисел и в локали и в C формате. Убедитесь что вы не поместили строки такие как разделённые запятыми списки значений, так как запятая может интерпретироваться как десятичная точка в некоторых локалях, вызывая неожиданный результат.

nptr : строка для конвертации в числовое значение.
endptr : Если не-NULL, возвращается символ после последнего символа используемого в конвертации.
Возвращает : gdouble значение.

g_strchug ()

gchar* g_strchug (gchar *string);

Удаляет все символы табуляций (whitespace) из строки, но перемещает символы вперёд.

Эта функция не распределяет и не перераспределяет никакую память; она изменяет string на месте. Указатель на string возвращается чтобы позволить вложенные функции.

Также смотрите g_strchomp() и g_strstrip().

string : строка из которой удаляются табуляции.
Возвращает : string.

g_strchomp ()

gchar* g_strchomp (gchar *string);

Удаляет замыкающие табуляции из строки.

Эта функция не распределяет и не перераспределяет никакую память; она изменяет string на месте. Указатель на string возвращается чтобы позволить вложенные функции.

Также смотрите g_strchug() и g_strstrip().

string : строка to remove the trailing whitespace from.
Возвращает : string.

g_strstrip()

#define g_strstrip( string )

Удаляет начальные и завершающие пробелы (whitespace) из строки. Смотрите g_strchomp() и g_strchug().

string : строка из которой удаляются начальные и завершающие пробелы (whitespace).

g_strdelimit ()

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

Конвертирует любые разделительные символы (delimiter characters) в string в new_delimiter. Любые найденные в string символы delimiters изменяются на new_delimiter. Изменяет строку string на месте и возвращает непосредственно string, а не копию. Возвращаемое значение позволяет вложение, такое как g_ascii_strup (g_strdelimit (str, "abc", '?')).

string : строка для конвертации.
delimiters : строка содержащая текущие разделители, или NULL для использования стандартных разделителей определённых в G_STR_DELIMITERS.
new_delimiter : новые разделительные символы.
Возвращает : string.

G_STR_DELIMITERS

#define G_STR_DELIMITERS "_-|> <."

Стандартные разделительные символы используемые в g_strdelimit().


g_strescape ()

gchar* g_strescape (const gchar *source, const gchar *exceptions);

Выводит специальные символы '\b', '\f', '\n', '\r', '\t', '\' и '"' в строке source и вставляет перед ними '\'. Дополнительно все символы в диапазоне 0x01-0x1F (все ниже SPACE) м в диапазоне 0x7F-0xFF (все не-ASCII символы) заменяются с помощью '\' сопровождаемого их восьмеричным представлением. Символы поставляемые в exceptions не выводятся.

g_strcompress() выполняет обратную конвертацию.

source : строка для вывода.
exceptions : строка of characters not to escape in source.
Возвращает : вновь распределённая копия source с определёнными символами вывода. Смотрите выше.

g_strcompress ()

gchar* g_strcompress (const gchar *source);

Заменяет все escape-символы их однобайтными эквивалентами. Вы полняет обратную конвертацию для g_strescape().

source : строка для сжатия.
Возвращает : вновь распределённая копия source в которой все escape-символы сжаты.

g_strcanon ()

gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor);

Каждый символ в string, если символ не valid_chars, заменяет символом substitutor. Изменяет строку string на месте и возвращает непосредственно string, а не копию. Возвращаемое значение допускает вложенность, такую как g_ascii_strup (g_strcanon (str, "abc", '?')).

string : nul-завершённый массив байт.
valid_chars : байты разрешённые в string.
substitutor : символ заменяющий запрещённые байты.
Возвращает : string.

g_strsplit ()

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

Разбивает строку на максимум max_tokens частей, используя разделитель delimiter. Если max_tokens достигнут, остаток строки string прикрепляется к последней лексеме.

Как специальный случай, результатом разбиения пустой строки "" является пустой вектор, а не вектор содержащий единственную строку. Причиной такого специального случая является то, что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно представить пустые элементы, вы должны проверить пустую строку перед вызовом g_strsplit().

string : строка для разбиения.
delimiter : строка определяющая места разбиения строки. Разделитель не включается ни в одну из результирующих строк, пока не достигнут max_tokens.
max_tokens : максимальное число частей для разбиения string. Если меньше чем 1, строка разбивается полностью.
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

g_strsplit_set ()

gchar** g_strsplit_set (const gchar *string, const gchar *delimiters, gint max_tokens);

Разбивает string на множество лексем не содержащих любой из символов в delimiter. Лексемы это (возможно пустые) длинные строки которые не содержат любой из символов находящихся в delimiters. Если достигнут max_tokens, остаток предложения прикрепляется к последней лексеме.

Например результатом g_strsplit_set ("abc:def/ghi", ":/", -1) будет NULL-завершённый вектор содержащий дерево строк "abc", "def", и "ghi".

Результатом g_strsplit_set (":def/ghi:", ":/", -1) NULL-завершённый вектор содержащий четыре строки "", "def", "ghi", и "".

Как специальный случай, результатом разбиения пустой строки "" является пустой вектор, а не вектор содержащий единственную строку. Причиной такого специального случая является то, что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно представить пустые элементы, вы должны проверить пустую строку перед вызовом g_strsplit().

Помните что эта функция работает с байтами а не с символами, поэтому она не может использоваться для разграничения UTF-8 строк чем нибудь кроме ASCII символов.

string : строка для разбиения на лексемы
delimiters : nul-завершённая строка содержащая байты которые используются для разбиения строки.
max_tokens : максимальное число лексем для разбиения string. Если меньше 1, строка разбивается полностью
Возвращает : вновь распределённый NULL-завершённый массив строк. Используйте g_strfreev() для его освобождения.

Начиная с версии 2.4


g_strfreev ()

void g_strfreev (gchar **str_array);

Освобождает NULL-завершённый массив строк, и непосредственно массив. Если вызвана для значения NULL, g_strfreev() просто возвращается.

str_array : NULL-завершённый массив строк для освобождения.

g_strconcat ()

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

Соединяет все полученные строки в одну длинную строку. Возвращаемая строка должна быть освобождена когда больше не нужна.

Внимание

Переменный список параметров must должен завершаться NULL. Если вы забудете о NULL, g_strconcat() добавит к ваше строке произвольный участок памяти.

string1 : Первая строка для добавления, которая не должна быть NULL.
... : NULL-завершённый список строк для добавления к строке.
Возвращает : вновь распределённая строка содержащая все строки аргументов.

g_strjoin ()

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

Объединяет множество строк вместе в форме одной длинной строки, с необязательным разделителем separator вставляемым между ними.

separator : строка для вставки между каждой строкой, или NULL.
... : NULL-завершённый список строк в объединении.
Возвращает : вновь распределённая строка содержащая все строки объединённые вместе, с separator между ними.

g_strjoinv ()

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

Объединяет множество строк вместе в форме одной длинной строки, с необязательным separator вставляемым между каждой из них.

separator : строка вставляемая между каждой из строк, или NULL.
str_array : NULL-завершённый массив строк для объединения.
Возвращает : вновь распределённая строка содержащая все строки объединённые вместе, с separator между ними.

g_strv_length ()

guint g_strv_length (gchar **str_array);

Возвращает длину полученного NULL-завершённого массива строк str_array.

str_array : NULL-завершённый массив строк.
Возвращает : длина str_array.

Начиная с версии 2.6


g_strerror ()

const gchar* g_strerror (gint errnum);

Возвращает строку соответствующую данному коду ошибки (error code), например "no such process". Эта функция включена так как не все платформы поддерживают функцию strerror().

errnum : номер системной ошибки. Смотрите стандарт C errno документацию.
Возвращает : строка описывающая кодовую ошибку. Если данный код ошибки не известен, возвращается "unknown error (<code>)". Строка может использоваться только до следующего вызова g_strerror().

g_strsignal ()

const gchar* g_strsignal (gint signum);

Возвращает строку описывающую полученный сигнал, например "Segmentation fault". Эта функция включена так как не на всех платформах поддерживается функция strsignal().

signum : номер сигнала. Смотрите signal документацию.
Возвращает : строка описывающая сигнал. Если сигнал не известен, возвращается "unknown signal (<signum>)". Строка может использоваться только до следующего вызова g_strsignal().