ucnvsel.h File Reference

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. 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
	icu
	File coll.h.

Typedefs
typedef struct UConverterSelector	UConverterSelector

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

Detailed Description

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.

Function Documentation

ucnvsel_close()

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()

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()

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()

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()

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()

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