Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/unicodeobject.h
1 #ifndef Py_UNICODEOBJECT_H 2 #define Py_UNICODEOBJECT_H 3 4 /* 5 6 Unicode implementation based on original code by Fredrik Lundh, 7 modified by Marc-Andre Lemburg (mal@lemburg.com) according to the 8 Unicode Integration Proposal. (See 9 http://www.egenix.com/files/python/unicode-proposal.txt). 10 11 Copyright (c) Corporation for National Research Initiatives. 12 13 14 Original header: 15 -------------------------------------------------------------------- 16 17 * Yet another Unicode string type for Python. This type supports the 18 * 16-bit Basic Multilingual Plane (BMP) only. 19 * 20 * Written by Fredrik Lundh, January 1999. 21 * 22 * Copyright (c) 1999 by Secret Labs AB. 23 * Copyright (c) 1999 by Fredrik Lundh. 24 * 25 * fredrik@pythonware.com 26 * http://www.pythonware.com 27 * 28 * -------------------------------------------------------------------- 29 * This Unicode String Type is 30 * 31 * Copyright (c) 1999 by Secret Labs AB 32 * Copyright (c) 1999 by Fredrik Lundh 33 * 34 * By obtaining, using, and/or copying this software and/or its 35 * associated documentation, you agree that you have read, understood, 36 * and will comply with the following terms and conditions: 37 * 38 * Permission to use, copy, modify, and distribute this software and its 39 * associated documentation for any purpose and without fee is hereby 40 * granted, provided that the above copyright notice appears in all 41 * copies, and that both that copyright notice and this permission notice 42 * appear in supporting documentation, and that the name of Secret Labs 43 * AB or the author not be used in advertising or publicity pertaining to 44 * distribution of the software without specific, written prior 45 * permission. 46 * 47 * SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO 48 * THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND 49 * FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR 50 * ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 51 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 52 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 53 * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 54 * -------------------------------------------------------------------- */ 55 56 /* === Internal API ======================================================= */ 57 58 /* --- Internal Unicode Format -------------------------------------------- */ 59 60 /* Python 3.x requires unicode */ 61 #define Py_USING_UNICODE 62 63 #ifndef SIZEOF_WCHAR_T 64 #error Must define SIZEOF_WCHAR_T 65 #endif 66 67 #define Py_UNICODE_SIZE SIZEOF_WCHAR_T 68 69 /* If wchar_t can be used for UCS-4 storage, set Py_UNICODE_WIDE. 70 Otherwise, Unicode strings are stored as UCS-2 (with limited support 71 for UTF-16) */ 72 73 #if Py_UNICODE_SIZE >= 4 74 #define Py_UNICODE_WIDE 75 #endif 76 77 /* Set these flags if the platform has "wchar.h" and the 78 wchar_t type is a 16-bit unsigned type */ 79 /* #define HAVE_WCHAR_H */ 80 /* #define HAVE_USABLE_WCHAR_T */ 81 82 /* If the compiler provides a wchar_t type we try to support it 83 through the interface functions PyUnicode_FromWideChar(), 84 PyUnicode_AsWideChar() and PyUnicode_AsWideCharString(). */ 85 86 #ifdef HAVE_USABLE_WCHAR_T 87 # ifndef HAVE_WCHAR_H 88 # define HAVE_WCHAR_H 89 # endif 90 #endif 91 92 /* Py_UCS4 and Py_UCS2 are typedefs for the respective 93 unicode representations. */ 94 typedef uint32_t Py_UCS4; 95 typedef uint16_t Py_UCS2; 96 typedef uint8_t Py_UCS1; 97 98 #ifdef __cplusplus 99 extern "C" { 100 #endif 101 102 103 PyAPI_DATA(PyTypeObject) PyUnicode_Type; 104 PyAPI_DATA(PyTypeObject) PyUnicodeIter_Type; 105 106 #define PyUnicode_Check(op) \ 107 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_UNICODE_SUBCLASS) 108 #define PyUnicode_CheckExact(op) Py_IS_TYPE((op), &PyUnicode_Type) 109 110 /* --- Constants ---------------------------------------------------------- */ 111 112 /* This Unicode character will be used as replacement character during 113 decoding if the errors argument is set to "replace". Note: the 114 Unicode character U+FFFD is the official REPLACEMENT CHARACTER in 115 Unicode 3.0. */ 116 117 #define Py_UNICODE_REPLACEMENT_CHARACTER ((Py_UCS4) 0xFFFD) 118 119 /* === Public API ========================================================= */ 120 121 /* Similar to PyUnicode_FromUnicode(), but u points to UTF-8 encoded bytes */ 122 PyAPI_FUNC(PyObject*) PyUnicode_FromStringAndSize( 123 const char *u, /* UTF-8 encoded string */ 124 Py_ssize_t size /* size of buffer */ 125 ); 126 127 /* Similar to PyUnicode_FromUnicode(), but u points to null-terminated 128 UTF-8 encoded bytes. The size is determined with strlen(). */ 129 PyAPI_FUNC(PyObject*) PyUnicode_FromString( 130 const char *u /* UTF-8 encoded string */ 131 ); 132 133 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 134 PyAPI_FUNC(PyObject*) PyUnicode_Substring( 135 PyObject *str, 136 Py_ssize_t start, 137 Py_ssize_t end); 138 #endif 139 140 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 141 /* Copy the string into a UCS4 buffer including the null character if copy_null 142 is set. Return NULL and raise an exception on error. Raise a SystemError if 143 the buffer is smaller than the string. Return buffer on success. 144 145 buflen is the length of the buffer in (Py_UCS4) characters. */ 146 PyAPI_FUNC(Py_UCS4*) PyUnicode_AsUCS4( 147 PyObject *unicode, 148 Py_UCS4* buffer, 149 Py_ssize_t buflen, 150 int copy_null); 151 152 /* Copy the string into a UCS4 buffer. A new buffer is allocated using 153 * PyMem_Malloc; if this fails, NULL is returned with a memory error 154 exception set. */ 155 PyAPI_FUNC(Py_UCS4*) PyUnicode_AsUCS4Copy(PyObject *unicode); 156 #endif 157 158 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 159 /* Get the length of the Unicode object. */ 160 161 PyAPI_FUNC(Py_ssize_t) PyUnicode_GetLength( 162 PyObject *unicode 163 ); 164 #endif 165 166 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 167 /* Read a character from the string. */ 168 169 PyAPI_FUNC(Py_UCS4) PyUnicode_ReadChar( 170 PyObject *unicode, 171 Py_ssize_t index 172 ); 173 174 /* Write a character to the string. The string must have been created through 175 PyUnicode_New, must not be shared, and must not have been hashed yet. 176 177 Return 0 on success, -1 on error. */ 178 179 PyAPI_FUNC(int) PyUnicode_WriteChar( 180 PyObject *unicode, 181 Py_ssize_t index, 182 Py_UCS4 character 183 ); 184 #endif 185 186 /* Resize a Unicode object. The length is the number of codepoints. 187 188 *unicode is modified to point to the new (resized) object and 0 189 returned on success. 190 191 Try to resize the string in place (which is usually faster than allocating 192 a new string and copy characters), or create a new string. 193 194 Error handling is implemented as follows: an exception is set, -1 195 is returned and *unicode left untouched. 196 197 WARNING: The function doesn't check string content, the result may not be a 198 string in canonical representation. */ 199 200 PyAPI_FUNC(int) PyUnicode_Resize( 201 PyObject **unicode, /* Pointer to the Unicode object */ 202 Py_ssize_t length /* New length */ 203 ); 204 205 /* Decode obj to a Unicode object. 206 207 bytes, bytearray and other bytes-like objects are decoded according to the 208 given encoding and error handler. The encoding and error handler can be 209 NULL to have the interface use UTF-8 and "strict". 210 211 All other objects (including Unicode objects) raise an exception. 212 213 The API returns NULL in case of an error. The caller is responsible 214 for decref'ing the returned objects. 215 216 */ 217 218 PyAPI_FUNC(PyObject*) PyUnicode_FromEncodedObject( 219 PyObject *obj, /* Object */ 220 const char *encoding, /* encoding */ 221 const char *errors /* error handling */ 222 ); 223 224 /* Copy an instance of a Unicode subtype to a new true Unicode object if 225 necessary. If obj is already a true Unicode object (not a subtype), return 226 the reference with *incremented* refcount. 227 228 The API returns NULL in case of an error. The caller is responsible 229 for decref'ing the returned objects. 230 231 */ 232 233 PyAPI_FUNC(PyObject*) PyUnicode_FromObject( 234 PyObject *obj /* Object */ 235 ); 236 237 PyAPI_FUNC(PyObject *) PyUnicode_FromFormatV( 238 const char *format, /* ASCII-encoded string */ 239 va_list vargs 240 ); 241 PyAPI_FUNC(PyObject *) PyUnicode_FromFormat( 242 const char *format, /* ASCII-encoded string */ 243 ... 244 ); 245 246 PyAPI_FUNC(void) PyUnicode_InternInPlace(PyObject **); 247 PyAPI_FUNC(PyObject *) PyUnicode_InternFromString( 248 const char *u /* UTF-8 encoded string */ 249 ); 250 251 /* --- wchar_t support for platforms which support it --------------------- */ 252 253 #ifdef HAVE_WCHAR_H 254 255 /* Create a Unicode Object from the wchar_t buffer w of the given 256 size. 257 258 The buffer is copied into the new object. */ 259 260 PyAPI_FUNC(PyObject*) PyUnicode_FromWideChar( 261 const wchar_t *w, /* wchar_t buffer */ 262 Py_ssize_t size /* size of buffer */ 263 ); 264 265 /* Copies the Unicode Object contents into the wchar_t buffer w. At 266 most size wchar_t characters are copied. 267 268 Note that the resulting wchar_t string may or may not be 269 0-terminated. It is the responsibility of the caller to make sure 270 that the wchar_t string is 0-terminated in case this is required by 271 the application. 272 273 Returns the number of wchar_t characters copied (excluding a 274 possibly trailing 0-termination character) or -1 in case of an 275 error. */ 276 277 PyAPI_FUNC(Py_ssize_t) PyUnicode_AsWideChar( 278 PyObject *unicode, /* Unicode object */ 279 wchar_t *w, /* wchar_t buffer */ 280 Py_ssize_t size /* size of buffer */ 281 ); 282 283 /* Convert the Unicode object to a wide character string. The output string 284 always ends with a nul character. If size is not NULL, write the number of 285 wide characters (excluding the null character) into *size. 286 287 Returns a buffer allocated by PyMem_Malloc() (use PyMem_Free() to free it) 288 on success. On error, returns NULL, *size is undefined and raises a 289 MemoryError. */ 290 291 PyAPI_FUNC(wchar_t*) PyUnicode_AsWideCharString( 292 PyObject *unicode, /* Unicode object */ 293 Py_ssize_t *size /* number of characters of the result */ 294 ); 295 296 #endif 297 298 /* --- Unicode ordinals --------------------------------------------------- */ 299 300 /* Create a Unicode Object from the given Unicode code point ordinal. 301 302 The ordinal must be in range(0x110000). A ValueError is 303 raised in case it is not. 304 305 */ 306 307 PyAPI_FUNC(PyObject*) PyUnicode_FromOrdinal(int ordinal); 308 309 /* === Builtin Codecs ===================================================== 310 311 Many of these APIs take two arguments encoding and errors. These 312 parameters encoding and errors have the same semantics as the ones 313 of the builtin str() API. 314 315 Setting encoding to NULL causes the default encoding (UTF-8) to be used. 316 317 Error handling is set by errors which may also be set to NULL 318 meaning to use the default handling defined for the codec. Default 319 error handling for all builtin codecs is "strict" (ValueErrors are 320 raised). 321 322 The codecs all use a similar interface. Only deviation from the 323 generic ones are documented. 324 325 */ 326 327 /* --- Manage the default encoding ---------------------------------------- */ 328 329 /* Returns "utf-8". */ 330 PyAPI_FUNC(const char*) PyUnicode_GetDefaultEncoding(void); 331 332 /* --- Generic Codecs ----------------------------------------------------- */ 333 334 /* Create a Unicode object by decoding the encoded string s of the 335 given size. */ 336 337 PyAPI_FUNC(PyObject*) PyUnicode_Decode( 338 const char *s, /* encoded string */ 339 Py_ssize_t size, /* size of buffer */ 340 const char *encoding, /* encoding */ 341 const char *errors /* error handling */ 342 ); 343 344 /* Decode a Unicode object unicode and return the result as Python 345 object. 346 347 This API is DEPRECATED and will be removed in 3.15. 348 The only supported standard encoding is rot13. 349 Use PyCodec_Decode() to decode with rot13 and non-standard codecs 350 that decode from str. */ 351 352 Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedObject( 353 PyObject *unicode, /* Unicode object */ 354 const char *encoding, /* encoding */ 355 const char *errors /* error handling */ 356 ); 357 358 /* Decode a Unicode object unicode and return the result as Unicode 359 object. 360 361 This API is DEPRECATED and will be removed in 3.15. 362 The only supported standard encoding is rot13. 363 Use PyCodec_Decode() to decode with rot13 and non-standard codecs 364 that decode from str to str. */ 365 366 Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsDecodedUnicode( 367 PyObject *unicode, /* Unicode object */ 368 const char *encoding, /* encoding */ 369 const char *errors /* error handling */ 370 ); 371 372 /* Encodes a Unicode object and returns the result as Python 373 object. 374 375 This API is DEPRECATED and will be removed in 3.15. 376 It is superseded by PyUnicode_AsEncodedString() 377 since all standard encodings (except rot13) encode str to bytes. 378 Use PyCodec_Encode() for encoding with rot13 and non-standard codecs 379 that encode form str to non-bytes. */ 380 381 Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedObject( 382 PyObject *unicode, /* Unicode object */ 383 const char *encoding, /* encoding */ 384 const char *errors /* error handling */ 385 ); 386 387 /* Encodes a Unicode object and returns the result as Python string 388 object. */ 389 390 PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedString( 391 PyObject *unicode, /* Unicode object */ 392 const char *encoding, /* encoding */ 393 const char *errors /* error handling */ 394 ); 395 396 /* Encodes a Unicode object and returns the result as Unicode 397 object. 398 399 This API is DEPRECATED and will be removed in 3.15. 400 The only supported standard encodings is rot13. 401 Use PyCodec_Encode() to encode with rot13 and non-standard codecs 402 that encode from str to str. */ 403 404 Py_DEPRECATED(3.6) PyAPI_FUNC(PyObject*) PyUnicode_AsEncodedUnicode( 405 PyObject *unicode, /* Unicode object */ 406 const char *encoding, /* encoding */ 407 const char *errors /* error handling */ 408 ); 409 410 /* Build an encoding map. */ 411 412 PyAPI_FUNC(PyObject*) PyUnicode_BuildEncodingMap( 413 PyObject* string /* 256 character map */ 414 ); 415 416 /* --- UTF-7 Codecs ------------------------------------------------------- */ 417 418 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF7( 419 const char *string, /* UTF-7 encoded string */ 420 Py_ssize_t length, /* size of string */ 421 const char *errors /* error handling */ 422 ); 423 424 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF7Stateful( 425 const char *string, /* UTF-7 encoded string */ 426 Py_ssize_t length, /* size of string */ 427 const char *errors, /* error handling */ 428 Py_ssize_t *consumed /* bytes consumed */ 429 ); 430 431 /* --- UTF-8 Codecs ------------------------------------------------------- */ 432 433 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF8( 434 const char *string, /* UTF-8 encoded string */ 435 Py_ssize_t length, /* size of string */ 436 const char *errors /* error handling */ 437 ); 438 439 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF8Stateful( 440 const char *string, /* UTF-8 encoded string */ 441 Py_ssize_t length, /* size of string */ 442 const char *errors, /* error handling */ 443 Py_ssize_t *consumed /* bytes consumed */ 444 ); 445 446 PyAPI_FUNC(PyObject*) PyUnicode_AsUTF8String( 447 PyObject *unicode /* Unicode object */ 448 ); 449 450 /* Returns a pointer to the default encoding (UTF-8) of the 451 Unicode object unicode and the size of the encoded representation 452 in bytes stored in *size. 453 454 In case of an error, no *size is set. 455 456 This function caches the UTF-8 encoded string in the unicodeobject 457 and subsequent calls will return the same string. The memory is released 458 when the unicodeobject is deallocated. 459 */ 460 461 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000 462 PyAPI_FUNC(const char *) PyUnicode_AsUTF8AndSize( 463 PyObject *unicode, 464 Py_ssize_t *size); 465 #endif 466 467 /* --- UTF-32 Codecs ------------------------------------------------------ */ 468 469 /* Decodes length bytes from a UTF-32 encoded buffer string and returns 470 the corresponding Unicode object. 471 472 errors (if non-NULL) defines the error handling. It defaults 473 to "strict". 474 475 If byteorder is non-NULL, the decoder starts decoding using the 476 given byte order: 477 478 *byteorder == -1: little endian 479 *byteorder == 0: native order 480 *byteorder == 1: big endian 481 482 In native mode, the first four bytes of the stream are checked for a 483 BOM mark. If found, the BOM mark is analysed, the byte order 484 adjusted and the BOM skipped. In the other modes, no BOM mark 485 interpretation is done. After completion, *byteorder is set to the 486 current byte order at the end of input data. 487 488 If byteorder is NULL, the codec starts in native order mode. 489 490 */ 491 492 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF32( 493 const char *string, /* UTF-32 encoded string */ 494 Py_ssize_t length, /* size of string */ 495 const char *errors, /* error handling */ 496 int *byteorder /* pointer to byteorder to use 497 0=native;-1=LE,1=BE; updated on 498 exit */ 499 ); 500 501 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF32Stateful( 502 const char *string, /* UTF-32 encoded string */ 503 Py_ssize_t length, /* size of string */ 504 const char *errors, /* error handling */ 505 int *byteorder, /* pointer to byteorder to use 506 0=native;-1=LE,1=BE; updated on 507 exit */ 508 Py_ssize_t *consumed /* bytes consumed */ 509 ); 510 511 /* Returns a Python string using the UTF-32 encoding in native byte 512 order. The string always starts with a BOM mark. */ 513 514 PyAPI_FUNC(PyObject*) PyUnicode_AsUTF32String( 515 PyObject *unicode /* Unicode object */ 516 ); 517 518 /* Returns a Python string object holding the UTF-32 encoded value of 519 the Unicode data. 520 521 If byteorder is not 0, output is written according to the following 522 byte order: 523 524 byteorder == -1: little endian 525 byteorder == 0: native byte order (writes a BOM mark) 526 byteorder == 1: big endian 527 528 If byteorder is 0, the output string will always start with the 529 Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is 530 prepended. 531 532 */ 533 534 /* --- UTF-16 Codecs ------------------------------------------------------ */ 535 536 /* Decodes length bytes from a UTF-16 encoded buffer string and returns 537 the corresponding Unicode object. 538 539 errors (if non-NULL) defines the error handling. It defaults 540 to "strict". 541 542 If byteorder is non-NULL, the decoder starts decoding using the 543 given byte order: 544 545 *byteorder == -1: little endian 546 *byteorder == 0: native order 547 *byteorder == 1: big endian 548 549 In native mode, the first two bytes of the stream are checked for a 550 BOM mark. If found, the BOM mark is analysed, the byte order 551 adjusted and the BOM skipped. In the other modes, no BOM mark 552 interpretation is done. After completion, *byteorder is set to the 553 current byte order at the end of input data. 554 555 If byteorder is NULL, the codec starts in native order mode. 556 557 */ 558 559 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF16( 560 const char *string, /* UTF-16 encoded string */ 561 Py_ssize_t length, /* size of string */ 562 const char *errors, /* error handling */ 563 int *byteorder /* pointer to byteorder to use 564 0=native;-1=LE,1=BE; updated on 565 exit */ 566 ); 567 568 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUTF16Stateful( 569 const char *string, /* UTF-16 encoded string */ 570 Py_ssize_t length, /* size of string */ 571 const char *errors, /* error handling */ 572 int *byteorder, /* pointer to byteorder to use 573 0=native;-1=LE,1=BE; updated on 574 exit */ 575 Py_ssize_t *consumed /* bytes consumed */ 576 ); 577 578 /* Returns a Python string using the UTF-16 encoding in native byte 579 order. The string always starts with a BOM mark. */ 580 581 PyAPI_FUNC(PyObject*) PyUnicode_AsUTF16String( 582 PyObject *unicode /* Unicode object */ 583 ); 584 585 /* --- Unicode-Escape Codecs ---------------------------------------------- */ 586 587 PyAPI_FUNC(PyObject*) PyUnicode_DecodeUnicodeEscape( 588 const char *string, /* Unicode-Escape encoded string */ 589 Py_ssize_t length, /* size of string */ 590 const char *errors /* error handling */ 591 ); 592 593 PyAPI_FUNC(PyObject*) PyUnicode_AsUnicodeEscapeString( 594 PyObject *unicode /* Unicode object */ 595 ); 596 597 /* --- Raw-Unicode-Escape Codecs ------------------------------------------ */ 598 599 PyAPI_FUNC(PyObject*) PyUnicode_DecodeRawUnicodeEscape( 600 const char *string, /* Raw-Unicode-Escape encoded string */ 601 Py_ssize_t length, /* size of string */ 602 const char *errors /* error handling */ 603 ); 604 605 PyAPI_FUNC(PyObject*) PyUnicode_AsRawUnicodeEscapeString( 606 PyObject *unicode /* Unicode object */ 607 ); 608 609 /* --- Latin-1 Codecs ----------------------------------------------------- 610 611 Note: Latin-1 corresponds to the first 256 Unicode ordinals. */ 612 613 PyAPI_FUNC(PyObject*) PyUnicode_DecodeLatin1( 614 const char *string, /* Latin-1 encoded string */ 615 Py_ssize_t length, /* size of string */ 616 const char *errors /* error handling */ 617 ); 618 619 PyAPI_FUNC(PyObject*) PyUnicode_AsLatin1String( 620 PyObject *unicode /* Unicode object */ 621 ); 622 623 /* --- ASCII Codecs ------------------------------------------------------- 624 625 Only 7-bit ASCII data is expected. All other codes generate errors. 626 627 */ 628 629 PyAPI_FUNC(PyObject*) PyUnicode_DecodeASCII( 630 const char *string, /* ASCII encoded string */ 631 Py_ssize_t length, /* size of string */ 632 const char *errors /* error handling */ 633 ); 634 635 PyAPI_FUNC(PyObject*) PyUnicode_AsASCIIString( 636 PyObject *unicode /* Unicode object */ 637 ); 638 639 /* --- Character Map Codecs ----------------------------------------------- 640 641 This codec uses mappings to encode and decode characters. 642 643 Decoding mappings must map byte ordinals (integers in the range from 0 to 644 255) to Unicode strings, integers (which are then interpreted as Unicode 645 ordinals) or None. Unmapped data bytes (ones which cause a LookupError) 646 as well as mapped to None, 0xFFFE or '\ufffe' are treated as "undefined 647 mapping" and cause an error. 648 649 Encoding mappings must map Unicode ordinal integers to bytes objects, 650 integers in the range from 0 to 255 or None. Unmapped character 651 ordinals (ones which cause a LookupError) as well as mapped to 652 None are treated as "undefined mapping" and cause an error. 653 654 */ 655 656 PyAPI_FUNC(PyObject*) PyUnicode_DecodeCharmap( 657 const char *string, /* Encoded string */ 658 Py_ssize_t length, /* size of string */ 659 PyObject *mapping, /* decoding mapping */ 660 const char *errors /* error handling */ 661 ); 662 663 PyAPI_FUNC(PyObject*) PyUnicode_AsCharmapString( 664 PyObject *unicode, /* Unicode object */ 665 PyObject *mapping /* encoding mapping */ 666 ); 667 668 /* --- MBCS codecs for Windows -------------------------------------------- */ 669 670 #ifdef MS_WINDOWS 671 PyAPI_FUNC(PyObject*) PyUnicode_DecodeMBCS( 672 const char *string, /* MBCS encoded string */ 673 Py_ssize_t length, /* size of string */ 674 const char *errors /* error handling */ 675 ); 676 677 PyAPI_FUNC(PyObject*) PyUnicode_DecodeMBCSStateful( 678 const char *string, /* MBCS encoded string */ 679 Py_ssize_t length, /* size of string */ 680 const char *errors, /* error handling */ 681 Py_ssize_t *consumed /* bytes consumed */ 682 ); 683 684 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 685 PyAPI_FUNC(PyObject*) PyUnicode_DecodeCodePageStateful( 686 int code_page, /* code page number */ 687 const char *string, /* encoded string */ 688 Py_ssize_t length, /* size of string */ 689 const char *errors, /* error handling */ 690 Py_ssize_t *consumed /* bytes consumed */ 691 ); 692 #endif 693 694 PyAPI_FUNC(PyObject*) PyUnicode_AsMBCSString( 695 PyObject *unicode /* Unicode object */ 696 ); 697 698 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 699 PyAPI_FUNC(PyObject*) PyUnicode_EncodeCodePage( 700 int code_page, /* code page number */ 701 PyObject *unicode, /* Unicode object */ 702 const char *errors /* error handling */ 703 ); 704 #endif 705 706 #endif /* MS_WINDOWS */ 707 708 /* --- Locale encoding --------------------------------------------------- */ 709 710 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 711 /* Decode a string from the current locale encoding. The decoder is strict if 712 *surrogateescape* is equal to zero, otherwise it uses the 'surrogateescape' 713 error handler (PEP 383) to escape undecodable bytes. If a byte sequence can 714 be decoded as a surrogate character and *surrogateescape* is not equal to 715 zero, the byte sequence is escaped using the 'surrogateescape' error handler 716 instead of being decoded. *str* must end with a null character but cannot 717 contain embedded null characters. */ 718 719 PyAPI_FUNC(PyObject*) PyUnicode_DecodeLocaleAndSize( 720 const char *str, 721 Py_ssize_t len, 722 const char *errors); 723 724 /* Similar to PyUnicode_DecodeLocaleAndSize(), but compute the string 725 length using strlen(). */ 726 727 PyAPI_FUNC(PyObject*) PyUnicode_DecodeLocale( 728 const char *str, 729 const char *errors); 730 731 /* Encode a Unicode object to the current locale encoding. The encoder is 732 strict is *surrogateescape* is equal to zero, otherwise the 733 "surrogateescape" error handler is used. Return a bytes object. The string 734 cannot contain embedded null characters. */ 735 736 PyAPI_FUNC(PyObject*) PyUnicode_EncodeLocale( 737 PyObject *unicode, 738 const char *errors 739 ); 740 #endif 741 742 /* --- File system encoding ---------------------------------------------- */ 743 744 /* ParseTuple converter: encode str objects to bytes using 745 PyUnicode_EncodeFSDefault(); bytes objects are output as-is. */ 746 747 PyAPI_FUNC(int) PyUnicode_FSConverter(PyObject*, void*); 748 749 /* ParseTuple converter: decode bytes objects to unicode using 750 PyUnicode_DecodeFSDefaultAndSize(); str objects are output as-is. */ 751 752 PyAPI_FUNC(int) PyUnicode_FSDecoder(PyObject*, void*); 753 754 /* Decode a null-terminated string from the Python filesystem encoding 755 and error handler. 756 757 If the string length is known, use PyUnicode_DecodeFSDefaultAndSize(). */ 758 PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefault( 759 const char *s /* encoded string */ 760 ); 761 762 /* Decode a string from the Python filesystem encoding and error handler. */ 763 PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefaultAndSize( 764 const char *s, /* encoded string */ 765 Py_ssize_t size /* size */ 766 ); 767 768 /* Encode a Unicode object to the Python filesystem encoding and error handler. 769 Return bytes. */ 770 PyAPI_FUNC(PyObject*) PyUnicode_EncodeFSDefault( 771 PyObject *unicode 772 ); 773 774 /* --- Methods & Slots ---------------------------------------------------- 775 776 These are capable of handling Unicode objects and strings on input 777 (we refer to them as strings in the descriptions) and return 778 Unicode objects or integers as appropriate. */ 779 780 /* Concat two strings giving a new Unicode string. */ 781 782 PyAPI_FUNC(PyObject*) PyUnicode_Concat( 783 PyObject *left, /* Left string */ 784 PyObject *right /* Right string */ 785 ); 786 787 /* Concat two strings and put the result in *pleft 788 (sets *pleft to NULL on error) */ 789 790 PyAPI_FUNC(void) PyUnicode_Append( 791 PyObject **pleft, /* Pointer to left string */ 792 PyObject *right /* Right string */ 793 ); 794 795 /* Concat two strings, put the result in *pleft and drop the right object 796 (sets *pleft to NULL on error) */ 797 798 PyAPI_FUNC(void) PyUnicode_AppendAndDel( 799 PyObject **pleft, /* Pointer to left string */ 800 PyObject *right /* Right string */ 801 ); 802 803 /* Split a string giving a list of Unicode strings. 804 805 If sep is NULL, splitting will be done at all whitespace 806 substrings. Otherwise, splits occur at the given separator. 807 808 At most maxsplit splits will be done. If negative, no limit is set. 809 810 Separators are not included in the resulting list. 811 812 */ 813 814 PyAPI_FUNC(PyObject*) PyUnicode_Split( 815 PyObject *s, /* String to split */ 816 PyObject *sep, /* String separator */ 817 Py_ssize_t maxsplit /* Maxsplit count */ 818 ); 819 820 /* Dito, but split at line breaks. 821 822 CRLF is considered to be one line break. Line breaks are not 823 included in the resulting list. */ 824 825 PyAPI_FUNC(PyObject*) PyUnicode_Splitlines( 826 PyObject *s, /* String to split */ 827 int keepends /* If true, line end markers are included */ 828 ); 829 830 /* Partition a string using a given separator. */ 831 832 PyAPI_FUNC(PyObject*) PyUnicode_Partition( 833 PyObject *s, /* String to partition */ 834 PyObject *sep /* String separator */ 835 ); 836 837 /* Partition a string using a given separator, searching from the end of the 838 string. */ 839 840 PyAPI_FUNC(PyObject*) PyUnicode_RPartition( 841 PyObject *s, /* String to partition */ 842 PyObject *sep /* String separator */ 843 ); 844 845 /* Split a string giving a list of Unicode strings. 846 847 If sep is NULL, splitting will be done at all whitespace 848 substrings. Otherwise, splits occur at the given separator. 849 850 At most maxsplit splits will be done. But unlike PyUnicode_Split 851 PyUnicode_RSplit splits from the end of the string. If negative, 852 no limit is set. 853 854 Separators are not included in the resulting list. 855 856 */ 857 858 PyAPI_FUNC(PyObject*) PyUnicode_RSplit( 859 PyObject *s, /* String to split */ 860 PyObject *sep, /* String separator */ 861 Py_ssize_t maxsplit /* Maxsplit count */ 862 ); 863 864 /* Translate a string by applying a character mapping table to it and 865 return the resulting Unicode object. 866 867 The mapping table must map Unicode ordinal integers to Unicode strings, 868 Unicode ordinal integers or None (causing deletion of the character). 869 870 Mapping tables may be dictionaries or sequences. Unmapped character 871 ordinals (ones which cause a LookupError) are left untouched and 872 are copied as-is. 873 874 */ 875 876 PyAPI_FUNC(PyObject *) PyUnicode_Translate( 877 PyObject *str, /* String */ 878 PyObject *table, /* Translate table */ 879 const char *errors /* error handling */ 880 ); 881 882 /* Join a sequence of strings using the given separator and return 883 the resulting Unicode string. */ 884 885 PyAPI_FUNC(PyObject*) PyUnicode_Join( 886 PyObject *separator, /* Separator string */ 887 PyObject *seq /* Sequence object */ 888 ); 889 890 /* Return 1 if substr matches str[start:end] at the given tail end, 0 891 otherwise. */ 892 893 PyAPI_FUNC(Py_ssize_t) PyUnicode_Tailmatch( 894 PyObject *str, /* String */ 895 PyObject *substr, /* Prefix or Suffix string */ 896 Py_ssize_t start, /* Start index */ 897 Py_ssize_t end, /* Stop index */ 898 int direction /* Tail end: -1 prefix, +1 suffix */ 899 ); 900 901 /* Return the first position of substr in str[start:end] using the 902 given search direction or -1 if not found. -2 is returned in case 903 an error occurred and an exception is set. */ 904 905 PyAPI_FUNC(Py_ssize_t) PyUnicode_Find( 906 PyObject *str, /* String */ 907 PyObject *substr, /* Substring to find */ 908 Py_ssize_t start, /* Start index */ 909 Py_ssize_t end, /* Stop index */ 910 int direction /* Find direction: +1 forward, -1 backward */ 911 ); 912 913 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 914 /* Like PyUnicode_Find, but search for single character only. */ 915 PyAPI_FUNC(Py_ssize_t) PyUnicode_FindChar( 916 PyObject *str, 917 Py_UCS4 ch, 918 Py_ssize_t start, 919 Py_ssize_t end, 920 int direction 921 ); 922 #endif 923 924 /* Count the number of occurrences of substr in str[start:end]. */ 925 926 PyAPI_FUNC(Py_ssize_t) PyUnicode_Count( 927 PyObject *str, /* String */ 928 PyObject *substr, /* Substring to count */ 929 Py_ssize_t start, /* Start index */ 930 Py_ssize_t end /* Stop index */ 931 ); 932 933 /* Replace at most maxcount occurrences of substr in str with replstr 934 and return the resulting Unicode object. */ 935 936 PyAPI_FUNC(PyObject *) PyUnicode_Replace( 937 PyObject *str, /* String */ 938 PyObject *substr, /* Substring to find */ 939 PyObject *replstr, /* Substring to replace */ 940 Py_ssize_t maxcount /* Max. number of replacements to apply; 941 -1 = all */ 942 ); 943 944 /* Compare two strings and return -1, 0, 1 for less than, equal, 945 greater than resp. 946 Raise an exception and return -1 on error. */ 947 948 PyAPI_FUNC(int) PyUnicode_Compare( 949 PyObject *left, /* Left string */ 950 PyObject *right /* Right string */ 951 ); 952 953 /* Compare a Unicode object with C string and return -1, 0, 1 for less than, 954 equal, and greater than, respectively. It is best to pass only 955 ASCII-encoded strings, but the function interprets the input string as 956 ISO-8859-1 if it contains non-ASCII characters. 957 This function does not raise exceptions. */ 958 959 PyAPI_FUNC(int) PyUnicode_CompareWithASCIIString( 960 PyObject *left, 961 const char *right /* ASCII-encoded string */ 962 ); 963 964 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030D0000 965 /* Compare a Unicode object with UTF-8 encoded C string. 966 Return 1 if they are equal, or 0 otherwise. 967 This function does not raise exceptions. */ 968 969 PyAPI_FUNC(int) PyUnicode_EqualToUTF8(PyObject *, const char *); 970 PyAPI_FUNC(int) PyUnicode_EqualToUTF8AndSize(PyObject *, const char *, Py_ssize_t); 971 #endif 972 973 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030e0000 974 PyAPI_FUNC(int) PyUnicode_Equal(PyObject *str1, PyObject *str2); 975 #endif 976 977 /* Rich compare two strings and return one of the following: 978 979 - NULL in case an exception was raised 980 - Py_True or Py_False for successful comparisons 981 - Py_NotImplemented in case the type combination is unknown 982 983 Possible values for op: 984 985 Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, Py_LE 986 987 */ 988 989 PyAPI_FUNC(PyObject *) PyUnicode_RichCompare( 990 PyObject *left, /* Left string */ 991 PyObject *right, /* Right string */ 992 int op /* Operation: Py_EQ, Py_NE, Py_GT, etc. */ 993 ); 994 995 /* Apply an argument tuple or dictionary to a format string and return 996 the resulting Unicode string. */ 997 998 PyAPI_FUNC(PyObject *) PyUnicode_Format( 999 PyObject *format, /* Format string */ 1000 PyObject *args /* Argument tuple or dictionary */ 1001 ); 1002 1003 /* Checks whether element is contained in container and return 1/0 1004 accordingly. 1005 1006 element has to coerce to a one element Unicode string. -1 is 1007 returned in case of an error. */ 1008 1009 PyAPI_FUNC(int) PyUnicode_Contains( 1010 PyObject *container, /* Container string */ 1011 PyObject *element /* Element string */ 1012 ); 1013 1014 /* Checks whether argument is a valid identifier. */ 1015 1016 PyAPI_FUNC(int) PyUnicode_IsIdentifier(PyObject *s); 1017 1018 /* === Characters Type APIs =============================================== */ 1019 1020 #ifndef Py_LIMITED_API 1021 # define Py_CPYTHON_UNICODEOBJECT_H 1022 # include "cpython/unicodeobject.h" 1023 # undef Py_CPYTHON_UNICODEOBJECT_H 1024 #endif 1025 1026 #ifdef __cplusplus 1027 } 1028 #endif 1029 #endif /* !Py_UNICODEOBJECT_H */
