File: string-utils.md

package info (click to toggle)
glib2.0 2.84.1-2
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 66,144 kB
  • sloc: ansic: 538,877; python: 9,624; sh: 1,572; xml: 1,482; perl: 1,222; cpp: 535; makefile: 316; javascript: 11
file content (187 lines) | stat: -rw-r--r-- 5,048 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
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

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]