Index for Section 3

Alphabetical listing for F

Bottom of page

fold_string_w(3)
NAME
  fold_string_w - maps one wide-character string to another, performing the
  specified Unicode character transformation

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

LIBRARY
  UCS4 Library (libucs4)

PARAMETERS
  map_flags
      Specifies one or more of the following flags:

      MAP_FOLDCZONE
	      Folds compatibility zone characters into standard Unicode
	      equivalents. For information on compatibility zone characters,
	      see the DESCRIPTION section.

      MAP_FOLDDIGITS
	      Maps all digits to Unicode ASCII 0 to 9.

      MAP_PRECOMPOSED
	      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.

      MAP_COMPOSITE
	      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.

  src_wcs
      Points to a source buffer containing the wide-character string whose
      characters are to be transformed.

  src_cnt
      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.

  dest_wcs
      Points to a destination buffer to store the transformed wide-character
      string.

  dest_cnt
      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 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
  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:

  [ENOMEM]
      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.

  [EINVAL]
      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.

  [ENOBUFS]
      The destination buffer is not large enough to store the transformed
      wide-character string.

Index for Section 3

Alphabetical listing for F

Top of page