C API: Charset Detection API.

Required Header

#include <utils_i18n.h>

Overview

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 created from the serialized form.

Functions
int	i18n_ucnvsel_create (const char const converter_list, int32_t converter_list_size, const i18n_uset_h excluded_code_points, const i18n_ucnv_unicode_set_e which_set, i18n_uconverter_selector_h *sel)
	Creates an i18n_uconverter_selector_h.
int	i18n_ucnvsel_destroy (i18n_uconverter_selector_h sel)
	Destroys an i18n_uconverter_selector_h.
int	i18n_ucnvsel_create_from_serialized (const void buffer, int32_t length, i18n_uconverter_selector_h sel)
	Creates an i18n_uconverter_selector_h from its serialized form.
int	i18n_ucnvsel_serialize (const i18n_uconverter_selector_h sel, void buffer, int32_t buffer_capacity, int32_t capacity)
	Serializes a selector into a linear buffer.
int	i18n_ucnvsel_select_for_string (const i18n_uconverter_selector_h sel, const i18n_uchar string, int32_t length, i18n_uenumeration_h enumeration)
	Selects converters that can map all characters in a UTF-16 string, ignoring the excluded code points.
int	i18n_ucnvsel_select_for_utf8 (const i18n_uconverter_selector_h sel, const char string, int32_t length, i18n_uenumeration_h enumeration)
	Selects converters that can map all characters in a UTF-8 string, ignoring the excluded code points.
Typedefs
typedef void *	i18n_uconverter_selector_h
	An i18n_uconverter_selector_h handle.

Typedef Documentation

typedef void* i18n_uconverter_selector_h

An i18n_uconverter_selector_h handle.

Since :: 6.0

Function Documentation

int i18n_ucnvsel_create	(	const char const	converter_list,
		int32_t	converter_list_size,
		const i18n_uset_h	excluded_code_points,
		const i18n_ucnv_unicode_set_e	which_set,
		i18n_uconverter_selector_h *	sel
	)

Creates an i18n_uconverter_selector_h.

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

Since :: 6.0

Remarks:: The sel should be released using i18n_ucnvsel_destroy().

Parameters:

[in]	converter_list	A pointer to encoding names needed to be involved. Can be NULL if converter_list_size ==0. The list and the names will be cloned, and the caller retains ownership of the original.
[in]	converter_list_size	Number of encodings in above list. If 0, builds a selector for all available converters.
[in]	excluded_code_points	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.
[in]	which_set	What converter set to use? Use this to determine whether to consider only roundtrip mappings or also fallbacks.
[out]	sel	The new selector.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucnvsel_create_from_serialized	(	const void *	buffer,
		int32_t	length,
		i18n_uconverter_selector_h *	sel
	)

Creates an i18n_uconverter_selector_h 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.

Since :: 6.0

Remarks:: The sel should be released using i18n_ucnvsel_destroy().

Parameters:

[in]	buffer	Pointer to the serialized form of a converter selector; must be 32-bit-aligned
[in]	length	The capacity of this buffer (can be equal to or larger than the actual data length)
[out]	sel	The new selector.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucnvsel_destroy ( i18n_uconverter_selector_h sel )

Destroys an i18n_uconverter_selector_h.

If any enumerations were returned by i18n_ucnvsel*, they become invalid. They can be destroyed before or after calling i18n_ucnv_destroy, but should never be used after the selector is destroyed.

Since :: 6.0

Parameters:

[in] sel The selector to destroy.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucnvsel_select_for_string	(	const i18n_uconverter_selector_h	sel,
		const i18n_uchar *	string,
		int32_t	length,
		i18n_uenumeration_h *	enumeration
	)

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

Since :: 6.0

Remarks:: The enumeration is valid until sel is released.

Parameters:

[in]	sel	An i18n_uconverter_selector_h
[in]	string	UTF-16 string
[in]	length	Length of the string, or -1 if NUL-terminated
[out]	enumeration	An enumeration containing encoding names. The returned encoding names and their order will be the same as supplied when building the selector.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

 int main() {
    i18n_uenumeration_h enumeration = NULL;
    i18n_uconverter_selector_h sel;
    i18n_uset_h excluded_set = NULL;
    const char *char_str = "Hello World!";
    const i18n_uchar string[20] = {0,};
    i18n_error_code_e error_code;
    int32_t length;

    i18n_ustring_from_UTF8((i18n_uchar *)string, I18N_UPRV_LENGTHOF(string), &length, char_str, 5, &error_code);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_ustring_from_UTF8: %d\n", error_code);
        return EXIT_FAILURE;
    }

    error_code = i18n_uset_create_empty(&excluded_set);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_uset_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }

    error_code = i18n_ucnvsel_create(NULL, 0, excluded_set, I18N_UCNV_ROUNDTRIP_AND_FALLBACK_SET, &sel);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_ucnvsel_create: %d\n", error_code);
        i18n_uset_destroy(excluded_set);
        return EXIT_FAILURE;
    }

    error_code = i18n_ucnvsel_select_for_string(sel, string, length, &enumeration);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_ucnvsel_select_for_string: %d\n", error_code);
        i18n_uset_destroy(excluded_set);
        i18n_ucnvsel_destroy(sel);
        return EXIT_FAILURE;
    }

    i18n_uset_destroy(excluded_set);
    i18n_ucnvsel_destroy(sel);
    return EXIT_SUCCESS;
 }

int i18n_ucnvsel_select_for_utf8	(	const i18n_uconverter_selector_h	sel,
		const char *	string,
		int32_t	length,
		i18n_uenumeration_h *	enumeration
	)

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

Since :: 6.0

Remarks:: The enumeration is valid until sel is released.

Parameters:

[in]	sel	An i18n_uconverter_selector_h
[in]	string	UTF-8 string
[in]	length	Length of the string, or -1 if NUL-terminated
[out]	enumeration	An enumeration containing encoding names. The returned encoding names and their order will be the same as supplied when building the selector.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
 #include <utils_i18n.h>

 int main() {
    i18n_uenumeration_h enumeration = NULL;
    i18n_uconverter_selector_h sel;
    i18n_uset_h excluded_set = NULL;
    const char *string = "Hello World!";
    i18n_error_code_e error_code;

    error_code = i18n_uset_create_empty(&excluded_set);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_uset_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }

    error_code = i18n_ucnvsel_create(NULL, 0, excluded_set, I18N_UCNV_ROUNDTRIP_AND_FALLBACK_SET, &sel);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_ucnvsel_create: %d\n", error_code);
        i18n_uset_destroy(excluded_set);
        return EXIT_FAILURE;
    }

    error_code = i18n_ucnvsel_select_for_utf8(sel, string, strlen(string), &enumeration);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_ucnvsel_select_for_utf8: %d\n", error_code);
        i18n_ucnvsel_destroy(sel);
        i18n_uset_destroy(excluded_set);
        return EXIT_FAILURE;
    }

    i18n_ucnvsel_destroy(sel);
    i18n_uset_destroy(excluded_set);
    return EXIT_SUCCESS;
 }

int i18n_ucnvsel_serialize	(	const i18n_uconverter_selector_h	sel,
		void *	buffer,
		int32_t	buffer_capacity,
		int32_t *	capacity
	)

Serializes a selector into a linear buffer.

The serialized form is portable to different machines.

Since :: 6.0

Parameters:

[in]	sel	Selector to consider
[in]	buffer	Pointer to 32-bit-aligned memory to be filled with the serialized form of this converter selector
[in]	buffer_capacity	The capacity of this buffer
[out]	capacity	The required buffer capacity to hold serialize data

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation