lib/mbiter.h

   1 /* Iterating through multibyte strings: macros for multi-byte encodings.
   2    Copyright (C) 2001, 2005 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 2, or (at your option)
   7    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, write to the Free Software Foundation,
  16    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  17
  18 /* Written by Bruno Haible <bruno@clisp.org>.  */
  19
  20 /* The macros in this file implement forward iteration through a
  21    multi-byte string.
  22
  23    With these macros, an iteration loop that looks like
  24
  25       char *iter;
  26       for (iter = buf; iter < buf + buflen; iter++)
  27         {
  28           do_something (*iter);
  29         }
  30
  31    becomes
  32
  33       mbi_iterator_t iter;
  34       for (mbi_init (iter, buf, buflen); mbi_avail (iter); mbi_advance (iter))
  35         {
  36           do_something (mbi_cur_ptr (iter), mb_len (mbi_cur (iter)));
  37         }
  38
  39    The benefit of these macros over plain use of mbrtowc is:
  40    - Handling of invalid multibyte sequences is possible without
  41      making the code more complicated, while still preserving the
  42      invalid multibyte sequences.
  43
  44    mbi_iterator_t
  45      is a type usable for variable declarations.
  46
  47    mbi_init (iter, startptr, length)
  48      initializes the iterator, starting at startptr and crossing length bytes.
  49
  50    mbi_avail (iter)
  51      returns true if there are more multibyte chracters available before
  52      the end of string is reached. In this case, mbi_cur (iter) is
  53      initialized to the next multibyte chracter.
  54
  55    mbi_advance (iter)
  56      advances the iterator by one multibyte character.
  57
  58    mbi_cur (iter)
  59      returns the current multibyte character, of type mbchar_t.  All the
  60      macros defined in mbchar.h can be used on it.
  61
  62    mbi_cur_ptr (iter)
  63      return a pointer to the beginning of the current multibyte character.
  64
  65    mbi_reloc (iter, ptrdiff)
  66      relocates iterator when the string is moved by ptrdiff bytes.
  67
  68    Here are the function prototypes of the macros.
  69
  70    extern void          mbi_init (mbi_iterator_t iter,
  71                                   const char *startptr, size_t length);
  72    extern bool          mbi_avail (mbi_iterator_t iter);
  73    extern void          mbi_advance (mbi_iterator_t iter);
  74    extern mbchar_t      mbi_cur (mbi_iterator_t iter);
  75    extern const char *  mbi_cur_ptr (mbi_iterator_t iter);
  76    extern void          mbi_reloc (mbi_iterator_t iter, ptrdiff_t ptrdiff);
  77  */
  78
  79 #ifndef _MBITER_H
  80 #define _MBITER_H 1
  81
  82 #include <assert.h>
  83 #include <stdbool.h>
  84
  85 /* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
  86    <wchar.h>.
  87    BSD/OS 4.1 has a bug: <stdio.h> and <time.h> must be included before
  88    <wchar.h>.  */
  89 #include <stdio.h>
  90 #include <time.h>
  91 #include <wchar.h>
  92
  93 #include "mbchar.h"
  94
  95 struct mbiter_multi
  96 {
  97   const char *limit;    /* pointer to end of string */
  98   bool in_shift;        /* true if next byte may not be interpreted as ASCII */
  99   mbstate_t state;      /* if in_shift: current shift state */
 100   bool next_done;       /* true if mbi_avail has already filled the following */
 101   struct mbchar cur;    /* the current character:
 102         const char *cur.ptr             pointer to current character
 103         The following are only valid after mbi_avail.
 104         size_t cur.bytes                number of bytes of current character
 105         bool cur.wc_valid               true if wc is a valid wide character
 106         wchar_t cur.wc                  if wc_valid: the current character
 107         */
 108 };
 109
 110 static inline void
 111 mbiter_multi_next (struct mbiter_multi *iter)
 112 {
 113   if (iter->next_done)
 114     return;
 115   if (iter->in_shift)
 116     goto with_shift;
 117   /* Handle most ASCII characters quickly, without calling mbrtowc().  */
 118   if (is_basic (*iter->cur.ptr))
 119     {
 120       /* These characters are part of the basic character set.  ISO C 99
 121          guarantees that their wide character code is identical to their
 122          char code.  */
 123       iter->cur.bytes = 1;
 124       iter->cur.wc = *iter->cur.ptr;
 125       iter->cur.wc_valid = true;
 126     }
 127   else
 128     {
 129       assert (mbsinit (&iter->state));
 130       iter->in_shift = true;
 131     with_shift:
 132       iter->cur.bytes = mbrtowc (&iter->cur.wc, iter->cur.ptr,
 133                                  iter->limit - iter->cur.ptr, &iter->state);
 134       if (iter->cur.bytes == (size_t) -1)
 135         {
 136           /* An invalid multibyte sequence was encountered.  */
 137           iter->cur.bytes = 1;
 138           iter->cur.wc_valid = false;
 139           /* Whether to set iter->in_shift = false and reset iter->state
 140              or not is not very important; the string is bogus anyway.  */
 141         }
 142       else if (iter->cur.bytes == (size_t) -2)
 143         {
 144           /* An incomplete multibyte character at the end.  */
 145           iter->cur.bytes = iter->limit - iter->cur.ptr;
 146           iter->cur.wc_valid = false;
 147           /* Whether to set iter->in_shift = false and reset iter->state
 148              or not is not important; the string end is reached anyway.  */
 149         }
 150       else
 151         {
 152           if (iter->cur.bytes == 0)
 153             {
 154               /* A null wide character was encountered.  */
 155               iter->cur.bytes = 1;
 156               assert (*iter->cur.ptr == '\0');
 157               assert (iter->cur.wc == 0);
 158             }
 159           iter->cur.wc_valid = true;
 160
 161           /* When in the initial state, we can go back treating ASCII
 162              characters more quickly.  */
 163           if (mbsinit (&iter->state))
 164             iter->in_shift = false;
 165         }
 166     }
 167   iter->next_done = true;
 168 }
 169
 170 static inline void
 171 mbiter_multi_reloc (struct mbiter_multi *iter, ptrdiff_t ptrdiff)
 172 {
 173   iter->cur.ptr += ptrdiff;
 174   iter->limit += ptrdiff;
 175 }
 176
 177 /* Iteration macros.  */
 178 typedef struct mbiter_multi mbi_iterator_t;
 179 #define mbi_init(iter, startptr, length) \
 180   ((iter).cur.ptr = (startptr), (iter).limit = (iter).cur.ptr + (length), \
 181    (iter).in_shift = false, memset (&(iter).state, '\0', sizeof (mbstate_t)), \
 182    (iter).next_done = false)
 183 #define mbi_avail(iter) \
 184   ((iter).cur.ptr < (iter).limit && (mbiter_multi_next (&(iter)), true))
 185 #define mbi_advance(iter) \
 186   ((iter).cur.ptr += (iter).cur.bytes, (iter).next_done = false)
 187
 188 /* Access to the current character.  */
 189 #define mbi_cur(iter) (iter).cur
 190 #define mbi_cur_ptr(iter) (iter).cur.ptr
 191
 192 /* Relocation.  */
 193 #define mbi_reloc(iter, ptrdiff) mbiter_multi_reloc (&iter, ptrdiff)
 194
 195 #endif /* _MBITER_H */