fold_string_w(3)fold_string_w(3)NAMEfold_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
Specifies one or more of the following flags: Folds compatibility zone
characters into standard Unicode equivalents. For information on com‐
patibility zone characters, see the DESCRIPTION section. Maps all dig‐
its to Unicode ASCII 0 to 9. Maps accented characters to precomposed
characters. In this transformation, the multiple accent and base char‐
acter values are combined into a single character value. The MAP_PRE‐
COMPOSED 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
The fold_string_w() function maps one wide-character string to another
and performs the specified Unicode character transformation. The func‐
tion then stores the transformed wide-character string in the destina‐
tion buffer and returns the number of wide characters stored. The sup‐
ported operations include the following: Transform separate values for
accent and base characters into a single value for an accented charac‐
ter 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 char‐
acters 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 stan‐
dards. Applications use the MAP_FOLDZONE flag to avoid support‐
ing compatibility zone characters that are duplicates of those
in Unicode.
The src_cnt value determines when the function stops processing charac‐
ters. If src_cnt is -1, then character processing stops when a null is
encountered. In this case, the null terminator is included in the des‐
tination 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 char‐
acters required for dest_wcs but does not store the transforma‐
tion 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 charac‐
ters 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 speci‐
fied 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_PRECOM‐
POSED and MAP_COMPOSITE flags are specified on the same call. The des‐
tination buffer is not large enough to store the transformed wide-char‐
acter string.
fold_string_w(3)