Branch data Line data Source code
1 : : #ifndef Py_CPYTHON_UNICODEOBJECT_H
2 : : # error "this header file must not be included directly"
3 : : #endif
4 : :
5 : : /* Py_UNICODE was the native Unicode storage format (code unit) used by
6 : : Python and represents a single Unicode element in the Unicode type.
7 : : With PEP 393, Py_UNICODE is deprecated and replaced with a
8 : : typedef to wchar_t. */
9 : : #define PY_UNICODE_TYPE wchar_t
10 : : /* Py_DEPRECATED(3.3) */ typedef wchar_t Py_UNICODE;
11 : :
12 : : /* --- Internal Unicode Operations ---------------------------------------- */
13 : :
14 : : // Static inline functions to work with surrogates
15 : 112814 : static inline int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch) {
16 [ + + + + ]: 112814 : return (0xD800 <= ch && ch <= 0xDFFF);
17 : : }
18 : 0 : static inline int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch) {
19 [ # # # # ]: 0 : return (0xD800 <= ch && ch <= 0xDBFF);
20 : : }
21 : 0 : static inline int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch) {
22 [ # # # # ]: 0 : return (0xDC00 <= ch && ch <= 0xDFFF);
23 : : }
24 : :
25 : : // Join two surrogate characters and return a single Py_UCS4 value.
26 : 0 : static inline Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low) {
27 : : assert(Py_UNICODE_IS_HIGH_SURROGATE(high));
28 : : assert(Py_UNICODE_IS_LOW_SURROGATE(low));
29 : 0 : return 0x10000 + (((high & 0x03FF) << 10) | (low & 0x03FF));
30 : : }
31 : :
32 : : // High surrogate = top 10 bits added to 0xD800.
33 : : // The character must be in the range [U+10000; U+10ffff].
34 : 0 : static inline Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch) {
35 : : assert(0x10000 <= ch && ch <= 0x10ffff);
36 : 0 : return (0xD800 - (0x10000 >> 10) + (ch >> 10));
37 : : }
38 : :
39 : : // Low surrogate = bottom 10 bits added to 0xDC00.
40 : : // The character must be in the range [U+10000; U+10ffff].
41 : 0 : static inline Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch) {
42 : : assert(0x10000 <= ch && ch <= 0x10ffff);
43 : 0 : return (0xDC00 + (ch & 0x3FF));
44 : : }
45 : :
46 : : /* --- Unicode Type ------------------------------------------------------- */
47 : :
48 : : /* ASCII-only strings created through PyUnicode_New use the PyASCIIObject
49 : : structure. state.ascii and state.compact are set, and the data
50 : : immediately follow the structure. utf8_length can be found
51 : : in the length field; the utf8 pointer is equal to the data pointer. */
52 : : typedef struct {
53 : : /* There are 4 forms of Unicode strings:
54 : :
55 : : - compact ascii:
56 : :
57 : : * structure = PyASCIIObject
58 : : * test: PyUnicode_IS_COMPACT_ASCII(op)
59 : : * kind = PyUnicode_1BYTE_KIND
60 : : * compact = 1
61 : : * ascii = 1
62 : : * (length is the length of the utf8)
63 : : * (data starts just after the structure)
64 : : * (since ASCII is decoded from UTF-8, the utf8 string are the data)
65 : :
66 : : - compact:
67 : :
68 : : * structure = PyCompactUnicodeObject
69 : : * test: PyUnicode_IS_COMPACT(op) && !PyUnicode_IS_ASCII(op)
70 : : * kind = PyUnicode_1BYTE_KIND, PyUnicode_2BYTE_KIND or
71 : : PyUnicode_4BYTE_KIND
72 : : * compact = 1
73 : : * ascii = 0
74 : : * utf8 is not shared with data
75 : : * utf8_length = 0 if utf8 is NULL
76 : : * (data starts just after the structure)
77 : :
78 : : - legacy string:
79 : :
80 : : * structure = PyUnicodeObject structure
81 : : * test: !PyUnicode_IS_COMPACT(op)
82 : : * kind = PyUnicode_1BYTE_KIND, PyUnicode_2BYTE_KIND or
83 : : PyUnicode_4BYTE_KIND
84 : : * compact = 0
85 : : * data.any is not NULL
86 : : * utf8 is shared and utf8_length = length with data.any if ascii = 1
87 : : * utf8_length = 0 if utf8 is NULL
88 : :
89 : : Compact strings use only one memory block (structure + characters),
90 : : whereas legacy strings use one block for the structure and one block
91 : : for characters.
92 : :
93 : : Legacy strings are created by subclasses of Unicode.
94 : :
95 : : See also _PyUnicode_CheckConsistency().
96 : : */
97 : : PyObject_HEAD
98 : : Py_ssize_t length; /* Number of code points in the string */
99 : : Py_hash_t hash; /* Hash value; -1 if not set */
100 : : struct {
101 : : /* If interned is set, the two references from the
102 : : dictionary to this object are *not* counted in ob_refcnt. */
103 : : unsigned int interned:1;
104 : : /* Character size:
105 : :
106 : : - PyUnicode_1BYTE_KIND (1):
107 : :
108 : : * character type = Py_UCS1 (8 bits, unsigned)
109 : : * all characters are in the range U+0000-U+00FF (latin1)
110 : : * if ascii is set, all characters are in the range U+0000-U+007F
111 : : (ASCII), otherwise at least one character is in the range
112 : : U+0080-U+00FF
113 : :
114 : : - PyUnicode_2BYTE_KIND (2):
115 : :
116 : : * character type = Py_UCS2 (16 bits, unsigned)
117 : : * all characters are in the range U+0000-U+FFFF (BMP)
118 : : * at least one character is in the range U+0100-U+FFFF
119 : :
120 : : - PyUnicode_4BYTE_KIND (4):
121 : :
122 : : * character type = Py_UCS4 (32 bits, unsigned)
123 : : * all characters are in the range U+0000-U+10FFFF
124 : : * at least one character is in the range U+10000-U+10FFFF
125 : : */
126 : : unsigned int kind:3;
127 : : /* Compact is with respect to the allocation scheme. Compact unicode
128 : : objects only require one memory block while non-compact objects use
129 : : one block for the PyUnicodeObject struct and another for its data
130 : : buffer. */
131 : : unsigned int compact:1;
132 : : /* The string only contains characters in the range U+0000-U+007F (ASCII)
133 : : and the kind is PyUnicode_1BYTE_KIND. If ascii is set and compact is
134 : : set, use the PyASCIIObject structure. */
135 : : unsigned int ascii:1;
136 : : /* Padding to ensure that PyUnicode_DATA() is always aligned to
137 : : 4 bytes (see issue #19537 on m68k). */
138 : : unsigned int :26;
139 : : } state;
140 : : } PyASCIIObject;
141 : :
142 : : /* Non-ASCII strings allocated through PyUnicode_New use the
143 : : PyCompactUnicodeObject structure. state.compact is set, and the data
144 : : immediately follow the structure. */
145 : : typedef struct {
146 : : PyASCIIObject _base;
147 : : Py_ssize_t utf8_length; /* Number of bytes in utf8, excluding the
148 : : * terminating \0. */
149 : : char *utf8; /* UTF-8 representation (null-terminated) */
150 : : } PyCompactUnicodeObject;
151 : :
152 : : /* Object format for Unicode subclasses. */
153 : : typedef struct {
154 : : PyCompactUnicodeObject _base;
155 : : union {
156 : : void *any;
157 : : Py_UCS1 *latin1;
158 : : Py_UCS2 *ucs2;
159 : : Py_UCS4 *ucs4;
160 : : } data; /* Canonical, smallest-form Unicode buffer */
161 : : } PyUnicodeObject;
162 : :
163 : : PyAPI_FUNC(int) _PyUnicode_CheckConsistency(
164 : : PyObject *op,
165 : : int check_content);
166 : :
167 : :
168 : : #define _PyASCIIObject_CAST(op) \
169 : : (assert(PyUnicode_Check(op)), \
170 : : _Py_CAST(PyASCIIObject*, (op)))
171 : : #define _PyCompactUnicodeObject_CAST(op) \
172 : : (assert(PyUnicode_Check(op)), \
173 : : _Py_CAST(PyCompactUnicodeObject*, (op)))
174 : : #define _PyUnicodeObject_CAST(op) \
175 : : (assert(PyUnicode_Check(op)), \
176 : : _Py_CAST(PyUnicodeObject*, (op)))
177 : :
178 : :
179 : : /* --- Flexible String Representation Helper Macros (PEP 393) -------------- */
180 : :
181 : : /* Values for PyASCIIObject.state: */
182 : :
183 : : /* Interning state. */
184 : : #define SSTATE_NOT_INTERNED 0
185 : : #define SSTATE_INTERNED_MORTAL 1
186 : :
187 : : /* Use only if you know it's a string */
188 : 8986981 : static inline unsigned int PyUnicode_CHECK_INTERNED(PyObject *op) {
189 : 8986981 : return _PyASCIIObject_CAST(op)->state.interned;
190 : : }
191 : : #define PyUnicode_CHECK_INTERNED(op) PyUnicode_CHECK_INTERNED(_PyObject_CAST(op))
192 : :
193 : : /* For backward compatibility */
194 : 1500720 : static inline unsigned int PyUnicode_IS_READY(PyObject* Py_UNUSED(op)) {
195 : 1500720 : return 1;
196 : : }
197 : : #define PyUnicode_IS_READY(op) PyUnicode_IS_READY(_PyObject_CAST(op))
198 : :
199 : : /* Return true if the string contains only ASCII characters, or 0 if not. The
200 : : string may be compact (PyUnicode_IS_COMPACT_ASCII) or not, but must be
201 : : ready. */
202 : 25019819 : static inline unsigned int PyUnicode_IS_ASCII(PyObject *op) {
203 [ # # ]: 25019819 : return _PyASCIIObject_CAST(op)->state.ascii;
204 : : }
205 : : #define PyUnicode_IS_ASCII(op) PyUnicode_IS_ASCII(_PyObject_CAST(op))
206 : :
207 : : /* Return true if the string is compact or 0 if not.
208 : : No type checks or Ready calls are performed. */
209 : 29563860 : static inline unsigned int PyUnicode_IS_COMPACT(PyObject *op) {
210 [ # # ]: 29563860 : return _PyASCIIObject_CAST(op)->state.compact;
211 : : }
212 : : #define PyUnicode_IS_COMPACT(op) PyUnicode_IS_COMPACT(_PyObject_CAST(op))
213 : :
214 : : /* Return true if the string is a compact ASCII string (use PyASCIIObject
215 : : structure), or 0 if not. No type checks or Ready calls are performed. */
216 : 4800553 : static inline int PyUnicode_IS_COMPACT_ASCII(PyObject *op) {
217 [ + + + + ]: 4800553 : return (_PyASCIIObject_CAST(op)->state.ascii && PyUnicode_IS_COMPACT(op));
218 : : }
219 : : #define PyUnicode_IS_COMPACT_ASCII(op) PyUnicode_IS_COMPACT_ASCII(_PyObject_CAST(op))
220 : :
221 : : enum PyUnicode_Kind {
222 : : /* Return values of the PyUnicode_KIND() function: */
223 : : PyUnicode_1BYTE_KIND = 1,
224 : : PyUnicode_2BYTE_KIND = 2,
225 : : PyUnicode_4BYTE_KIND = 4
226 : : };
227 : :
228 : : // PyUnicode_KIND(): Return one of the PyUnicode_*_KIND values defined above.
229 : : //
230 : : // gh-89653: Converting this macro to a static inline function would introduce
231 : : // new compiler warnings on "kind < PyUnicode_KIND(str)" (compare signed and
232 : : // unsigned numbers) where kind type is an int or on
233 : : // "unsigned int kind = PyUnicode_KIND(str)" (cast signed to unsigned).
234 : : #define PyUnicode_KIND(op) _Py_RVALUE(_PyASCIIObject_CAST(op)->state.kind)
235 : :
236 : : /* Return a void pointer to the raw unicode buffer. */
237 : 20178995 : static inline void* _PyUnicode_COMPACT_DATA(PyObject *op) {
238 [ + + ]: 20178995 : if (PyUnicode_IS_ASCII(op)) {
239 [ # # ]: 20153698 : return _Py_STATIC_CAST(void*, (_PyASCIIObject_CAST(op) + 1));
240 : : }
241 [ # # ]: 25297 : return _Py_STATIC_CAST(void*, (_PyCompactUnicodeObject_CAST(op) + 1));
242 : : }
243 : :
244 : 28 : static inline void* _PyUnicode_NONCOMPACT_DATA(PyObject *op) {
245 : : void *data;
246 [ # # ]: 0 : assert(!PyUnicode_IS_COMPACT(op));
247 [ # # ]: 28 : data = _PyUnicodeObject_CAST(op)->data.any;
248 [ # # ]: 0 : assert(data != NULL);
249 : 28 : return data;
250 : : }
251 : :
252 : 20179023 : static inline void* PyUnicode_DATA(PyObject *op) {
253 [ + + ]: 20179023 : if (PyUnicode_IS_COMPACT(op)) {
254 : 20178995 : return _PyUnicode_COMPACT_DATA(op);
255 : : }
256 : 28 : return _PyUnicode_NONCOMPACT_DATA(op);
257 : : }
258 : : #define PyUnicode_DATA(op) PyUnicode_DATA(_PyObject_CAST(op))
259 : :
260 : : /* Return pointers to the canonical representation cast to unsigned char,
261 : : Py_UCS2, or Py_UCS4 for direct character access.
262 : : No checks are performed, use PyUnicode_KIND() before to ensure
263 : : these will work correctly. */
264 : :
265 : : #define PyUnicode_1BYTE_DATA(op) _Py_STATIC_CAST(Py_UCS1*, PyUnicode_DATA(op))
266 : : #define PyUnicode_2BYTE_DATA(op) _Py_STATIC_CAST(Py_UCS2*, PyUnicode_DATA(op))
267 : : #define PyUnicode_4BYTE_DATA(op) _Py_STATIC_CAST(Py_UCS4*, PyUnicode_DATA(op))
268 : :
269 : : /* Returns the length of the unicode string. */
270 : 27393330 : static inline Py_ssize_t PyUnicode_GET_LENGTH(PyObject *op) {
271 [ # # ]: 27393330 : return _PyASCIIObject_CAST(op)->length;
272 : : }
273 : : #define PyUnicode_GET_LENGTH(op) PyUnicode_GET_LENGTH(_PyObject_CAST(op))
274 : :
275 : : /* Write into the canonical representation, this function does not do any sanity
276 : : checks and is intended for usage in loops. The caller should cache the
277 : : kind and data pointers obtained from other function calls.
278 : : index is the index in the string (starts at 0) and value is the new
279 : : code point value which should be written to that location. */
280 : 764080 : static inline void PyUnicode_WRITE(int kind, void *data,
281 : : Py_ssize_t index, Py_UCS4 value)
282 : : {
283 : : assert(index >= 0);
284 [ + + ]: 764080 : if (kind == PyUnicode_1BYTE_KIND) {
285 : : assert(value <= 0xffU);
286 : 755833 : _Py_STATIC_CAST(Py_UCS1*, data)[index] = _Py_STATIC_CAST(Py_UCS1, value);
287 : : }
288 [ + + ]: 8247 : else if (kind == PyUnicode_2BYTE_KIND) {
289 : : assert(value <= 0xffffU);
290 : 8202 : _Py_STATIC_CAST(Py_UCS2*, data)[index] = _Py_STATIC_CAST(Py_UCS2, value);
291 : : }
292 : : else {
293 : : assert(kind == PyUnicode_4BYTE_KIND);
294 : : assert(value <= 0x10ffffU);
295 : 45 : _Py_STATIC_CAST(Py_UCS4*, data)[index] = value;
296 : : }
297 : 764080 : }
298 : : #define PyUnicode_WRITE(kind, data, index, value) \
299 : : PyUnicode_WRITE(_Py_STATIC_CAST(int, kind), _Py_CAST(void*, data), \
300 : : (index), _Py_STATIC_CAST(Py_UCS4, value))
301 : :
302 : : /* Read a code point from the string's canonical representation. No checks
303 : : or ready calls are performed. */
304 : 5933633 : static inline Py_UCS4 PyUnicode_READ(int kind,
305 : : const void *data, Py_ssize_t index)
306 : : {
307 : : assert(index >= 0);
308 [ + + ]: 5933633 : if (kind == PyUnicode_1BYTE_KIND) {
309 : 5844162 : return _Py_STATIC_CAST(const Py_UCS1*, data)[index];
310 : : }
311 [ + + ]: 89471 : if (kind == PyUnicode_2BYTE_KIND) {
312 : 89464 : return _Py_STATIC_CAST(const Py_UCS2*, data)[index];
313 : : }
314 : : assert(kind == PyUnicode_4BYTE_KIND);
315 : 7 : return _Py_STATIC_CAST(const Py_UCS4*, data)[index];
316 : : }
317 : : #define PyUnicode_READ(kind, data, index) \
318 : : PyUnicode_READ(_Py_STATIC_CAST(int, kind), \
319 : : _Py_STATIC_CAST(const void*, data), \
320 : : (index))
321 : :
322 : : /* PyUnicode_READ_CHAR() is less efficient than PyUnicode_READ() because it
323 : : calls PyUnicode_KIND() and might call it twice. For single reads, use
324 : : PyUnicode_READ_CHAR, for multiple consecutive reads callers should
325 : : cache kind and use PyUnicode_READ instead. */
326 : 564768 : static inline Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)
327 : : {
328 : : int kind;
329 : :
330 [ # # ]: 0 : assert(index >= 0);
331 : : // Tolerate reading the NUL character at str[len(str)]
332 [ # # ]: 0 : assert(index <= PyUnicode_GET_LENGTH(unicode));
333 : :
334 [ # # ]: 564768 : kind = PyUnicode_KIND(unicode);
335 [ + + ]: 564768 : if (kind == PyUnicode_1BYTE_KIND) {
336 : 564680 : return PyUnicode_1BYTE_DATA(unicode)[index];
337 : : }
338 [ + + ]: 88 : if (kind == PyUnicode_2BYTE_KIND) {
339 : 87 : return PyUnicode_2BYTE_DATA(unicode)[index];
340 : : }
341 [ # # ]: 0 : assert(kind == PyUnicode_4BYTE_KIND);
342 : 1 : return PyUnicode_4BYTE_DATA(unicode)[index];
343 : : }
344 : : #define PyUnicode_READ_CHAR(unicode, index) \
345 : : PyUnicode_READ_CHAR(_PyObject_CAST(unicode), (index))
346 : :
347 : : /* Return a maximum character value which is suitable for creating another
348 : : string based on op. This is always an approximation but more efficient
349 : : than iterating over the string. */
350 : 2534381 : static inline Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *op)
351 : : {
352 : : int kind;
353 : :
354 [ + + ]: 2534381 : if (PyUnicode_IS_ASCII(op)) {
355 : 2534039 : return 0x7fU;
356 : : }
357 : :
358 [ # # ]: 342 : kind = PyUnicode_KIND(op);
359 [ + + ]: 342 : if (kind == PyUnicode_1BYTE_KIND) {
360 : 134 : return 0xffU;
361 : : }
362 [ + + ]: 208 : if (kind == PyUnicode_2BYTE_KIND) {
363 : 167 : return 0xffffU;
364 : : }
365 [ # # ]: 0 : assert(kind == PyUnicode_4BYTE_KIND);
366 : 41 : return 0x10ffffU;
367 : : }
368 : : #define PyUnicode_MAX_CHAR_VALUE(op) \
369 : : PyUnicode_MAX_CHAR_VALUE(_PyObject_CAST(op))
370 : :
371 : : /* === Public API ========================================================= */
372 : :
373 : : /* --- Plain Py_UNICODE --------------------------------------------------- */
374 : :
375 : : /* With PEP 393, this is the recommended way to allocate a new unicode object.
376 : : This function will allocate the object and its buffer in a single memory
377 : : block. Objects created using this function are not resizable. */
378 : : PyAPI_FUNC(PyObject*) PyUnicode_New(
379 : : Py_ssize_t size, /* Number of code points in the new string */
380 : : Py_UCS4 maxchar /* maximum code point value in the string */
381 : : );
382 : :
383 : : /* For backward compatibility */
384 : 4432370 : static inline int PyUnicode_READY(PyObject* Py_UNUSED(op))
385 : : {
386 : 4432370 : return 0;
387 : : }
388 : : #define PyUnicode_READY(op) PyUnicode_READY(_PyObject_CAST(op))
389 : :
390 : : /* Get a copy of a Unicode string. */
391 : : PyAPI_FUNC(PyObject*) _PyUnicode_Copy(
392 : : PyObject *unicode
393 : : );
394 : :
395 : : /* Copy character from one unicode object into another, this function performs
396 : : character conversion when necessary and falls back to memcpy() if possible.
397 : :
398 : : Fail if to is too small (smaller than *how_many* or smaller than
399 : : len(from)-from_start), or if kind(from[from_start:from_start+how_many]) >
400 : : kind(to), or if *to* has more than 1 reference.
401 : :
402 : : Return the number of written character, or return -1 and raise an exception
403 : : on error.
404 : :
405 : : Pseudo-code:
406 : :
407 : : how_many = min(how_many, len(from) - from_start)
408 : : to[to_start:to_start+how_many] = from[from_start:from_start+how_many]
409 : : return how_many
410 : :
411 : : Note: The function doesn't write a terminating null character.
412 : : */
413 : : PyAPI_FUNC(Py_ssize_t) PyUnicode_CopyCharacters(
414 : : PyObject *to,
415 : : Py_ssize_t to_start,
416 : : PyObject *from,
417 : : Py_ssize_t from_start,
418 : : Py_ssize_t how_many
419 : : );
420 : :
421 : : /* Unsafe version of PyUnicode_CopyCharacters(): don't check arguments and so
422 : : may crash if parameters are invalid (e.g. if the output string
423 : : is too short). */
424 : : PyAPI_FUNC(void) _PyUnicode_FastCopyCharacters(
425 : : PyObject *to,
426 : : Py_ssize_t to_start,
427 : : PyObject *from,
428 : : Py_ssize_t from_start,
429 : : Py_ssize_t how_many
430 : : );
431 : :
432 : : /* Fill a string with a character: write fill_char into
433 : : unicode[start:start+length].
434 : :
435 : : Fail if fill_char is bigger than the string maximum character, or if the
436 : : string has more than 1 reference.
437 : :
438 : : Return the number of written character, or return -1 and raise an exception
439 : : on error. */
440 : : PyAPI_FUNC(Py_ssize_t) PyUnicode_Fill(
441 : : PyObject *unicode,
442 : : Py_ssize_t start,
443 : : Py_ssize_t length,
444 : : Py_UCS4 fill_char
445 : : );
446 : :
447 : : /* Unsafe version of PyUnicode_Fill(): don't check arguments and so may crash
448 : : if parameters are invalid (e.g. if length is longer than the string). */
449 : : PyAPI_FUNC(void) _PyUnicode_FastFill(
450 : : PyObject *unicode,
451 : : Py_ssize_t start,
452 : : Py_ssize_t length,
453 : : Py_UCS4 fill_char
454 : : );
455 : :
456 : : /* Create a new string from a buffer of Py_UCS1, Py_UCS2 or Py_UCS4 characters.
457 : : Scan the string to find the maximum character. */
458 : : PyAPI_FUNC(PyObject*) PyUnicode_FromKindAndData(
459 : : int kind,
460 : : const void *buffer,
461 : : Py_ssize_t size);
462 : :
463 : : /* Create a new string from a buffer of ASCII characters.
464 : : WARNING: Don't check if the string contains any non-ASCII character. */
465 : : PyAPI_FUNC(PyObject*) _PyUnicode_FromASCII(
466 : : const char *buffer,
467 : : Py_ssize_t size);
468 : :
469 : : /* Compute the maximum character of the substring unicode[start:end].
470 : : Return 127 for an empty string. */
471 : : PyAPI_FUNC(Py_UCS4) _PyUnicode_FindMaxChar (
472 : : PyObject *unicode,
473 : : Py_ssize_t start,
474 : : Py_ssize_t end);
475 : :
476 : : /* --- _PyUnicodeWriter API ----------------------------------------------- */
477 : :
478 : : typedef struct {
479 : : PyObject *buffer;
480 : : void *data;
481 : : int kind;
482 : : Py_UCS4 maxchar;
483 : : Py_ssize_t size;
484 : : Py_ssize_t pos;
485 : :
486 : : /* minimum number of allocated characters (default: 0) */
487 : : Py_ssize_t min_length;
488 : :
489 : : /* minimum character (default: 127, ASCII) */
490 : : Py_UCS4 min_char;
491 : :
492 : : /* If non-zero, overallocate the buffer (default: 0). */
493 : : unsigned char overallocate;
494 : :
495 : : /* If readonly is 1, buffer is a shared string (cannot be modified)
496 : : and size is set to 0. */
497 : : unsigned char readonly;
498 : : } _PyUnicodeWriter ;
499 : :
500 : : /* Initialize a Unicode writer.
501 : : *
502 : : * By default, the minimum buffer size is 0 character and overallocation is
503 : : * disabled. Set min_length, min_char and overallocate attributes to control
504 : : * the allocation of the buffer. */
505 : : PyAPI_FUNC(void)
506 : : _PyUnicodeWriter_Init(_PyUnicodeWriter *writer);
507 : :
508 : : /* Prepare the buffer to write 'length' characters
509 : : with the specified maximum character.
510 : :
511 : : Return 0 on success, raise an exception and return -1 on error. */
512 : : #define _PyUnicodeWriter_Prepare(WRITER, LENGTH, MAXCHAR) \
513 : : (((MAXCHAR) <= (WRITER)->maxchar \
514 : : && (LENGTH) <= (WRITER)->size - (WRITER)->pos) \
515 : : ? 0 \
516 : : : (((LENGTH) == 0) \
517 : : ? 0 \
518 : : : _PyUnicodeWriter_PrepareInternal((WRITER), (LENGTH), (MAXCHAR))))
519 : :
520 : : /* Don't call this function directly, use the _PyUnicodeWriter_Prepare() macro
521 : : instead. */
522 : : PyAPI_FUNC(int)
523 : : _PyUnicodeWriter_PrepareInternal(_PyUnicodeWriter *writer,
524 : : Py_ssize_t length, Py_UCS4 maxchar);
525 : :
526 : : /* Prepare the buffer to have at least the kind KIND.
527 : : For example, kind=PyUnicode_2BYTE_KIND ensures that the writer will
528 : : support characters in range U+000-U+FFFF.
529 : :
530 : : Return 0 on success, raise an exception and return -1 on error. */
531 : : #define _PyUnicodeWriter_PrepareKind(WRITER, KIND) \
532 : : ((KIND) <= (WRITER)->kind \
533 : : ? 0 \
534 : : : _PyUnicodeWriter_PrepareKindInternal((WRITER), (KIND)))
535 : :
536 : : /* Don't call this function directly, use the _PyUnicodeWriter_PrepareKind()
537 : : macro instead. */
538 : : PyAPI_FUNC(int)
539 : : _PyUnicodeWriter_PrepareKindInternal(_PyUnicodeWriter *writer,
540 : : int kind);
541 : :
542 : : /* Append a Unicode character.
543 : : Return 0 on success, raise an exception and return -1 on error. */
544 : : PyAPI_FUNC(int)
545 : : _PyUnicodeWriter_WriteChar(_PyUnicodeWriter *writer,
546 : : Py_UCS4 ch
547 : : );
548 : :
549 : : /* Append a Unicode string.
550 : : Return 0 on success, raise an exception and return -1 on error. */
551 : : PyAPI_FUNC(int)
552 : : _PyUnicodeWriter_WriteStr(_PyUnicodeWriter *writer,
553 : : PyObject *str /* Unicode string */
554 : : );
555 : :
556 : : /* Append a substring of a Unicode string.
557 : : Return 0 on success, raise an exception and return -1 on error. */
558 : : PyAPI_FUNC(int)
559 : : _PyUnicodeWriter_WriteSubstring(_PyUnicodeWriter *writer,
560 : : PyObject *str, /* Unicode string */
561 : : Py_ssize_t start,
562 : : Py_ssize_t end
563 : : );
564 : :
565 : : /* Append an ASCII-encoded byte string.
566 : : Return 0 on success, raise an exception and return -1 on error. */
567 : : PyAPI_FUNC(int)
568 : : _PyUnicodeWriter_WriteASCIIString(_PyUnicodeWriter *writer,
569 : : const char *str, /* ASCII-encoded byte string */
570 : : Py_ssize_t len /* number of bytes, or -1 if unknown */
571 : : );
572 : :
573 : : /* Append a latin1-encoded byte string.
574 : : Return 0 on success, raise an exception and return -1 on error. */
575 : : PyAPI_FUNC(int)
576 : : _PyUnicodeWriter_WriteLatin1String(_PyUnicodeWriter *writer,
577 : : const char *str, /* latin1-encoded byte string */
578 : : Py_ssize_t len /* length in bytes */
579 : : );
580 : :
581 : : /* Get the value of the writer as a Unicode string. Clear the
582 : : buffer of the writer. Raise an exception and return NULL
583 : : on error. */
584 : : PyAPI_FUNC(PyObject *)
585 : : _PyUnicodeWriter_Finish(_PyUnicodeWriter *writer);
586 : :
587 : : /* Deallocate memory of a writer (clear its internal buffer). */
588 : : PyAPI_FUNC(void)
589 : : _PyUnicodeWriter_Dealloc(_PyUnicodeWriter *writer);
590 : :
591 : :
592 : : /* Format the object based on the format_spec, as defined in PEP 3101
593 : : (Advanced String Formatting). */
594 : : PyAPI_FUNC(int) _PyUnicode_FormatAdvancedWriter(
595 : : _PyUnicodeWriter *writer,
596 : : PyObject *obj,
597 : : PyObject *format_spec,
598 : : Py_ssize_t start,
599 : : Py_ssize_t end);
600 : :
601 : : /* --- Manage the default encoding ---------------------------------------- */
602 : :
603 : : /* Returns a pointer to the default encoding (UTF-8) of the
604 : : Unicode object unicode.
605 : :
606 : : Like PyUnicode_AsUTF8AndSize(), this also caches the UTF-8 representation
607 : : in the unicodeobject.
608 : :
609 : : _PyUnicode_AsString is a #define for PyUnicode_AsUTF8 to
610 : : support the previous internal function with the same behaviour.
611 : :
612 : : Use of this API is DEPRECATED since no size information can be
613 : : extracted from the returned data.
614 : : */
615 : :
616 : : PyAPI_FUNC(const char *) PyUnicode_AsUTF8(PyObject *unicode);
617 : :
618 : : #define _PyUnicode_AsString PyUnicode_AsUTF8
619 : :
620 : : /* --- UTF-7 Codecs ------------------------------------------------------- */
621 : :
622 : : PyAPI_FUNC(PyObject*) _PyUnicode_EncodeUTF7(
623 : : PyObject *unicode, /* Unicode object */
624 : : int base64SetO, /* Encode RFC2152 Set O characters in base64 */
625 : : int base64WhiteSpace, /* Encode whitespace (sp, ht, nl, cr) in base64 */
626 : : const char *errors /* error handling */
627 : : );
628 : :
629 : : /* --- UTF-8 Codecs ------------------------------------------------------- */
630 : :
631 : : PyAPI_FUNC(PyObject*) _PyUnicode_AsUTF8String(
632 : : PyObject *unicode,
633 : : const char *errors);
634 : :
635 : : /* --- UTF-32 Codecs ------------------------------------------------------ */
636 : :
637 : : PyAPI_FUNC(PyObject*) _PyUnicode_EncodeUTF32(
638 : : PyObject *object, /* Unicode object */
639 : : const char *errors, /* error handling */
640 : : int byteorder /* byteorder to use 0=BOM+native;-1=LE,1=BE */
641 : : );
642 : :
643 : : /* --- UTF-16 Codecs ------------------------------------------------------ */
644 : :
645 : : /* Returns a Python string object holding the UTF-16 encoded value of
646 : : the Unicode data.
647 : :
648 : : If byteorder is not 0, output is written according to the following
649 : : byte order:
650 : :
651 : : byteorder == -1: little endian
652 : : byteorder == 0: native byte order (writes a BOM mark)
653 : : byteorder == 1: big endian
654 : :
655 : : If byteorder is 0, the output string will always start with the
656 : : Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
657 : : prepended.
658 : : */
659 : : PyAPI_FUNC(PyObject*) _PyUnicode_EncodeUTF16(
660 : : PyObject* unicode, /* Unicode object */
661 : : const char *errors, /* error handling */
662 : : int byteorder /* byteorder to use 0=BOM+native;-1=LE,1=BE */
663 : : );
664 : :
665 : : /* --- Unicode-Escape Codecs ---------------------------------------------- */
666 : :
667 : : /* Variant of PyUnicode_DecodeUnicodeEscape that supports partial decoding. */
668 : : PyAPI_FUNC(PyObject*) _PyUnicode_DecodeUnicodeEscapeStateful(
669 : : const char *string, /* Unicode-Escape encoded string */
670 : : Py_ssize_t length, /* size of string */
671 : : const char *errors, /* error handling */
672 : : Py_ssize_t *consumed /* bytes consumed */
673 : : );
674 : : /* Helper for PyUnicode_DecodeUnicodeEscape that detects invalid escape
675 : : chars. */
676 : : PyAPI_FUNC(PyObject*) _PyUnicode_DecodeUnicodeEscapeInternal(
677 : : const char *string, /* Unicode-Escape encoded string */
678 : : Py_ssize_t length, /* size of string */
679 : : const char *errors, /* error handling */
680 : : Py_ssize_t *consumed, /* bytes consumed */
681 : : const char **first_invalid_escape /* on return, points to first
682 : : invalid escaped char in
683 : : string. */
684 : : );
685 : :
686 : : /* --- Raw-Unicode-Escape Codecs ---------------------------------------------- */
687 : :
688 : : /* Variant of PyUnicode_DecodeRawUnicodeEscape that supports partial decoding. */
689 : : PyAPI_FUNC(PyObject*) _PyUnicode_DecodeRawUnicodeEscapeStateful(
690 : : const char *string, /* Unicode-Escape encoded string */
691 : : Py_ssize_t length, /* size of string */
692 : : const char *errors, /* error handling */
693 : : Py_ssize_t *consumed /* bytes consumed */
694 : : );
695 : :
696 : : /* --- Latin-1 Codecs ----------------------------------------------------- */
697 : :
698 : : PyAPI_FUNC(PyObject*) _PyUnicode_AsLatin1String(
699 : : PyObject* unicode,
700 : : const char* errors);
701 : :
702 : : /* --- ASCII Codecs ------------------------------------------------------- */
703 : :
704 : : PyAPI_FUNC(PyObject*) _PyUnicode_AsASCIIString(
705 : : PyObject* unicode,
706 : : const char* errors);
707 : :
708 : : /* --- Character Map Codecs ----------------------------------------------- */
709 : :
710 : : /* Translate an Unicode object by applying a character mapping table to
711 : : it and return the resulting Unicode object.
712 : :
713 : : The mapping table must map Unicode ordinal integers to Unicode strings,
714 : : Unicode ordinal integers or None (causing deletion of the character).
715 : :
716 : : Mapping tables may be dictionaries or sequences. Unmapped character
717 : : ordinals (ones which cause a LookupError) are left untouched and
718 : : are copied as-is.
719 : : */
720 : : PyAPI_FUNC(PyObject*) _PyUnicode_EncodeCharmap(
721 : : PyObject *unicode, /* Unicode object */
722 : : PyObject *mapping, /* encoding mapping */
723 : : const char *errors /* error handling */
724 : : );
725 : :
726 : : /* --- Decimal Encoder ---------------------------------------------------- */
727 : :
728 : : /* Coverts a Unicode object holding a decimal value to an ASCII string
729 : : for using in int, float and complex parsers.
730 : : Transforms code points that have decimal digit property to the
731 : : corresponding ASCII digit code points. Transforms spaces to ASCII.
732 : : Transforms code points starting from the first non-ASCII code point that
733 : : is neither a decimal digit nor a space to the end into '?'. */
734 : :
735 : : PyAPI_FUNC(PyObject*) _PyUnicode_TransformDecimalAndSpaceToASCII(
736 : : PyObject *unicode /* Unicode object */
737 : : );
738 : :
739 : : /* --- Methods & Slots ---------------------------------------------------- */
740 : :
741 : : PyAPI_FUNC(PyObject *) _PyUnicode_JoinArray(
742 : : PyObject *separator,
743 : : PyObject *const *items,
744 : : Py_ssize_t seqlen
745 : : );
746 : :
747 : : /* Test whether a unicode is equal to ASCII identifier. Return 1 if true,
748 : : 0 otherwise. The right argument must be ASCII identifier.
749 : : Any error occurs inside will be cleared before return. */
750 : : PyAPI_FUNC(int) _PyUnicode_EqualToASCIIId(
751 : : PyObject *left, /* Left string */
752 : : _Py_Identifier *right /* Right identifier */
753 : : );
754 : :
755 : : /* Test whether a unicode is equal to ASCII string. Return 1 if true,
756 : : 0 otherwise. The right argument must be ASCII-encoded string.
757 : : Any error occurs inside will be cleared before return. */
758 : : PyAPI_FUNC(int) _PyUnicode_EqualToASCIIString(
759 : : PyObject *left,
760 : : const char *right /* ASCII-encoded string */
761 : : );
762 : :
763 : : /* Externally visible for str.strip(unicode) */
764 : : PyAPI_FUNC(PyObject *) _PyUnicode_XStrip(
765 : : PyObject *self,
766 : : int striptype,
767 : : PyObject *sepobj
768 : : );
769 : :
770 : : /* Using explicit passed-in values, insert the thousands grouping
771 : : into the string pointed to by buffer. For the argument descriptions,
772 : : see Objects/stringlib/localeutil.h */
773 : : PyAPI_FUNC(Py_ssize_t) _PyUnicode_InsertThousandsGrouping(
774 : : _PyUnicodeWriter *writer,
775 : : Py_ssize_t n_buffer,
776 : : PyObject *digits,
777 : : Py_ssize_t d_pos,
778 : : Py_ssize_t n_digits,
779 : : Py_ssize_t min_width,
780 : : const char *grouping,
781 : : PyObject *thousands_sep,
782 : : Py_UCS4 *maxchar);
783 : :
784 : : /* === Characters Type APIs =============================================== */
785 : :
786 : : /* These should not be used directly. Use the Py_UNICODE_IS* and
787 : : Py_UNICODE_TO* macros instead.
788 : :
789 : : These APIs are implemented in Objects/unicodectype.c.
790 : :
791 : : */
792 : :
793 : : PyAPI_FUNC(int) _PyUnicode_IsLowercase(
794 : : Py_UCS4 ch /* Unicode character */
795 : : );
796 : :
797 : : PyAPI_FUNC(int) _PyUnicode_IsUppercase(
798 : : Py_UCS4 ch /* Unicode character */
799 : : );
800 : :
801 : : PyAPI_FUNC(int) _PyUnicode_IsTitlecase(
802 : : Py_UCS4 ch /* Unicode character */
803 : : );
804 : :
805 : : PyAPI_FUNC(int) _PyUnicode_IsXidStart(
806 : : Py_UCS4 ch /* Unicode character */
807 : : );
808 : :
809 : : PyAPI_FUNC(int) _PyUnicode_IsXidContinue(
810 : : Py_UCS4 ch /* Unicode character */
811 : : );
812 : :
813 : : PyAPI_FUNC(int) _PyUnicode_IsWhitespace(
814 : : const Py_UCS4 ch /* Unicode character */
815 : : );
816 : :
817 : : PyAPI_FUNC(int) _PyUnicode_IsLinebreak(
818 : : const Py_UCS4 ch /* Unicode character */
819 : : );
820 : :
821 : : /* Py_DEPRECATED(3.3) */ PyAPI_FUNC(Py_UCS4) _PyUnicode_ToLowercase(
822 : : Py_UCS4 ch /* Unicode character */
823 : : );
824 : :
825 : : /* Py_DEPRECATED(3.3) */ PyAPI_FUNC(Py_UCS4) _PyUnicode_ToUppercase(
826 : : Py_UCS4 ch /* Unicode character */
827 : : );
828 : :
829 : : Py_DEPRECATED(3.3) PyAPI_FUNC(Py_UCS4) _PyUnicode_ToTitlecase(
830 : : Py_UCS4 ch /* Unicode character */
831 : : );
832 : :
833 : : PyAPI_FUNC(int) _PyUnicode_ToLowerFull(
834 : : Py_UCS4 ch, /* Unicode character */
835 : : Py_UCS4 *res
836 : : );
837 : :
838 : : PyAPI_FUNC(int) _PyUnicode_ToTitleFull(
839 : : Py_UCS4 ch, /* Unicode character */
840 : : Py_UCS4 *res
841 : : );
842 : :
843 : : PyAPI_FUNC(int) _PyUnicode_ToUpperFull(
844 : : Py_UCS4 ch, /* Unicode character */
845 : : Py_UCS4 *res
846 : : );
847 : :
848 : : PyAPI_FUNC(int) _PyUnicode_ToFoldedFull(
849 : : Py_UCS4 ch, /* Unicode character */
850 : : Py_UCS4 *res
851 : : );
852 : :
853 : : PyAPI_FUNC(int) _PyUnicode_IsCaseIgnorable(
854 : : Py_UCS4 ch /* Unicode character */
855 : : );
856 : :
857 : : PyAPI_FUNC(int) _PyUnicode_IsCased(
858 : : Py_UCS4 ch /* Unicode character */
859 : : );
860 : :
861 : : PyAPI_FUNC(int) _PyUnicode_ToDecimalDigit(
862 : : Py_UCS4 ch /* Unicode character */
863 : : );
864 : :
865 : : PyAPI_FUNC(int) _PyUnicode_ToDigit(
866 : : Py_UCS4 ch /* Unicode character */
867 : : );
868 : :
869 : : PyAPI_FUNC(double) _PyUnicode_ToNumeric(
870 : : Py_UCS4 ch /* Unicode character */
871 : : );
872 : :
873 : : PyAPI_FUNC(int) _PyUnicode_IsDecimalDigit(
874 : : Py_UCS4 ch /* Unicode character */
875 : : );
876 : :
877 : : PyAPI_FUNC(int) _PyUnicode_IsDigit(
878 : : Py_UCS4 ch /* Unicode character */
879 : : );
880 : :
881 : : PyAPI_FUNC(int) _PyUnicode_IsNumeric(
882 : : Py_UCS4 ch /* Unicode character */
883 : : );
884 : :
885 : : PyAPI_FUNC(int) _PyUnicode_IsPrintable(
886 : : Py_UCS4 ch /* Unicode character */
887 : : );
888 : :
889 : : PyAPI_FUNC(int) _PyUnicode_IsAlpha(
890 : : Py_UCS4 ch /* Unicode character */
891 : : );
892 : :
893 : : // Helper array used by Py_UNICODE_ISSPACE().
894 : : PyAPI_DATA(const unsigned char) _Py_ascii_whitespace[];
895 : :
896 : : // Since splitting on whitespace is an important use case, and
897 : : // whitespace in most situations is solely ASCII whitespace, we
898 : : // optimize for the common case by using a quick look-up table
899 : : // _Py_ascii_whitespace (see below) with an inlined check.
900 : 188085 : static inline int Py_UNICODE_ISSPACE(Py_UCS4 ch) {
901 [ + - ]: 188085 : if (ch < 128) {
902 : 188085 : return _Py_ascii_whitespace[ch];
903 : : }
904 : 0 : return _PyUnicode_IsWhitespace(ch);
905 : : }
906 : :
907 : : #define Py_UNICODE_ISLOWER(ch) _PyUnicode_IsLowercase(ch)
908 : : #define Py_UNICODE_ISUPPER(ch) _PyUnicode_IsUppercase(ch)
909 : : #define Py_UNICODE_ISTITLE(ch) _PyUnicode_IsTitlecase(ch)
910 : : #define Py_UNICODE_ISLINEBREAK(ch) _PyUnicode_IsLinebreak(ch)
911 : :
912 : : #define Py_UNICODE_TOLOWER(ch) _PyUnicode_ToLowercase(ch)
913 : : #define Py_UNICODE_TOUPPER(ch) _PyUnicode_ToUppercase(ch)
914 : : #define Py_UNICODE_TOTITLE(ch) _PyUnicode_ToTitlecase(ch)
915 : :
916 : : #define Py_UNICODE_ISDECIMAL(ch) _PyUnicode_IsDecimalDigit(ch)
917 : : #define Py_UNICODE_ISDIGIT(ch) _PyUnicode_IsDigit(ch)
918 : : #define Py_UNICODE_ISNUMERIC(ch) _PyUnicode_IsNumeric(ch)
919 : : #define Py_UNICODE_ISPRINTABLE(ch) _PyUnicode_IsPrintable(ch)
920 : :
921 : : #define Py_UNICODE_TODECIMAL(ch) _PyUnicode_ToDecimalDigit(ch)
922 : : #define Py_UNICODE_TODIGIT(ch) _PyUnicode_ToDigit(ch)
923 : : #define Py_UNICODE_TONUMERIC(ch) _PyUnicode_ToNumeric(ch)
924 : :
925 : : #define Py_UNICODE_ISALPHA(ch) _PyUnicode_IsAlpha(ch)
926 : :
927 : 67028638 : static inline int Py_UNICODE_ISALNUM(Py_UCS4 ch) {
928 : 67028638 : return (Py_UNICODE_ISALPHA(ch)
929 [ + + ]: 38471348 : || Py_UNICODE_ISDECIMAL(ch)
930 [ + - ]: 27352855 : || Py_UNICODE_ISDIGIT(ch)
931 [ + + - + ]: 105499986 : || Py_UNICODE_ISNUMERIC(ch));
932 : : }
933 : :
934 : :
935 : : /* === Misc functions ===================================================== */
936 : :
937 : : PyAPI_FUNC(PyObject*) _PyUnicode_FormatLong(PyObject *, int, int, int);
938 : :
939 : : /* Return an interned Unicode object for an Identifier; may fail if there is no memory.*/
940 : : PyAPI_FUNC(PyObject*) _PyUnicode_FromId(_Py_Identifier*);
941 : :
942 : : /* Fast equality check when the inputs are known to be exact unicode types
943 : : and where the hash values are equal (i.e. a very probable match) */
944 : : PyAPI_FUNC(int) _PyUnicode_EQ(PyObject *, PyObject *);
945 : :
946 : : /* Equality check. */
947 : : PyAPI_FUNC(int) _PyUnicode_Equal(PyObject *, PyObject *);
948 : :
949 : : PyAPI_FUNC(int) _PyUnicode_WideCharString_Converter(PyObject *, void *);
950 : : PyAPI_FUNC(int) _PyUnicode_WideCharString_Opt_Converter(PyObject *, void *);
951 : :
952 : : PyAPI_FUNC(Py_ssize_t) _PyUnicode_ScanIdentifier(PyObject *);
|