Line | Count | Source (jump to first uncovered line) |
1 | | /* Iterating through multibyte strings: macros for multi-byte encodings. |
2 | | Copyright (C) 2001, 2005, 2007, 2009-2025 Free Software Foundation, Inc. |
3 | | |
4 | | This file is free software: you can redistribute it and/or modify |
5 | | it under the terms of the GNU Lesser General Public License as |
6 | | published by the Free Software Foundation; either version 2.1 of the |
7 | | License, or (at your option) any later version. |
8 | | |
9 | | This file is distributed in the hope that it will be useful, |
10 | | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12 | | GNU Lesser General Public License for more details. |
13 | | |
14 | | You should have received a copy of the GNU Lesser General Public License |
15 | | along with this program. If not, see <https://www.gnu.org/licenses/>. */ |
16 | | |
17 | | /* Written by Bruno Haible <bruno@clisp.org>. */ |
18 | | |
19 | | /* The macros in this file implement forward iteration through a |
20 | | multi-byte string. |
21 | | |
22 | | With these macros, an iteration loop that looks like |
23 | | |
24 | | char *iter; |
25 | | for (iter = buf; iter < buf + buflen; iter++) |
26 | | { |
27 | | do_something (*iter); |
28 | | } |
29 | | |
30 | | becomes |
31 | | |
32 | | mbi_iterator_t iter; |
33 | | for (mbi_init (iter, buf, buflen); mbi_avail (iter); mbi_advance (iter)) |
34 | | { |
35 | | do_something (mbi_cur_ptr (iter), mb_len (mbi_cur (iter))); |
36 | | } |
37 | | |
38 | | The benefit of these macros over plain use of mbrtowc is: |
39 | | - Handling of invalid multibyte sequences is possible without |
40 | | making the code more complicated, while still preserving the |
41 | | invalid multibyte sequences. |
42 | | |
43 | | mbi_iterator_t |
44 | | is a type usable for variable declarations. |
45 | | |
46 | | mbi_init (iter, startptr, length) |
47 | | initializes the iterator, starting at startptr and crossing length bytes. |
48 | | |
49 | | mbi_avail (iter) |
50 | | returns true if there are more multibyte characters available before |
51 | | the end of string is reached. In this case, mbi_cur (iter) is |
52 | | initialized to the next multibyte character. |
53 | | |
54 | | mbi_advance (iter) |
55 | | advances the iterator by one multibyte character. |
56 | | |
57 | | mbi_cur (iter) |
58 | | returns the current multibyte character, of type mbchar_t. All the |
59 | | macros defined in mbchar.h can be used on it. |
60 | | |
61 | | mbi_cur_ptr (iter) |
62 | | return a pointer to the beginning of the current multibyte character. |
63 | | |
64 | | mbi_reloc (iter, ptrdiff) |
65 | | relocates iterator when the string is moved by ptrdiff bytes. |
66 | | |
67 | | mbi_copy (&destiter, &srciter) |
68 | | copies srciter to destiter. |
69 | | |
70 | | Here are the function prototypes of the macros. |
71 | | |
72 | | extern void mbi_init (mbi_iterator_t iter, |
73 | | const char *startptr, size_t length); |
74 | | extern bool mbi_avail (mbi_iterator_t iter); |
75 | | extern void mbi_advance (mbi_iterator_t iter); |
76 | | extern mbchar_t mbi_cur (mbi_iterator_t iter); |
77 | | extern const char * mbi_cur_ptr (mbi_iterator_t iter); |
78 | | extern void mbi_reloc (mbi_iterator_t iter, ptrdiff_t ptrdiff); |
79 | | extern void mbi_copy (mbi_iterator_t *new, const mbi_iterator_t *old); |
80 | | */ |
81 | | |
82 | | #ifndef _MBITER_H |
83 | | #define _MBITER_H 1 |
84 | | |
85 | | /* This file uses _GL_INLINE_HEADER_BEGIN, _GL_INLINE, |
86 | | _GL_ATTRIBUTE_ALWAYS_INLINE. */ |
87 | | #if !_GL_CONFIG_H_INCLUDED |
88 | | #error "Please include config.h first." |
89 | | #endif |
90 | | |
91 | | #include <assert.h> |
92 | | #include <stddef.h> |
93 | | #include <string.h> |
94 | | #include <uchar.h> |
95 | | #include <wchar.h> |
96 | | |
97 | | #include "mbchar.h" |
98 | | |
99 | | _GL_INLINE_HEADER_BEGIN |
100 | | #ifndef MBITER_INLINE |
101 | | # define MBITER_INLINE _GL_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE |
102 | | #endif |
103 | | |
104 | | #ifdef __cplusplus |
105 | | extern "C" { |
106 | | #endif |
107 | | |
108 | | |
109 | | struct mbiter_multi |
110 | | { |
111 | | const char *limit; /* pointer to end of string */ |
112 | | #if !GNULIB_MBRTOC32_REGULAR |
113 | | bool in_shift; /* true if next byte may not be interpreted as ASCII */ |
114 | | /* If GNULIB_MBRTOC32_REGULAR, it is always false, |
115 | | so optimize it away. */ |
116 | | #endif |
117 | | mbstate_t state; /* if in_shift: current shift state */ |
118 | | /* If GNULIB_MBRTOC32_REGULAR, it is in an initial state |
119 | | before and after every mbiter_multi_next invocation. |
120 | | */ |
121 | | bool next_done; /* true if mbi_avail has already filled the following */ |
122 | | struct mbchar cur; /* the current character: |
123 | | const char *cur.ptr pointer to current character |
124 | | The following are only valid after mbi_avail. |
125 | | size_t cur.bytes number of bytes of current character |
126 | | bool cur.wc_valid true if wc is a valid 32-bit wide character |
127 | | char32_t cur.wc if wc_valid: the current character |
128 | | */ |
129 | | }; |
130 | | |
131 | | MBITER_INLINE void |
132 | | mbiter_multi_next (struct mbiter_multi *iter) |
133 | 0 | { |
134 | 0 | if (iter->next_done) |
135 | 0 | return; |
136 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
137 | 0 | if (iter->in_shift) |
138 | 0 | goto with_shift; |
139 | 0 | #endif |
140 | | /* Handle most ASCII characters quickly, without calling mbrtowc(). */ |
141 | 0 | if (is_basic (*iter->cur.ptr)) |
142 | 0 | { |
143 | | /* These characters are part of the POSIX portable character set. |
144 | | For most of them, namely those in the ISO C basic character set, |
145 | | ISO C 99 guarantees that their wide character code is identical to |
146 | | their char code. For the few other ones, this is the case as well, |
147 | | in all locale encodings that are in use. The 32-bit wide character |
148 | | code is the same as well. */ |
149 | 0 | iter->cur.bytes = 1; |
150 | 0 | iter->cur.wc = *iter->cur.ptr; |
151 | 0 | iter->cur.wc_valid = true; |
152 | 0 | } |
153 | 0 | else |
154 | 0 | { |
155 | 0 | assert (mbsinit (&iter->state)); |
156 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
157 | 0 | iter->in_shift = true; |
158 | 0 | with_shift: |
159 | 0 | #endif |
160 | 0 | iter->cur.bytes = mbrtoc32 (&iter->cur.wc, iter->cur.ptr, |
161 | 0 | iter->limit - iter->cur.ptr, &iter->state); |
162 | 0 | if (iter->cur.bytes == (size_t) -1) |
163 | 0 | { |
164 | | /* An invalid multibyte sequence was encountered. */ |
165 | 0 | iter->cur.bytes = 1; |
166 | 0 | iter->cur.wc_valid = false; |
167 | | /* Allow the next invocation to continue from a sane state. */ |
168 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
169 | 0 | iter->in_shift = false; |
170 | 0 | #endif |
171 | 0 | mbszero (&iter->state); |
172 | 0 | } |
173 | 0 | else if (iter->cur.bytes == (size_t) -2) |
174 | 0 | { |
175 | | /* An incomplete multibyte character at the end. */ |
176 | 0 | iter->cur.bytes = iter->limit - iter->cur.ptr; |
177 | 0 | iter->cur.wc_valid = false; |
178 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
179 | | /* Cause the next mbi_avail invocation to return false. */ |
180 | 0 | iter->in_shift = false; |
181 | 0 | #endif |
182 | | /* Whether to reset iter->state or not is not important; the |
183 | | string end is reached anyway. */ |
184 | 0 | } |
185 | 0 | else |
186 | 0 | { |
187 | 0 | if (iter->cur.bytes == 0) |
188 | 0 | { |
189 | | /* A null wide character was encountered. */ |
190 | 0 | iter->cur.bytes = 1; |
191 | 0 | assert (*iter->cur.ptr == '\0'); |
192 | 0 | assert (iter->cur.wc == 0); |
193 | 0 | } |
194 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
195 | 0 | else if (iter->cur.bytes == (size_t) -3) |
196 | | /* The previous multibyte sequence produced an additional 32-bit |
197 | | wide character. */ |
198 | 0 | iter->cur.bytes = 0; |
199 | 0 | #endif |
200 | 0 | iter->cur.wc_valid = true; |
201 | | |
202 | | /* When in an initial state, we can go back treating ASCII |
203 | | characters more quickly. */ |
204 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
205 | 0 | if (mbsinit (&iter->state)) |
206 | 0 | iter->in_shift = false; |
207 | 0 | #endif |
208 | 0 | } |
209 | 0 | } |
210 | 0 | iter->next_done = true; |
211 | 0 | } |
212 | | |
213 | | MBITER_INLINE void |
214 | | mbiter_multi_reloc (struct mbiter_multi *iter, ptrdiff_t ptrdiff) |
215 | 0 | { |
216 | 0 | iter->cur.ptr += ptrdiff; |
217 | 0 | iter->limit += ptrdiff; |
218 | 0 | } |
219 | | |
220 | | MBITER_INLINE void |
221 | | mbiter_multi_copy (struct mbiter_multi *new_iter, const struct mbiter_multi *old_iter) |
222 | 0 | { |
223 | 0 | new_iter->limit = old_iter->limit; |
224 | 0 | #if !GNULIB_MBRTOC32_REGULAR |
225 | 0 | if ((new_iter->in_shift = old_iter->in_shift)) |
226 | 0 | memcpy (&new_iter->state, &old_iter->state, sizeof (mbstate_t)); |
227 | 0 | else |
228 | 0 | #endif |
229 | 0 | mbszero (&new_iter->state); |
230 | 0 | new_iter->next_done = old_iter->next_done; |
231 | 0 | mb_copy (&new_iter->cur, &old_iter->cur); |
232 | 0 | } |
233 | | |
234 | | /* Iteration macros. */ |
235 | | typedef struct mbiter_multi mbi_iterator_t; |
236 | | #if !GNULIB_MBRTOC32_REGULAR |
237 | | #define mbi_init(iter, startptr, length) \ |
238 | 0 | ((iter).cur.ptr = (startptr), (iter).limit = (iter).cur.ptr + (length), \ |
239 | 0 | (iter).in_shift = false, mbszero (&(iter).state), \ |
240 | 0 | (iter).next_done = false) |
241 | | #else |
242 | | /* Optimized: no in_shift. */ |
243 | | #define mbi_init(iter, startptr, length) \ |
244 | | ((iter).cur.ptr = (startptr), (iter).limit = (iter).cur.ptr + (length), \ |
245 | | mbszero (&(iter).state), \ |
246 | | (iter).next_done = false) |
247 | | #endif |
248 | | #if !GNULIB_MBRTOC32_REGULAR |
249 | | #define mbi_avail(iter) \ |
250 | 0 | (((iter).cur.ptr < (iter).limit || (iter).in_shift) \ |
251 | 0 | && (mbiter_multi_next (&(iter)), true)) |
252 | | #else |
253 | | /* Optimized: no in_shift. */ |
254 | | #define mbi_avail(iter) \ |
255 | | ((iter).cur.ptr < (iter).limit \ |
256 | | && (mbiter_multi_next (&(iter)), true)) |
257 | | #endif |
258 | | #define mbi_advance(iter) \ |
259 | 0 | ((iter).cur.ptr += (iter).cur.bytes, (iter).next_done = false) |
260 | | |
261 | | /* Access to the current character. */ |
262 | 0 | #define mbi_cur(iter) (iter).cur |
263 | | #define mbi_cur_ptr(iter) (iter).cur.ptr |
264 | | |
265 | | /* Relocation. */ |
266 | | #define mbi_reloc(iter, ptrdiff) mbiter_multi_reloc (&iter, ptrdiff) |
267 | | |
268 | | /* Copying an iterator. */ |
269 | | #define mbi_copy mbiter_multi_copy |
270 | | |
271 | | |
272 | | #ifdef __cplusplus |
273 | | } |
274 | | #endif |
275 | | |
276 | | _GL_INLINE_HEADER_END |
277 | | |
278 | | #endif /* _MBITER_H */ |