include/unicode/ucnvsel.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *
0006 *   Copyright (C) 2008-2011, International Business Machines
0007 *   Corporation, Google and others.  All Rights Reserved.
0008 *
0009 *******************************************************************************
0010 */
0011 /*
0012  * Author : eldawy@google.com (Mohamed Eldawy)
0013  * ucnvsel.h
0014  *
0015  * Purpose: To generate a list of encodings capable of handling
0016  * a given Unicode text
0017  *
0018  * Started 09-April-2008
0019  */
0020
0021 #ifndef __ICU_UCNV_SEL_H__
0022 #define __ICU_UCNV_SEL_H__
0023
0024 #include "unicode/utypes.h"
0025
0026 #if !UCONFIG_NO_CONVERSION
0027
0028 #include "unicode/uset.h"
0029 #include "unicode/utf16.h"
0030 #include "unicode/uenum.h"
0031 #include "unicode/ucnv.h"
0032
0033 #if U_SHOW_CPLUSPLUS_API
0034 #include "unicode/localpointer.h"
0035 #endif   // U_SHOW_CPLUSPLUS_API
0036
0037 /**
0038  * \file
0039  * \brief C API: Encoding/charset encoding selector
0040  *
0041  * A converter selector is built with a set of encoding/charset names
0042  * and given an input string returns the set of names of the
0043  * corresponding converters which can convert the string.
0044  *
0045  * A converter selector can be serialized into a buffer and reopened
0046  * from the serialized form.
0047  */
0048
0049 struct UConverterSelector;
0050 /**
0051  * @{
0052  * Typedef for selector data structure.
0053  */
0054 typedef struct UConverterSelector UConverterSelector;
0055 /** @} */
0056
0057 /**
0058  * Open a selector.
0059  * If converterListSize is 0, build for all available converters.
0060  * If excludedCodePoints is NULL, don't exclude any code points.
0061  *
0062  * @param converterList a pointer to encoding names needed to be involved.
0063  *                      Can be NULL if converterListSize==0.
0064  *                      The list and the names will be cloned, and the caller
0065  *                      retains ownership of the original.
0066  * @param converterListSize number of encodings in above list.
0067  *                          If 0, builds a selector for all available converters.
0068  * @param excludedCodePoints a set of code points to be excluded from consideration.
0069  *                           That is, excluded code points in a string do not change
0070  *                           the selection result. (They might be handled by a callback.)
0071  *                           Use NULL to exclude nothing.
0072  * @param whichSet what converter set to use? Use this to determine whether
0073  *                 to consider only roundtrip mappings or also fallbacks.
0074  * @param status an in/out ICU UErrorCode
0075  * @return the new selector
0076  *
0077  * @stable ICU 4.2
0078  */
0079 U_CAPI UConverterSelector* U_EXPORT2
0080 ucnvsel_open(const char* const*  converterList, int32_t converterListSize,
0081              const USet* excludedCodePoints,
0082              const UConverterUnicodeSet whichSet, UErrorCode* status);
0083
0084 /**
0085  * Closes a selector.
0086  * If any Enumerations were returned by ucnv_select*, they become invalid.
0087  * They can be closed before or after calling ucnv_closeSelector,
0088  * but should never be used after the selector is closed.
0089  *
0090  * @see ucnv_selectForString
0091  * @see ucnv_selectForUTF8
0092  *
0093  * @param sel selector to close
0094  *
0095  * @stable ICU 4.2
0096  */
0097 U_CAPI void U_EXPORT2
0098 ucnvsel_close(UConverterSelector *sel);
0099
0100 #if U_SHOW_CPLUSPLUS_API
0101
0102 U_NAMESPACE_BEGIN
0103
0104 /**
0105  * \class LocalUConverterSelectorPointer
0106  * "Smart pointer" class, closes a UConverterSelector via ucnvsel_close().
0107  * For most methods see the LocalPointerBase base class.
0108  *
0109  * @see LocalPointerBase
0110  * @see LocalPointer
0111  * @stable ICU 4.4
0112  */
0113 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close);
0114
0115 U_NAMESPACE_END
0116
0117 #endif
0118
0119 /**
0120  * Open a selector from its serialized form.
0121  * The buffer must remain valid and unchanged for the lifetime of the selector.
0122  * This is much faster than creating a selector from scratch.
0123  * Using a serialized form from a different machine (endianness/charset) is supported.
0124  *
0125  * @param buffer pointer to the serialized form of a converter selector;
0126  *               must be 32-bit-aligned
0127  * @param length the capacity of this buffer (can be equal to or larger than
0128  *               the actual data length)
0129  * @param status an in/out ICU UErrorCode
0130  * @return the new selector
0131  *
0132  * @stable ICU 4.2
0133  */
0134 U_CAPI UConverterSelector* U_EXPORT2
0135 ucnvsel_openFromSerialized(const void* buffer, int32_t length, UErrorCode* status);
0136
0137 /**
0138  * Serialize a selector into a linear buffer.
0139  * The serialized form is portable to different machines.
0140  *
0141  * @param sel selector to consider
0142  * @param buffer pointer to 32-bit-aligned memory to be filled with the
0143  *               serialized form of this converter selector
0144  * @param bufferCapacity the capacity of this buffer
0145  * @param status an in/out ICU UErrorCode
0146  * @return the required buffer capacity to hold serialize data (even if the call fails
0147  *         with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity)
0148  *
0149  * @stable ICU 4.2
0150  */
0151 U_CAPI int32_t U_EXPORT2
0152 ucnvsel_serialize(const UConverterSelector* sel,
0153                   void* buffer, int32_t bufferCapacity, UErrorCode* status);
0154
0155 /**
0156  * Select converters that can map all characters in a UTF-16 string,
0157  * ignoring the excluded code points.
0158  *
0159  * @param sel a selector
0160  * @param s UTF-16 string
0161  * @param length length of the string, or -1 if NUL-terminated
0162  * @param status an in/out ICU UErrorCode
0163  * @return an enumeration containing encoding names.
0164  *         The returned encoding names and their order will be the same as
0165  *         supplied when building the selector.
0166  *
0167  * @stable ICU 4.2
0168  */
0169 U_CAPI UEnumeration * U_EXPORT2
0170 ucnvsel_selectForString(const UConverterSelector* sel,
0171                         const UChar *s, int32_t length, UErrorCode *status);
0172
0173 /**
0174  * Select converters that can map all characters in a UTF-8 string,
0175  * ignoring the excluded code points.
0176  *
0177  * @param sel a selector
0178  * @param s UTF-8 string
0179  * @param length length of the string, or -1 if NUL-terminated
0180  * @param status an in/out ICU UErrorCode
0181  * @return an enumeration containing encoding names.
0182  *         The returned encoding names and their order will be the same as
0183  *         supplied when building the selector.
0184  *
0185  * @stable ICU 4.2
0186  */
0187 U_CAPI UEnumeration * U_EXPORT2
0188 ucnvsel_selectForUTF8(const UConverterSelector* sel,
0189                       const char *s, int32_t length, UErrorCode *status);
0190
0191 #endif  /* !UCONFIG_NO_CONVERSION */
0192
0193 #endif  /* __ICU_UCNV_SEL_H__ */