lib/mbiter.h

   1 /* Iterating through multibyte strings: macros for multi-byte encodings.
   2    Copyright (C) 2001, 2005, 2007, 2009-2020 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 <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 #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
 108 struct 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
 123 MBITER_INLINE void
 124 mbiter_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
 183 MBITER_INLINE void
 184 mbiter_multi_reloc (struct mbiter_multi *iter, ptrdiff_t ptrdiff)
 185 {
 186   iter->cur.ptr += ptrdiff;
 187   iter->limit += ptrdiff;
 188 }
 189
 190 MBITER_INLINE void
 191 mbiter_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.  */
 203 typedef 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 */