Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucnvsel.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 *******************************************************************************
jpayne@69 5 *
jpayne@69 6 * Copyright (C) 2008-2011, International Business Machines
jpayne@69 7 * Corporation, Google and others. All Rights Reserved.
jpayne@69 8 *
jpayne@69 9 *******************************************************************************
jpayne@69 10 */
jpayne@69 11 /*
jpayne@69 12 * Author : eldawy@google.com (Mohamed Eldawy)
jpayne@69 13 * ucnvsel.h
jpayne@69 14 *
jpayne@69 15 * Purpose: To generate a list of encodings capable of handling
jpayne@69 16 * a given Unicode text
jpayne@69 17 *
jpayne@69 18 * Started 09-April-2008
jpayne@69 19 */
jpayne@69 20
jpayne@69 21 #ifndef __ICU_UCNV_SEL_H__
jpayne@69 22 #define __ICU_UCNV_SEL_H__
jpayne@69 23
jpayne@69 24 #include "unicode/utypes.h"
jpayne@69 25
jpayne@69 26 #if !UCONFIG_NO_CONVERSION
jpayne@69 27
jpayne@69 28 #include "unicode/uset.h"
jpayne@69 29 #include "unicode/utf16.h"
jpayne@69 30 #include "unicode/uenum.h"
jpayne@69 31 #include "unicode/ucnv.h"
jpayne@69 32 #include "unicode/localpointer.h"
jpayne@69 33
jpayne@69 34 /**
jpayne@69 35 * \file
jpayne@69 36 *
jpayne@69 37 * A converter selector is built with a set of encoding/charset names
jpayne@69 38 * and given an input string returns the set of names of the
jpayne@69 39 * corresponding converters which can convert the string.
jpayne@69 40 *
jpayne@69 41 * A converter selector can be serialized into a buffer and reopened
jpayne@69 42 * from the serialized form.
jpayne@69 43 */
jpayne@69 44
jpayne@69 45 /**
jpayne@69 46 * @{
jpayne@69 47 * The selector data structure
jpayne@69 48 */
jpayne@69 49 struct UConverterSelector;
jpayne@69 50 typedef struct UConverterSelector UConverterSelector;
jpayne@69 51 /** @} */
jpayne@69 52
jpayne@69 53 /**
jpayne@69 54 * Open a selector.
jpayne@69 55 * If converterListSize is 0, build for all available converters.
jpayne@69 56 * If excludedCodePoints is NULL, don't exclude any code points.
jpayne@69 57 *
jpayne@69 58 * @param converterList a pointer to encoding names needed to be involved.
jpayne@69 59 * Can be NULL if converterListSize==0.
jpayne@69 60 * The list and the names will be cloned, and the caller
jpayne@69 61 * retains ownership of the original.
jpayne@69 62 * @param converterListSize number of encodings in above list.
jpayne@69 63 * If 0, builds a selector for all available converters.
jpayne@69 64 * @param excludedCodePoints a set of code points to be excluded from consideration.
jpayne@69 65 * That is, excluded code points in a string do not change
jpayne@69 66 * the selection result. (They might be handled by a callback.)
jpayne@69 67 * Use NULL to exclude nothing.
jpayne@69 68 * @param whichSet what converter set to use? Use this to determine whether
jpayne@69 69 * to consider only roundtrip mappings or also fallbacks.
jpayne@69 70 * @param status an in/out ICU UErrorCode
jpayne@69 71 * @return the new selector
jpayne@69 72 *
jpayne@69 73 * @stable ICU 4.2
jpayne@69 74 */
jpayne@69 75 U_STABLE UConverterSelector* U_EXPORT2
jpayne@69 76 ucnvsel_open(const char* const* converterList, int32_t converterListSize,
jpayne@69 77 const USet* excludedCodePoints,
jpayne@69 78 const UConverterUnicodeSet whichSet, UErrorCode* status);
jpayne@69 79
jpayne@69 80 /**
jpayne@69 81 * Closes a selector.
jpayne@69 82 * If any Enumerations were returned by ucnv_select*, they become invalid.
jpayne@69 83 * They can be closed before or after calling ucnv_closeSelector,
jpayne@69 84 * but should never be used after the selector is closed.
jpayne@69 85 *
jpayne@69 86 * @see ucnv_selectForString
jpayne@69 87 * @see ucnv_selectForUTF8
jpayne@69 88 *
jpayne@69 89 * @param sel selector to close
jpayne@69 90 *
jpayne@69 91 * @stable ICU 4.2
jpayne@69 92 */
jpayne@69 93 U_STABLE void U_EXPORT2
jpayne@69 94 ucnvsel_close(UConverterSelector *sel);
jpayne@69 95
jpayne@69 96 #if U_SHOW_CPLUSPLUS_API
jpayne@69 97
jpayne@69 98 U_NAMESPACE_BEGIN
jpayne@69 99
jpayne@69 100 /**
jpayne@69 101 * \class LocalUConverterSelectorPointer
jpayne@69 102 * "Smart pointer" class, closes a UConverterSelector via ucnvsel_close().
jpayne@69 103 * For most methods see the LocalPointerBase base class.
jpayne@69 104 *
jpayne@69 105 * @see LocalPointerBase
jpayne@69 106 * @see LocalPointer
jpayne@69 107 * @stable ICU 4.4
jpayne@69 108 */
jpayne@69 109 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close);
jpayne@69 110
jpayne@69 111 U_NAMESPACE_END
jpayne@69 112
jpayne@69 113 #endif
jpayne@69 114
jpayne@69 115 /**
jpayne@69 116 * Open a selector from its serialized form.
jpayne@69 117 * The buffer must remain valid and unchanged for the lifetime of the selector.
jpayne@69 118 * This is much faster than creating a selector from scratch.
jpayne@69 119 * Using a serialized form from a different machine (endianness/charset) is supported.
jpayne@69 120 *
jpayne@69 121 * @param buffer pointer to the serialized form of a converter selector;
jpayne@69 122 * must be 32-bit-aligned
jpayne@69 123 * @param length the capacity of this buffer (can be equal to or larger than
jpayne@69 124 * the actual data length)
jpayne@69 125 * @param status an in/out ICU UErrorCode
jpayne@69 126 * @return the new selector
jpayne@69 127 *
jpayne@69 128 * @stable ICU 4.2
jpayne@69 129 */
jpayne@69 130 U_STABLE UConverterSelector* U_EXPORT2
jpayne@69 131 ucnvsel_openFromSerialized(const void* buffer, int32_t length, UErrorCode* status);
jpayne@69 132
jpayne@69 133 /**
jpayne@69 134 * Serialize a selector into a linear buffer.
jpayne@69 135 * The serialized form is portable to different machines.
jpayne@69 136 *
jpayne@69 137 * @param sel selector to consider
jpayne@69 138 * @param buffer pointer to 32-bit-aligned memory to be filled with the
jpayne@69 139 * serialized form of this converter selector
jpayne@69 140 * @param bufferCapacity the capacity of this buffer
jpayne@69 141 * @param status an in/out ICU UErrorCode
jpayne@69 142 * @return the required buffer capacity to hold serialize data (even if the call fails
jpayne@69 143 * with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity)
jpayne@69 144 *
jpayne@69 145 * @stable ICU 4.2
jpayne@69 146 */
jpayne@69 147 U_STABLE int32_t U_EXPORT2
jpayne@69 148 ucnvsel_serialize(const UConverterSelector* sel,
jpayne@69 149 void* buffer, int32_t bufferCapacity, UErrorCode* status);
jpayne@69 150
jpayne@69 151 /**
jpayne@69 152 * Select converters that can map all characters in a UTF-16 string,
jpayne@69 153 * ignoring the excluded code points.
jpayne@69 154 *
jpayne@69 155 * @param sel a selector
jpayne@69 156 * @param s UTF-16 string
jpayne@69 157 * @param length length of the string, or -1 if NUL-terminated
jpayne@69 158 * @param status an in/out ICU UErrorCode
jpayne@69 159 * @return an enumeration containing encoding names.
jpayne@69 160 * The returned encoding names and their order will be the same as
jpayne@69 161 * supplied when building the selector.
jpayne@69 162 *
jpayne@69 163 * @stable ICU 4.2
jpayne@69 164 */
jpayne@69 165 U_STABLE UEnumeration * U_EXPORT2
jpayne@69 166 ucnvsel_selectForString(const UConverterSelector* sel,
jpayne@69 167 const UChar *s, int32_t length, UErrorCode *status);
jpayne@69 168
jpayne@69 169 /**
jpayne@69 170 * Select converters that can map all characters in a UTF-8 string,
jpayne@69 171 * ignoring the excluded code points.
jpayne@69 172 *
jpayne@69 173 * @param sel a selector
jpayne@69 174 * @param s UTF-8 string
jpayne@69 175 * @param length length of the string, or -1 if NUL-terminated
jpayne@69 176 * @param status an in/out ICU UErrorCode
jpayne@69 177 * @return an enumeration containing encoding names.
jpayne@69 178 * The returned encoding names and their order will be the same as
jpayne@69 179 * supplied when building the selector.
jpayne@69 180 *
jpayne@69 181 * @stable ICU 4.2
jpayne@69 182 */
jpayne@69 183 U_STABLE UEnumeration * U_EXPORT2
jpayne@69 184 ucnvsel_selectForUTF8(const UConverterSelector* sel,
jpayne@69 185 const char *s, int32_t length, UErrorCode *status);
jpayne@69 186
jpayne@69 187 #endif /* !UCONFIG_NO_CONVERSION */
jpayne@69 188
jpayne@69 189 #endif /* __ICU_UCNV_SEL_H__ */