luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the string_utils SECTION

Browse Source 
Move it to a mega separate file.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-11-21 17:55:54 +00:00
parent cf52727f03
commit 425731f766
5 changed files with 201 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/glib/glib.toml.in
View File

@ -51,6 +51,8 @@ content_files = [
"character-set.md",
"i18n.md",
"string-utils.md",
"macros.md",
"conversion-macros.md",
"auto-cleanup.md",

1
docs/reference/glib/meson.build
View File

@ -169,6 +169,7 @@ expand_content_files = [
'goption.md',
'data-structures.md',
'shell.md',
'string-utils.md',
'unicode.md',
'uuid.md',
'version.md',

187
docs/reference/glib/string-utils.md Normal file
View File

@ -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 `<glib/gprintf.h>` 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]

18
glib/gprintf.c
View File

@ -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

43
glib/gstrfuncs.c
View File

@ -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 `<glib/gprintf.h>` 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