ICU 74.2: common/unicode/ucnvsel.h File Reference

ICU 74.2 74.2

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.

## Functions
U_CAPI UConverterSelector * | ucnvsel_open (const char *const *converterList, int32_t converterListSize, const USet *excludedCodePoints, const UConverterUnicodeSet whichSet, UErrorCode *status)
| Open a selector.
U_CAPI void | ucnvsel_close (UConverterSelector *sel)
| Closes a selector.
U_CAPI UConverterSelector * | ucnvsel_openFromSerialized (const void *buffer, int32_t length, UErrorCode *status)
| Open a selector from its serialized form.
U_CAPI int32_t | ucnvsel_serialize (const UConverterSelector *sel, void *buffer, int32_t bufferCapacity, UErrorCode *status)
| Serialize a selector into a linear buffer.
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.
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.

## 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 struct UConverterSelector 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

  sel | selector 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

  converterList | a 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.
  converterListSize | number of encodings in above list. If 0, builds a selector for all available converters.
  excludedCodePoints | a 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.
  whichSet | what converter set to use? Use this to determine whether to consider only roundtrip mappings or also fallbacks.
  status | an 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

  buffer | pointer to the serialized form of a converter selector; must be 32-bit-aligned
  length | the capacity of this buffer (can be equal to or larger than the actual data length)
  status | an 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

  sel | a selector
  s | UTF-16 string
  length | length of the string, or -1 if NUL-terminated
  status | an 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

  sel | a selector
  s | UTF-8 string
  length | length of the string, or -1 if NUL-terminated
  status | an 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

  sel | selector to consider
  buffer | pointer to 32-bit-aligned memory to be filled with the serialized form of this converter selector
  bufferCapacity | the capacity of this buffer
  status | an 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