--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-08-16  Bruno Haible  <bruno@clisp.org>
+
+	* modules/mbiter: New file.
+	* MODULES.html.sh (Extended multibyte and wide character utilities):
+	Add mbiter.
+
 2005-08-16  Bruno Haible  <bruno@clisp.org>
 
 	* modules/mbchar: New file.

--- a/MODULES.html.sh
+++ b/MODULES.html.sh
@@ -1746,7 +1746,7 @@
 
   func_begin_table
   func_module mbchar
-  #func_module mbiter
+  func_module mbiter
   #func_module mbfile
   func_end_table
 

--- a/lib/ChangeLog
+++ b/lib/ChangeLog
@@ -1,3 +1,7 @@
+2005-08-16  Bruno Haible  <bruno@clisp.org>
+
+	* mbiter.h: New file.
+
 2005-08-16  Bruno Haible  <bruno@clisp.org>
 
 	* mbchar.h: New file.

new file mode 100644
--- /dev/null
+++ b/lib/mbiter.h
@@ -0,0 +1,195 @@
+/* Iterating through multibyte strings: macros for multi-byte encodings.
+   Copyright (C) 2001, 2005 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2, or (at your option)
+   any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software Foundation,
+   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
+
+/* Written by Bruno Haible <bruno@clisp.org>.  */
+
+/* The macros in this file implement forward iteration through a
+   multi-byte string.
+
+   With these macros, an iteration loop that looks like
+
+      char *iter;
+      for (iter = buf; iter < buf + buflen; iter++)
+        {
+          do_something (*iter);
+        }
+
+   becomes
+
+      mbi_iterator_t iter;
+      for (mbi_init (iter, buf, buflen); mbi_avail (iter); mbi_advance (iter))
+        {
+          do_something (mbi_cur_ptr (iter), mb_len (mbi_cur (iter)));
+        }
+
+   The benefit of these macros over plain use of mbrtowc is:
+   - Handling of invalid multibyte sequences is possible without
+     making the code more complicated, while still preserving the
+     invalid multibyte sequences.
+
+   mbi_iterator_t
+     is a type usable for variable declarations.
+
+   mbi_init (iter, startptr, length)
+     initializes the iterator, starting at startptr and crossing length bytes.
+
+   mbi_avail (iter)
+     returns true if there are more multibyte chracters available before
+     the end of string is reached. In this case, mbi_cur (iter) is
+     initialized to the next multibyte chracter.
+
+   mbi_advance (iter)
+     advances the iterator by one multibyte character.
+
+   mbi_cur (iter)
+     returns the current multibyte character, of type MB_CHAR.  All the macros
+     defined in mbchar_multi.h can be used on it.
+
+   mbi_cur_ptr (iter)
+     return a pointer to the beginning of the current multibyte character.
+
+   mbi_reloc (iter, ptrdiff)
+     relocates iterator when the string is moved by ptrdiff bytes.
+
+   Here are the function prototypes of the macros.
+
+   extern void		mbi_init (mbi_iterator_t iter,
+				  const char *startptr, size_t length);
+   extern bool		mbi_avail (mbi_iterator_t iter);
+   extern void		mbi_advance (mbi_iterator_t iter);
+   extern mbchar_t	mbi_cur (mbi_iterator_t iter);
+   extern const char *	mbi_cur_ptr (mbi_iterator_t iter);
+   extern void		mbi_reloc (mbi_iterator_t iter, ptrdiff_t ptrdiff);
+ */
+
+#ifndef _MBITER_H
+#define _MBITER_H 1
+
+#include <assert.h>
+#include <stdbool.h>
+
+/* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
+   <wchar.h>.
+   BSD/OS 4.1 has a bug: <stdio.h> and <time.h> must be included before
+   <wchar.h>.  */
+#include <stdio.h>
+#include <time.h>
+#include <wchar.h>
+
+#include "mbchar.h"
+
+struct mbiter_multi
+{
+  const char *limit;	/* pointer to end of string */
+  bool in_shift;	/* true if next byte may not be interpreted as ASCII */
+  mbstate_t state;	/* if in_shift: current shift state */
+  bool next_done;	/* true if mbi_avail has already filled the following */
+  struct mbchar cur;	/* the current character:
+	const char *cur.ptr		pointer to current character
+	The following are only valid after mbi_avail.
+	size_t cur.bytes		number of bytes of current character
+	bool cur.wc_valid		true if wc is a valid wide character
+	wchar_t cur.wc			if wc_valid: the current character
+	*/
+};
+
+static inline void
+mbiter_multi_next (struct mbiter_multi *iter)
+{
+  if (iter->next_done)
+    return;
+  if (iter->in_shift)
+    goto with_shift;
+  /* Handle most ASCII characters quickly, without calling mbrtowc().  */
+  if (is_basic (*iter->cur.ptr))
+    {
+      /* These characters are part of the basic character set.  ISO C 99
+	 guarantees that their wide character code is identical to their
+	 char code.  */
+      iter->cur.bytes = 1;
+      iter->cur.wc = *iter->cur.ptr;
+      iter->cur.wc_valid = true;
+    }
+  else
+    {
+      assert (mbsinit (&iter->state));
+      iter->in_shift = true;
+    with_shift:
+      iter->cur.bytes = mbrtowc (&iter->cur.wc, iter->cur.ptr,
+				 iter->limit - iter->cur.ptr, &iter->state);
+      if (iter->cur.bytes == (size_t) -1)
+	{
+	  /* An invalid multibyte sequence was encountered.  */
+	  iter->cur.bytes = 1;
+	  iter->cur.wc_valid = false;
+	  /* Whether to set iter->in_shift = false and reset iter->state
+	     or not is not very important; the string is bogus anyway.  */
+	}
+      else if (iter->cur.bytes == (size_t) -2)
+	{
+	  /* An incomplete multibyte character at the end.  */
+	  iter->cur.bytes = iter->limit - iter->cur.ptr;
+	  iter->cur.wc_valid = false;
+	  /* Whether to set iter->in_shift = false and reset iter->state
+	     or not is not important; the string end is reached anyway.  */
+	}
+      else
+	{
+	  if (iter->cur.bytes == 0)
+	    {
+	      /* A null wide character was encountered.  */
+	      iter->cur.bytes = 1;
+	      assert (*iter->cur.ptr == '\0');
+	      assert (iter->cur.wc == 0);
+	    }
+	  iter->cur.wc_valid = true;
+
+	  /* When in the initial state, we can go back treating ASCII
+	     characters more quickly.  */
+	  if (mbsinit (&iter->state))
+	    iter->in_shift = false;
+	}
+    }
+  iter->next_done = true;
+}
+
+static inline void
+mbiter_multi_reloc (struct mbiter_multi *iter, ptrdiff_t ptrdiff)
+{
+  iter->cur.ptr += ptrdiff;
+  iter->limit += ptrdiff;
+}
+
+/* Iteration macros.  */
+typedef struct mbiter_multi mbi_iterator_t;
+#define mbi_init(iter, startptr, length) \
+  ((iter).cur.ptr = (startptr), (iter).limit = (iter).cur.ptr + (length), \
+   (iter).in_shift = false, memset (&(iter).state, '\0', sizeof (mbstate_t)), \
+   (iter).next_done = false)
+#define mbi_avail(iter) \
+  ((iter).cur.ptr < (iter).limit && (mbiter_multi_next (&(iter)), true))
+#define mbi_advance(iter) \
+  ((iter).cur.ptr += (iter).cur.bytes, (iter).next_done = false)
+
+/* Access to the current character.  */
+#define mbi_cur(iter) (iter).cur
+#define mbi_cur_ptr(iter) (iter).cur.ptr
+
+/* Relocation.  */
+#define mbi_reloc(iter, ptrdiff) mbiter_multi_reloc (&iter, ptrdiff)
+
+#endif /* _MBITER_H */

--- a/m4/ChangeLog
+++ b/m4/ChangeLog
@@ -1,3 +1,7 @@
+2005-08-16  Bruno Haible  <bruno@clisp.org>
+
+	* mbiter.m4: New file.
+
 2005-08-16  Bruno Haible  <bruno@clisp.org>
 
 	* mbchar.m4: New file.

new file mode 100644
--- /dev/null
+++ b/m4/mbiter.m4
@@ -0,0 +1,14 @@
+# mbiter.m4 serial 1
+dnl Copyright (C) 2005 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+dnl autoconf tests required for use of mbiter.h
+dnl From Bruno Haible.
+
+AC_DEFUN([gl_MBITER],
+[
+  AC_REQUIRE([AC_TYPE_MBSTATE_T])
+  :
+])

new file mode 100644
--- /dev/null
+++ b/modules/mbiter
@@ -0,0 +1,26 @@
+Description:
+Iterating through multibyte strings.
+
+Files:
+lib/mbiter.h
+m4/mbiter.m4
+
+Depends-on:
+mbchar
+stdbool
+
+configure.ac:
+gl_MBITER
+
+Makefile.am:
+lib_SOURCES += mbiter.h
+
+Include:
+"mbiter.h"
+
+License:
+LGPL
+
+Maintainer:
+Bruno Haible
+