fold_string_w(3)					     Library Functions Manual						  fold_string_w(3)

NAME

       fold_string_w - Maps one wide-character string to another, performing the specified Unicode character transformation

LIBRARY

       UCS4 Library (libucs4)

SYNOPSIS

       #include <ucs4.h>

       int fold_string_w(
	       unsigned long map_flags,
	       const wchar_t *src_wcs,
	       int src_cnt,
	       wchar_t *dest_wcs,
	       int dest_cnt );

PARAMETERS

       Specifies  one  or  more of the following flags: Folds compatibility zone characters into standard Unicode equivalents.	For information on
       compatibility zone characters, see the DESCRIPTION section.  Maps all digits to Unicode ASCII 0 to 9.  Maps accented characters to  precom-
       posed  characters.  In  this  transformation, the multiple accent and base character values are combined into a single character value. The
       MAP_PRECOMPOSED flag cannot be combined with the MAP_COMPOSITE flag.
       Maps accented characters to composite characters. In this transformation, the single value for an accented  character  is  decomposed  into
       multiple  values for the base and accented characters.  The MAP_COMPOSITE flag cannot be combined with the MAP_PRECOMPOSED flag.  Points to
       a source buffer containing the wide-character string whose characters are to be transformed.  Specifies the size (in number of wide charac-
       ters)  of  the  source  buffer.	 If  the wide-character string in the source buffer is null-terminated, applications can specify -1 as the
       src_cnt value and the function calculates the length of the string automatically.  Points to a destination buffer to store the  transformed
       wide-character string.  Specifies the size (in number of wide characters) of the destination buffer.

DESCRIPTION

       The  fold_string_w()  function  maps one wide-character string to another and performs the specified Unicode character transformation.  The
       function then stores the transformed wide-character string in the destination buffer and returns the number of wide characters stored.  The
       supported  operations  include  the following: Transform separate values for accent and base characters into a single value for an accented
       character Transform a single value for an accented character into separate values for accent and base characters Transform all digit values
       to Unicode ASCII 0 to 9.  for digits Transform all compatibility zone characters into standard Unicode equivalents

	      The  compatibility zone in Unicode consists of characters that are in the range 0xF900 to 0xFFEF (values assigned to characters from
	      other encoding standards) but are variants of characters that already exist in Unicode.  The compatibility zone is used  to  support
	      round-trip  mapping  of characters to and from these standards.  Applications use the MAP_FOLDZONE flag to avoid supporting compati-
	      bility zone characters that are duplicates of those in Unicode.

       The src_cnt value determines when the function stops processing characters.  If src_cnt is -1, then character processing stops when a  null
       is encountered.	In this case, the null terminator is included in the destination string and also included in the return count.	Otherwise,
       nulls are treated as other characters and may be embedded in the source string. In this case, the return count and destination  string  may
       or may not include a null.

       The  fold_string_w()  function  fails if dest_wcs is too small to contain the transformed string. The application can avoid this failure in
       one of the following ways: Allocate a buffer size large enough to store transformed strings resulting from any call to fold_string_w() Call
       fold_string_w()	twice for each string transformation, once to calculate the length of the destination string and again to store the trans-
       formed string

	      If an application calls fold_string_w() with dest_cnt set to 0 (zero), the function calculates and returns the number of	characters
	      required	for  dest_wcs but does not store the transformation results in dest_wcs. The application can then specify the return value
	      from the first call as the value for dest_wcs on a second call, on which the transformation results are stored.

       The src_wcs and dest_wcs parameters cannot point to the same location.  If they do, the function fails and sets errno to EINVAL.

RETURN VALUES

       On success, the fold_string_w() function returns the number of characters written to the destination wide-character  string.   On  failure,
       the function returns 0 (zero) and sets errno to indicate the reason for failure.

ERRORS

       The  fold_string_w()  function  sets  errno  to the following values for the specified conditions: Insufficient memory is available for the
       specified operations.  A possible cause of this condition is a src_cnt value of -1 when the source string is not null terminated.  A param-
       eter  value  is invalid; for example, the source and destination strings point to the same location.  This error can also occur if both the
       MAP_PRECOMPOSED and MAP_COMPOSITE flags are specified on the same call.	The destination buffer is not large enough  to	store  the  trans-
       formed wide-character string.  delim off

																  fold_string_w(3)