1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/ucnvsel.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,187 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2008-2011, International Business Machines
1.8 +* Corporation, Google and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +*/
1.12 +/*
1.13 + * Author : eldawy@google.com (Mohamed Eldawy)
1.14 + * ucnvsel.h
1.15 + *
1.16 + * Purpose: To generate a list of encodings capable of handling
1.17 + * a given Unicode text
1.18 + *
1.19 + * Started 09-April-2008
1.20 + */
1.21 +
1.22 +#ifndef __ICU_UCNV_SEL_H__
1.23 +#define __ICU_UCNV_SEL_H__
1.24 +
1.25 +#include "unicode/utypes.h"
1.26 +
1.27 +#if !UCONFIG_NO_CONVERSION
1.28 +
1.29 +#include "unicode/uset.h"
1.30 +#include "unicode/utf16.h"
1.31 +#include "unicode/uenum.h"
1.32 +#include "unicode/ucnv.h"
1.33 +#include "unicode/localpointer.h"
1.34 +
1.35 +/**
1.36 + * \file
1.37 + *
1.38 + * A converter selector is built with a set of encoding/charset names
1.39 + * and given an input string returns the set of names of the
1.40 + * corresponding converters which can convert the string.
1.41 + *
1.42 + * A converter selector can be serialized into a buffer and reopened
1.43 + * from the serialized form.
1.44 + */
1.45 +
1.46 +/**
1.47 + * @{
1.48 + * The selector data structure
1.49 + */
1.50 +struct UConverterSelector;
1.51 +typedef struct UConverterSelector UConverterSelector;
1.52 +/** @} */
1.53 +
1.54 +/**
1.55 + * Open a selector.
1.56 + * If converterListSize is 0, build for all available converters.
1.57 + * If excludedCodePoints is NULL, don't exclude any code points.
1.58 + *
1.59 + * @param converterList a pointer to encoding names needed to be involved.
1.60 + * Can be NULL if converterListSize==0.
1.61 + * The list and the names will be cloned, and the caller
1.62 + * retains ownership of the original.
1.63 + * @param converterListSize number of encodings in above list.
1.64 + * If 0, builds a selector for all available converters.
1.65 + * @param excludedCodePoints a set of code points to be excluded from consideration.
1.66 + * That is, excluded code points in a string do not change
1.67 + * the selection result. (They might be handled by a callback.)
1.68 + * Use NULL to exclude nothing.
1.69 + * @param whichSet what converter set to use? Use this to determine whether
1.70 + * to consider only roundtrip mappings or also fallbacks.
1.71 + * @param status an in/out ICU UErrorCode
1.72 + * @return the new selector
1.73 + *
1.74 + * @stable ICU 4.2
1.75 + */
1.76 +U_STABLE UConverterSelector* U_EXPORT2
1.77 +ucnvsel_open(const char* const* converterList, int32_t converterListSize,
1.78 + const USet* excludedCodePoints,
1.79 + const UConverterUnicodeSet whichSet, UErrorCode* status);
1.80 +
1.81 +/**
1.82 + * Closes a selector.
1.83 + * If any Enumerations were returned by ucnv_select*, they become invalid.
1.84 + * They can be closed before or after calling ucnv_closeSelector,
1.85 + * but should never be used after the selector is closed.
1.86 + *
1.87 + * @see ucnv_selectForString
1.88 + * @see ucnv_selectForUTF8
1.89 + *
1.90 + * @param sel selector to close
1.91 + *
1.92 + * @stable ICU 4.2
1.93 + */
1.94 +U_STABLE void U_EXPORT2
1.95 +ucnvsel_close(UConverterSelector *sel);
1.96 +
1.97 +#if U_SHOW_CPLUSPLUS_API
1.98 +
1.99 +U_NAMESPACE_BEGIN
1.100 +
1.101 +/**
1.102 + * \class LocalUConverterSelectorPointer
1.103 + * "Smart pointer" class, closes a UConverterSelector via ucnvsel_close().
1.104 + * For most methods see the LocalPointerBase base class.
1.105 + *
1.106 + * @see LocalPointerBase
1.107 + * @see LocalPointer
1.108 + * @stable ICU 4.4
1.109 + */
1.110 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close);
1.111 +
1.112 +U_NAMESPACE_END
1.113 +
1.114 +#endif
1.115 +
1.116 +/**
1.117 + * Open a selector from its serialized form.
1.118 + * The buffer must remain valid and unchanged for the lifetime of the selector.
1.119 + * This is much faster than creating a selector from scratch.
1.120 + * Using a serialized form from a different machine (endianness/charset) is supported.
1.121 + *
1.122 + * @param buffer pointer to the serialized form of a converter selector;
1.123 + * must be 32-bit-aligned
1.124 + * @param length the capacity of this buffer (can be equal to or larger than
1.125 + * the actual data length)
1.126 + * @param status an in/out ICU UErrorCode
1.127 + * @return the new selector
1.128 + *
1.129 + * @stable ICU 4.2
1.130 + */
1.131 +U_STABLE UConverterSelector* U_EXPORT2
1.132 +ucnvsel_openFromSerialized(const void* buffer, int32_t length, UErrorCode* status);
1.133 +
1.134 +/**
1.135 + * Serialize a selector into a linear buffer.
1.136 + * The serialized form is portable to different machines.
1.137 + *
1.138 + * @param sel selector to consider
1.139 + * @param buffer pointer to 32-bit-aligned memory to be filled with the
1.140 + * serialized form of this converter selector
1.141 + * @param bufferCapacity the capacity of this buffer
1.142 + * @param status an in/out ICU UErrorCode
1.143 + * @return the required buffer capacity to hold serialize data (even if the call fails
1.144 + * with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity)
1.145 + *
1.146 + * @stable ICU 4.2
1.147 + */
1.148 +U_STABLE int32_t U_EXPORT2
1.149 +ucnvsel_serialize(const UConverterSelector* sel,
1.150 + void* buffer, int32_t bufferCapacity, UErrorCode* status);
1.151 +
1.152 +/**
1.153 + * Select converters that can map all characters in a UTF-16 string,
1.154 + * ignoring the excluded code points.
1.155 + *
1.156 + * @param sel a selector
1.157 + * @param s UTF-16 string
1.158 + * @param length length of the string, or -1 if NUL-terminated
1.159 + * @param status an in/out ICU UErrorCode
1.160 + * @return an enumeration containing encoding names.
1.161 + * The returned encoding names and their order will be the same as
1.162 + * supplied when building the selector.
1.163 + *
1.164 + * @stable ICU 4.2
1.165 + */
1.166 +U_STABLE UEnumeration * U_EXPORT2
1.167 +ucnvsel_selectForString(const UConverterSelector* sel,
1.168 + const UChar *s, int32_t length, UErrorCode *status);
1.169 +
1.170 +/**
1.171 + * Select converters that can map all characters in a UTF-8 string,
1.172 + * ignoring the excluded code points.
1.173 + *
1.174 + * @param sel a selector
1.175 + * @param s UTF-8 string
1.176 + * @param length length of the string, or -1 if NUL-terminated
1.177 + * @param status an in/out ICU UErrorCode
1.178 + * @return an enumeration containing encoding names.
1.179 + * The returned encoding names and their order will be the same as
1.180 + * supplied when building the selector.
1.181 + *
1.182 + * @stable ICU 4.2
1.183 + */
1.184 +U_STABLE UEnumeration * U_EXPORT2
1.185 +ucnvsel_selectForUTF8(const UConverterSelector* sel,
1.186 + const char *s, int32_t length, UErrorCode *status);
1.187 +
1.188 +#endif /* !UCONFIG_NO_CONVERSION */
1.189 +
1.190 +#endif /* __ICU_UCNV_SEL_H__ */
