From 425731f766bf75f78d581ab686152b1bfcc41eb6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 21 Nov 2023 17:55:54 +0000 Subject: [PATCH] docs: Move the string_utils SECTION Move it to a mega separate file. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/glib/glib.toml.in | 2 + docs/reference/glib/meson.build | 1 + docs/reference/glib/string-utils.md | 187 ++++++++++++++++++++++++++++ glib/gprintf.c | 18 +-- glib/gstrfuncs.c | 43 +------ 5 files changed, 201 insertions(+), 50 deletions(-) create mode 100644 docs/reference/glib/string-utils.md diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 2cba7e095..94a5e2fb5 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -51,6 +51,8 @@ content_files = [ "character-set.md", "i18n.md", + "string-utils.md", + "macros.md", "conversion-macros.md", "auto-cleanup.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index 9787d17f0..5a9ad97c7 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -169,6 +169,7 @@ expand_content_files = [ 'goption.md', 'data-structures.md', 'shell.md', + 'string-utils.md', 'unicode.md', 'uuid.md', 'version.md', diff --git a/docs/reference/glib/string-utils.md b/docs/reference/glib/string-utils.md new file mode 100644 index 000000000..977af4b0c --- /dev/null +++ b/docs/reference/glib/string-utils.md @@ -0,0 +1,187 @@ +Title: String Utilities +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 1999 Owen Taylor +SPDX-FileCopyrightText: 2000 Red Hat, Inc. +SPDX-FileCopyrightText: 2002, 2003, 2014 Matthias Clasen +SPDX-FileCopyrightText: 2015 Collabora, Ltd. + +# String Utilities + +This section describes a number of utility functions for creating, +duplicating, and manipulating strings. + +Note that the functions [func@GLib.printf], [func@GLib.fprintf], +[func@GLib.sprintf], [func@GLib.vprintf], [func@GLib.vfprintf], +[func@GLib.vsprintf] and [func@GLib.vasprintf] are declared in 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 `` in order to use the GLib +`printf()` functions. + +## String precision pitfalls # {#string-precision} + +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 [func@GLib.unichar_iswide]) +into account. + +Note also that there are various `printf()` parameters which are platform +dependent. GLib provides platform independent macros for these parameters +which should be used instead. A common example is [const@GLib.GUINT64_FORMAT], +which should be used instead of `%llu` or similar parameters for formatting +64-bit integers. These macros are all named `G_*_FORMAT`; see +[Basic Types](types.html). + +## General String Manipulation + + * [func@GLib.strdup] + * [func@GLib.strndup] + * [func@GLib.strdupv] + * [func@GLib.strnfill] + * [func@GLib.stpcpy] + * [func@GLib.strstr_len] + * [func@GLib.strrstr] + * [func@GLib.strrstr_len] + * [func@GLib.str_has_prefix] + * [func@GLib.str_has_suffix] + * [func@GLib.strcmp0] + * [func@GLib.str_to_ascii] + * [func@GLib.str_tokenize_and_fold] + * [func@GLib.str_match_string] + +For users of GLib in C, the `g_set_str()` inline function also exists to set a +string and handle copying the new value and freeing the old one. + +## String Copying + + * [func@GLib.strlcpy] + * [func@GLib.strlcat] + +## Printing + + * [func@GLib.strdup_printf] + * [func@GLib.strdup_vprintf] + * [func@GLib.printf] + * [func@GLib.vprintf] + * [func@GLib.fprintf] + * [func@GLib.vfprintf] + * [func@GLib.sprintf] + * [func@GLib.vsprintf] + * [func@GLib.snprintf] + * [func@GLib.vsnprintf] + * [func@GLib.vasprintf] + * [func@GLib.printf_string_upper_bound] + +## ASCII + + * [func@GLib.str_is_ascii] + * [func@GLib.ascii_isalnum] + * [func@GLib.ascii_isalpha] + * [func@GLib.ascii_iscntrl] + * [func@GLib.ascii_isdigit] + * [func@GLib.ascii_isgraph] + * [func@GLib.ascii_islower] + * [func@GLib.ascii_isprint] + * [func@GLib.ascii_ispunct] + * [func@GLib.ascii_isspace] + * [func@GLib.ascii_isupper] + * [func@GLib.ascii_isxdigit] + +## ASCII Parsing + + * [func@GLib.ascii_digit_value] + * [func@GLib.ascii_xdigit_value] + +## ASCII Comparisons + + * [func@GLib.ascii_strcasecmp] + * [func@GLib.ascii_strncasecmp] + +## ASCII Case Manipulation + + * [func@GLib.ascii_strup] + * [func@GLib.ascii_strdown] + * [func@GLib.ascii_tolower] + * [func@GLib.ascii_toupper + +## ASCII String Manipulation + + * [func@GLib.strreverse] + +## ASCII Number Manipulation + + * [func@GLib.ascii_strtoll] + * [func@GLib.ascii_strtoull] + * [const@GLib.ASCII_DTOSTR_BUF_SIZE] + * [func@GLib.ascii_strtod] + * [func@GLib.ascii_dtostr] + * [func@GLib.ascii_formatd] + * [func@GLib.strtod] + +## ASCII Number Parsing + + * [type@GLib.NumberParserError] + * [func@GLib.ascii_string_to_signed] + * [func@GLib.ascii_string_to_unsigned] + +## Whitespace Removal + + * [func@GLib.strchug] + * [func@GLib.strchomp] + * [func@GLib.strstrip] + +## Find and Replace + + * [func@GLib.strdelimit] + * [const@GLib.STR_DELIMITERS] + * [func@GLib.strescape] + * [func@GLib.strcompress] + * [func@GLib.strcanon] + +## Splitting and Joining + + * [func@GLib.strsplit] + * [func@GLib.strsplit_set] + * [func@GLib.strconcat] + * [func@GLib.strjoin] + * [func@GLib.strjoinv] + +## String Arrays + + * [type@GLib.Strv] + * [func@GLib.strfreev] + * [func@GLib.strv_length] + * [func@GLib.strv_contains] + * [func@GLib.strv_equal] + +## String Array Builder + + * [type@GLib.StrvBuilder] + * [ctor@GLib.StrvBuilder.new] + * [method@GLib.StrvBuilder.ref] + * [method@GLib.StrvBuilder.unref] + * [method@GLib.StrvBuilder.add] + * [method@GLib.StrvBuilder.addv] + * [method@GLib.StrvBuilder.add_many] + * [method@GLib.StrvBuilder.take] + * [method@GLib.StrvBuilder.end] + +## POSIX Errors + + * [func@GLib.strerror] + * [func@GLib.strsignal] + +## Deprecated API + + * [func@GLib.strup] + * [func@GLib.strdown] + * [func@GLib.strcasecmp] + * [func@GLib.strncasecmp] diff --git a/glib/gprintf.c b/glib/gprintf.c index 19642d82b..7cf30d2cf 100644 --- a/glib/gprintf.c +++ b/glib/gprintf.c @@ -31,7 +31,7 @@ /** * g_printf: * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports @@ -65,7 +65,7 @@ g_printf (gchar const *format, * g_fprintf: * @file: (not nullable): the stream to write to. * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -98,7 +98,7 @@ g_fprintf (FILE *file, * is up to the caller to ensure that the allocated buffer is large * enough to hold the formatted result * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports @@ -136,7 +136,7 @@ g_sprintf (gchar *string, * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed @@ -179,7 +179,7 @@ g_snprintf (gchar *string, /** * g_vprintf: * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports @@ -204,7 +204,7 @@ g_vprintf (gchar const *format, * g_vfprintf: * @file: (not nullable): the stream to write to. * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -230,7 +230,7 @@ g_vfprintf (FILE *file, * g_vsprintf: * @string: the buffer to hold the output. * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports @@ -259,7 +259,7 @@ g_vsprintf (gchar *string, * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed @@ -300,7 +300,7 @@ g_vsnprintf (gchar *string, * @string: (not optional) (nullable): the return location for the newly-allocated string, * which will be %NULL if (and only if) this function fails * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 506b7c3ea..8dd722afd 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -57,45 +57,6 @@ #include "gprintfint.h" #include "glibintl.h" - -/** - * SECTION:string_utils - * @title: String Utility Functions - * @short_description: various string-related functions - * - * This section describes a number of utility functions for creating, - * duplicating, and manipulating strings. - * - * Note that the functions g_printf(), g_fprintf(), g_sprintf(), - * g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() - * are declared in 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 `` in order to use the GLib - * printf() functions. - * - * ## String precision pitfalls # {#string-precision} - * - * 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. - * - * Note also that there are various printf() parameters which are platform - * dependent. GLib provides platform independent macros for these parameters - * which should be used instead. A common example is %G_GUINT64_FORMAT, which - * should be used instead of `%llu` or similar parameters for formatting - * 64-bit integers. These macros are all named `G_*_FORMAT`; see - * [Basic Types][glib-Basic-Types]. - */ - /** * g_ascii_isalnum: * @c: any character @@ -527,7 +488,7 @@ g_stpcpy (gchar *dest, /** * g_strdup_vprintf: * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it @@ -558,7 +519,7 @@ g_strdup_vprintf (const gchar *format, /** * g_strdup_printf: * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it