1/* Iterating through multibyte strings: macros for multi-byte encodings.
2   Copyright (C) 2001, 2005, 2007, 2009-2014 Free Software Foundation, Inc.
3
4   This program is free software: you can redistribute it and/or modify
5   it under the terms of the GNU General Public License as published by
6   the Free Software Foundation; either version 3 of the License, or
7   (at your option) any later version.
8
9   This program 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 General Public License for more details.
13
14   You should have received a copy of the GNU General Public License
15   along with this program.  If not, see <http://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#include <assert.h>
86#include <stdbool.h>
87#include <stddef.h>
88#include <string.h>
89
90/* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
91   <wchar.h>.
92   BSD/OS 4.1 has a bug: <stdio.h> and <time.h> must be included before
93   <wchar.h>.  */
94#include <stdio.h>
95#include <time.h>
96#include <wchar.h>
97
98#include "mbchar.h"
99
100#ifndef _GL_INLINE_HEADER_BEGIN
101 #error "Please include config.h first."
102#endif
103_GL_INLINE_HEADER_BEGIN
104#ifndef MBITER_INLINE
105# define MBITER_INLINE _GL_INLINE
106#endif
107
108struct mbiter_multi
109{
110  const char *limit;    /* pointer to end of string */
111  bool in_shift;        /* true if next byte may not be interpreted as ASCII */
112  mbstate_t state;      /* if in_shift: current shift state */
113  bool next_done;       /* true if mbi_avail has already filled the following */
114  struct mbchar cur;    /* the current character:
115        const char *cur.ptr             pointer to current character
116        The following are only valid after mbi_avail.
117        size_t cur.bytes                number of bytes of current character
118        bool cur.wc_valid               true if wc is a valid wide character
119        wchar_t cur.wc                  if wc_valid: the current character
120        */
121};
122
123MBITER_INLINE void
124mbiter_multi_next (struct mbiter_multi *iter)
125{
126  if (iter->next_done)
127    return;
128  if (iter->in_shift)
129    goto with_shift;
130  /* Handle most ASCII characters quickly, without calling mbrtowc().  */
131  if (is_basic (*iter->cur.ptr))
132    {
133      /* These characters are part of the basic character set.  ISO C 99
134         guarantees that their wide character code is identical to their
135         char code.  */
136      iter->cur.bytes = 1;
137      iter->cur.wc = *iter->cur.ptr;
138      iter->cur.wc_valid = true;
139    }
140  else
141    {
142      assert (mbsinit (&iter->state));
143      iter->in_shift = true;
144    with_shift:
145      iter->cur.bytes = mbrtowc (&iter->cur.wc, iter->cur.ptr,
146                                 iter->limit - iter->cur.ptr, &iter->state);
147      if (iter->cur.bytes == (size_t) -1)
148        {
149          /* An invalid multibyte sequence was encountered.  */
150          iter->cur.bytes = 1;
151          iter->cur.wc_valid = false;
152          /* Whether to set iter->in_shift = false and reset iter->state
153             or not is not very important; the string is bogus anyway.  */
154        }
155      else if (iter->cur.bytes == (size_t) -2)
156        {
157          /* An incomplete multibyte character at the end.  */
158          iter->cur.bytes = iter->limit - iter->cur.ptr;
159          iter->cur.wc_valid = false;
160          /* Whether to set iter->in_shift = false and reset iter->state
161             or not is not important; the string end is reached anyway.  */
162        }
163      else
164        {
165          if (iter->cur.bytes == 0)
166            {
167              /* A null wide character was encountered.  */
168              iter->cur.bytes = 1;
169              assert (*iter->cur.ptr == '\0');
170              assert (iter->cur.wc == 0);
171            }
172          iter->cur.wc_valid = true;
173
174          /* When in the initial state, we can go back treating ASCII
175             characters more quickly.  */
176          if (mbsinit (&iter->state))
177            iter->in_shift = false;
178        }
179    }
180  iter->next_done = true;
181}
182
183MBITER_INLINE void
184mbiter_multi_reloc (struct mbiter_multi *iter, ptrdiff_t ptrdiff)
185{
186  iter->cur.ptr += ptrdiff;
187  iter->limit += ptrdiff;
188}
189
190MBITER_INLINE void
191mbiter_multi_copy (struct mbiter_multi *new_iter, const struct mbiter_multi *old_iter)
192{
193  new_iter->limit = old_iter->limit;
194  if ((new_iter->in_shift = old_iter->in_shift))
195    memcpy (&new_iter->state, &old_iter->state, sizeof (mbstate_t));
196  else
197    memset (&new_iter->state, 0, sizeof (mbstate_t));
198  new_iter->next_done = old_iter->next_done;
199  mb_copy (&new_iter->cur, &old_iter->cur);
200}
201
202/* Iteration macros.  */
203typedef struct mbiter_multi mbi_iterator_t;
204#define mbi_init(iter, startptr, length) \
205  ((iter).cur.ptr = (startptr), (iter).limit = (iter).cur.ptr + (length), \
206   (iter).in_shift = false, memset (&(iter).state, '\0', sizeof (mbstate_t)), \
207   (iter).next_done = false)
208#define mbi_avail(iter) \
209  ((iter).cur.ptr < (iter).limit && (mbiter_multi_next (&(iter)), true))
210#define mbi_advance(iter) \
211  ((iter).cur.ptr += (iter).cur.bytes, (iter).next_done = false)
212
213/* Access to the current character.  */
214#define mbi_cur(iter) (iter).cur
215#define mbi_cur_ptr(iter) (iter).cur.ptr
216
217/* Relocation.  */
218#define mbi_reloc(iter, ptrdiff) mbiter_multi_reloc (&iter, ptrdiff)
219
220/* Copying an iterator.  */
221#define mbi_copy mbiter_multi_copy
222
223_GL_INLINE_HEADER_END
224
225#endif /* _MBITER_H */
226