NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       #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 );

LIBRARY    [Toc]    [Back]

       UCS4 Library (libucs4)

PARAMETERS    [Toc]    [Back]

       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  precomposed
       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 characters)
       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    [Toc]    [Back]

       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 compatibility
              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 transformed 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    [Toc]    [Back]

       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    [Toc]    [Back]

       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  parameter  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 transformed wide-character
       string.



                                                 fold_string_w(3)