mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-24 16:40:06 +01:00
a8537918bc
Commit 425731f7 moved string utils docs to a Markdown file, but one of the paragraph headings was left broken.
188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
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
|
||
|
||
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]
|