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