The Tor Browser: intl/icu/source/common/unicode/ucnvsel.h@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     1 /*

     2 *******************************************************************************

3 *

     4 *   Copyright (C) 2008-2011, International Business Machines

     5 *   Corporation, Google and others.  All Rights Reserved.

6 *

     7 *******************************************************************************

     8 */

     9 /*

    10  * Author : eldawy@google.com (Mohamed Eldawy)

    11  * ucnvsel.h

    12  *

    13  * Purpose: To generate a list of encodings capable of handling

    14  * a given Unicode text

    15  *

    16  * Started 09-April-2008

    17  */

    19 #ifndef __ICU_UCNV_SEL_H__

    20 #define __ICU_UCNV_SEL_H__

    22 #include "unicode/utypes.h"

    24 #if !UCONFIG_NO_CONVERSION

    26 #include "unicode/uset.h"

    27 #include "unicode/utf16.h"

    28 #include "unicode/uenum.h"

    29 #include "unicode/ucnv.h"

    30 #include "unicode/localpointer.h"

    32 /**

    33  * \file

    34  *

    35  * A converter selector is built with a set of encoding/charset names

    36  * and given an input string returns the set of names of the

    37  * corresponding converters which can convert the string.

    38  *

    39  * A converter selector can be serialized into a buffer and reopened

    40  * from the serialized form.

    41  */

    43 /**

    44  * @{

    45  * The selector data structure

    46  */

    47 struct UConverterSelector;

    48 typedef struct UConverterSelector UConverterSelector;

    49 /** @} */

    51 /**

    52  * Open a selector.

    53  * If converterListSize is 0, build for all available converters.

    54  * If excludedCodePoints is NULL, don't exclude any code points.

    55  *

    56  * @param converterList a pointer to encoding names needed to be involved.

    57  *                      Can be NULL if converterListSize==0.

    58  *                      The list and the names will be cloned, and the caller

    59  *                      retains ownership of the original.

    60  * @param converterListSize number of encodings in above list.

    61  *                          If 0, builds a selector for all available converters.

    62  * @param excludedCodePoints a set of code points to be excluded from consideration.

    63  *                           That is, excluded code points in a string do not change

    64  *                           the selection result. (They might be handled by a callback.)

    65  *                           Use NULL to exclude nothing.

    66  * @param whichSet what converter set to use? Use this to determine whether

    67  *                 to consider only roundtrip mappings or also fallbacks.

    68  * @param status an in/out ICU UErrorCode

    69  * @return the new selector

    70  *

    71  * @stable ICU 4.2

    72  */

    73 U_STABLE UConverterSelector* U_EXPORT2

    74 ucnvsel_open(const char* const*  converterList, int32_t converterListSize,

    75              const USet* excludedCodePoints,

    76              const UConverterUnicodeSet whichSet, UErrorCode* status);

    78 /**

    79  * Closes a selector.

    80  * If any Enumerations were returned by ucnv_select*, they become invalid.

    81  * They can be closed before or after calling ucnv_closeSelector,

    82  * but should never be used after the selector is closed.

    83  *

    84  * @see ucnv_selectForString

    85  * @see ucnv_selectForUTF8

    86  *

    87  * @param sel selector to close

    88  *

    89  * @stable ICU 4.2

    90  */

    91 U_STABLE void U_EXPORT2

    92 ucnvsel_close(UConverterSelector *sel);

    94 #if U_SHOW_CPLUSPLUS_API

    96 U_NAMESPACE_BEGIN

    98 /**

    99  * \class LocalUConverterSelectorPointer

   100  * "Smart pointer" class, closes a UConverterSelector via ucnvsel_close().

   101  * For most methods see the LocalPointerBase base class.

   102  *

   103  * @see LocalPointerBase

   104  * @see LocalPointer

   105  * @stable ICU 4.4

   106  */

   107 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close);

   109 U_NAMESPACE_END

   111 #endif

   113 /**

   114  * Open a selector from its serialized form.

   115  * The buffer must remain valid and unchanged for the lifetime of the selector.

   116  * This is much faster than creating a selector from scratch.

   117  * Using a serialized form from a different machine (endianness/charset) is supported.

   118  *

   119  * @param buffer pointer to the serialized form of a converter selector;

   120  *               must be 32-bit-aligned

   121  * @param length the capacity of this buffer (can be equal to or larger than

   122  *               the actual data length)

   123  * @param status an in/out ICU UErrorCode

   124  * @return the new selector

   125  *

   126  * @stable ICU 4.2

   127  */

   128 U_STABLE UConverterSelector* U_EXPORT2

   129 ucnvsel_openFromSerialized(const void* buffer, int32_t length, UErrorCode* status);

   131 /**

   132  * Serialize a selector into a linear buffer.

   133  * The serialized form is portable to different machines.

   134  *

   135  * @param sel selector to consider

   136  * @param buffer pointer to 32-bit-aligned memory to be filled with the

   137  *               serialized form of this converter selector

   138  * @param bufferCapacity the capacity of this buffer

   139  * @param status an in/out ICU UErrorCode

   140  * @return the required buffer capacity to hold serialize data (even if the call fails

   141  *         with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity)

   142  *

   143  * @stable ICU 4.2

   144  */

   145 U_STABLE int32_t U_EXPORT2

   146 ucnvsel_serialize(const UConverterSelector* sel,

   147                   void* buffer, int32_t bufferCapacity, UErrorCode* status);

   149 /**

   150  * Select converters that can map all characters in a UTF-16 string,

   151  * ignoring the excluded code points.

   152  *

   153  * @param sel a selector

   154  * @param s UTF-16 string

   155  * @param length length of the string, or -1 if NUL-terminated

   156  * @param status an in/out ICU UErrorCode

   157  * @return an enumeration containing encoding names.

   158  *         The returned encoding names and their order will be the same as

   159  *         supplied when building the selector.

   160  *

   161  * @stable ICU 4.2

   162  */

   163 U_STABLE UEnumeration * U_EXPORT2

   164 ucnvsel_selectForString(const UConverterSelector* sel,

   165                         const UChar *s, int32_t length, UErrorCode *status);

   167 /**

   168  * Select converters that can map all characters in a UTF-8 string,

   169  * ignoring the excluded code points.

   170  *

   171  * @param sel a selector

   172  * @param s UTF-8 string

   173  * @param length length of the string, or -1 if NUL-terminated

   174  * @param status an in/out ICU UErrorCode

   175  * @return an enumeration containing encoding names.

   176  *         The returned encoding names and their order will be the same as

   177  *         supplied when building the selector.

   178  *

   179  * @stable ICU 4.2

   180  */

   181 U_STABLE UEnumeration * U_EXPORT2

   182 ucnvsel_selectForUTF8(const UConverterSelector* sel,

   183                       const char *s, int32_t length, UErrorCode *status);

   185 #endif  /* !UCONFIG_NO_CONVERSION */

   187 #endif  /* __ICU_UCNV_SEL_H__ */

The Tor Browser / file revision