Mercurial > repos > rliterman > csp2

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