towctrans

towctrans is a function in the C standard library that applies a locale-dependent wide-character transformation to a single wide character. It is declared in <wchar.h> and is used together with a transformation descriptor obtained from wctrans. The function operates on wide characters represented as wint_t and is part of the wide-character APIs that support locale-aware case mapping and other character transformations.

Prototype and behavior: wint_t towctrans(wint_t wc, wctrans_t tx); The first parameter wc is the input wide character. The second parameter tx is a transformation descriptor created by wctrans, which describes the desired transformation (for example, to uppercase, to lowercase, or other locale-defined mappings). The function returns the transformed wide character as a wint_t. If wc is WEOF or if an error occurs, WEOF is returned. If no mapping exists for the given character, some implementations may return wc unchanged, but this behavior is not guaranteed and depends on the locale and implementation.

Transformation descriptors: A descriptor is obtained by calling wctrans with a string that names the transformation, such as "toupper", "tolower", or "fold" (the available transformations are implementation- and locale-dependent). The descriptor is then passed to towctrans to produce the transformed character. This mechanism allows more flexible and locale-aware transformations beyond the standard towupper and towlower functions.

Availability and notes: towctrans is defined by the C standard library and is available in many modern C environments that support wide characters and locales. Its exact set of supported transformations and behavior can vary across platforms, so developers should consult their implementation’s documentation for specifics.

See also: wctrans, towupper, towlower, towcswz (related wide-character utilities).