mbstowcs

mbstowcs

Convert a Multibyte Character Sequence to a Wide Sequence

Portability: ISO/ANSI C conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
EXAMPLE

SYNOPSIS

#include <stdlib.h>

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

DESCRIPTION

mbstowcs converts a sequence of multibyte characters (mixed DBCS sequence) pointed to by s into a sequence of corresponding wide characters (pure DBCS sequence) and stores the output sequence in the array pointed to by pwcs . The multibyte character sequence is assumed to begin in the initial shift state.

n specifies the maximum number of wide characters to be stored.

RETURN VALUE

If the multibyte character sequence is valid, mbstowcs returns the number of elements of pwcs that were modified, excluding the terminating 0 code, if any. If the sequence of multibyte characters is invalid, mbstowcs returns -1 .

CAUTIONS

No multibyte characters that follow a null character are examined or converted. If the sequence you want to convert contains such a value in the middle, you should use a loop that calls mbtowc .

If copying takes place between objects that overlap, the behavior of mbstowcs is undefined.

A diagnostic is not issued if mbstowcs encounters invalid data; a return value of -1 is the only indication of an error.

EXAMPLE

This example replaces all occurences of a given character in a mixed DBCS string. The string is assumed to have a maximum length of 81 characters. This example uses mbstowcs and wcstomb .

#include <locale.h>
#include <limits.h>
#include <stdlib.h>
#include <stdio.h>

#define MAX_CHARACTERS 81
   /* "old_string" is the input MIXED DBCS string. "new_string" */
   /* is the output MIXED DBCS string. "old_wchar" is the       */
   /* multibyte character to be  replaced. "new_wchar" is the   */
   /* multibyte character to replace with.                      */
void mbsrepl(char *old_string, char *new_string,
             wchar_t old_wchar, wchar_t new_wchar)
{
   wchar_t work[MAX_CHARACTERS];
   int nchars;
   int i;

      /* Inform library that we will be accepting a DBCS string.*/
      /* That is, SO and SI are not regular control characters: */
      /* they indicate a change in shift state.                 */
   setlocale(LC_ALL, "dbcs");

   nchars = mbstowcs(work, old_string, MAX_CHARACTERS);
   if (nchars < 0) {
      fputs("Invalid DBCS string.\n", stderr);
      fclose(stderr);
      abort();
   }

      /* Perform the actual substitution.                       */
      for (i = 0; i < nchars; i++)
          if (work[i] ==  old_wchar)
              work[i] = new_wchar;

      /* Convert back to MIXED format.                          */
   nchars = wcstombs(new_string, work, MAX_CHARACTERS);

      /* See if the replacement caused the string to overflow.  */
   if (nchars == MAX_CHARACTERS) {
      fputs("Replacement string too large.\n", stderr);
      abort();
      fclose(stderr);
   }
}

Chapter Contents
Previous
Next
Top of Page