ICU 72.1 72.1
Namespaces | Functions
ucnvsel.h File Reference

C API: Encoding/charset encoding selector. More...

#include "unicode/utypes.h"
#include "unicode/uset.h"
#include "unicode/utf16.h"
#include "unicode/uenum.h"
#include "unicode/ucnv.h"
#include "unicode/localpointer.h"

Go to the source code of this file.

Namespaces

namespace  icu
 File coll.h.
 

Typedefs

typedef struct UConverterSelector UConverterSelector
 Typedef for selector data structure. More...
 

Functions

U_CAPI UConverterSelectorucnvsel_open (const char *const *converterList, int32_t converterListSize, const USet *excludedCodePoints, const UConverterUnicodeSet whichSet, UErrorCode *status)
 Open a selector. More...
 
U_CAPI void ucnvsel_close (UConverterSelector *sel)
 Closes a selector. More...
 
U_CAPI UConverterSelectorucnvsel_openFromSerialized (const void *buffer, int32_t length, UErrorCode *status)
 Open a selector from its serialized form. More...
 
U_CAPI int32_t ucnvsel_serialize (const UConverterSelector *sel, void *buffer, int32_t bufferCapacity, UErrorCode *status)
 Serialize a selector into a linear buffer. More...
 
U_CAPI UEnumerationucnvsel_selectForString (const UConverterSelector *sel, const UChar *s, int32_t length, UErrorCode *status)
 Select converters that can map all characters in a UTF-16 string, ignoring the excluded code points. More...
 
U_CAPI UEnumerationucnvsel_selectForUTF8 (const UConverterSelector *sel, const char *s, int32_t length, UErrorCode *status)
 Select converters that can map all characters in a UTF-8 string, ignoring the excluded code points. More...
 

Detailed Description

C API: Encoding/charset encoding selector.

A converter selector is built with a set of encoding/charset names and given an input string returns the set of names of the corresponding converters which can convert the string.

A converter selector can be serialized into a buffer and reopened from the serialized form.

Definition in file ucnvsel.h.

Typedef Documentation

◆ UConverterSelector

Typedef for selector data structure.

Definition at line 54 of file ucnvsel.h.

Function Documentation

◆ ucnvsel_close()

U_CAPI void ucnvsel_close ( UConverterSelector sel)

Closes a selector.

If any Enumerations were returned by ucnv_select*, they become invalid. They can be closed before or after calling ucnv_closeSelector, but should never be used after the selector is closed.

See also
ucnv_selectForString
ucnv_selectForUTF8
Parameters
selselector to close
Stable:
ICU 4.2

◆ ucnvsel_open()

U_CAPI UConverterSelector * ucnvsel_open ( const char *const *  converterList,
int32_t  converterListSize,
const USet excludedCodePoints,
const UConverterUnicodeSet  whichSet,
UErrorCode status 
)

Open a selector.

If converterListSize is 0, build for all available converters. If excludedCodePoints is NULL, don't exclude any code points.

Parameters
converterLista pointer to encoding names needed to be involved. Can be NULL if converterListSize==0. The list and the names will be cloned, and the caller retains ownership of the original.
converterListSizenumber of encodings in above list. If 0, builds a selector for all available converters.
excludedCodePointsa set of code points to be excluded from consideration. That is, excluded code points in a string do not change the selection result. (They might be handled by a callback.) Use NULL to exclude nothing.
whichSetwhat converter set to use? Use this to determine whether to consider only roundtrip mappings or also fallbacks.
statusan in/out ICU UErrorCode
Returns
the new selector
Stable:
ICU 4.2

◆ ucnvsel_openFromSerialized()

U_CAPI UConverterSelector * ucnvsel_openFromSerialized ( const void *  buffer,
int32_t  length,
UErrorCode status 
)

Open a selector from its serialized form.

The buffer must remain valid and unchanged for the lifetime of the selector. This is much faster than creating a selector from scratch. Using a serialized form from a different machine (endianness/charset) is supported.

Parameters
bufferpointer to the serialized form of a converter selector; must be 32-bit-aligned
lengththe capacity of this buffer (can be equal to or larger than the actual data length)
statusan in/out ICU UErrorCode
Returns
the new selector
Stable:
ICU 4.2

◆ ucnvsel_selectForString()

U_CAPI UEnumeration * ucnvsel_selectForString ( const UConverterSelector sel,
const UChar s,
int32_t  length,
UErrorCode status 
)

Select converters that can map all characters in a UTF-16 string, ignoring the excluded code points.

Parameters
sela selector
sUTF-16 string
lengthlength of the string, or -1 if NUL-terminated
statusan in/out ICU UErrorCode
Returns
an enumeration containing encoding names. The returned encoding names and their order will be the same as supplied when building the selector.
Stable:
ICU 4.2

◆ ucnvsel_selectForUTF8()

U_CAPI UEnumeration * ucnvsel_selectForUTF8 ( const UConverterSelector sel,
const char *  s,
int32_t  length,
UErrorCode status 
)

Select converters that can map all characters in a UTF-8 string, ignoring the excluded code points.

Parameters
sela selector
sUTF-8 string
lengthlength of the string, or -1 if NUL-terminated
statusan in/out ICU UErrorCode
Returns
an enumeration containing encoding names. The returned encoding names and their order will be the same as supplied when building the selector.
Stable:
ICU 4.2

◆ ucnvsel_serialize()

U_CAPI int32_t ucnvsel_serialize ( const UConverterSelector sel,
void *  buffer,
int32_t  bufferCapacity,
UErrorCode status 
)

Serialize a selector into a linear buffer.

The serialized form is portable to different machines.

Parameters
selselector to consider
bufferpointer to 32-bit-aligned memory to be filled with the serialized form of this converter selector
bufferCapacitythe capacity of this buffer
statusan in/out ICU UErrorCode
Returns
the required buffer capacity to hold serialize data (even if the call fails with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity)
Stable:
ICU 4.2