unicodeobject.h revision 9e896b37c7a554250d7d832566cc4fe7d30d034c
1#ifndef Py_UNICODEOBJECT_H 2#define Py_UNICODEOBJECT_H 3 4/* 5 6Unicode implementation based on original code by Fredrik Lundh, 7modified by Marc-Andre Lemburg (mal@lemburg.com) according to the 8Unicode Integration Proposal (see file Misc/unicode.txt). 9 10(c) Copyright CNRI, All Rights Reserved. NO WARRANTY. 11 12 13 Original header: 14 -------------------------------------------------------------------- 15 16 * Yet another Unicode string type for Python. This type supports the 17 * 16-bit Basic Multilingual Plane (BMP) only. 18 * 19 * Written by Fredrik Lundh, January 1999. 20 * 21 * Copyright (c) 1999 by Secret Labs AB. 22 * Copyright (c) 1999 by Fredrik Lundh. 23 * 24 * fredrik@pythonware.com 25 * http://www.pythonware.com 26 * 27 * -------------------------------------------------------------------- 28 * This Unicode String Type is 29 * 30 * Copyright (c) 1999 by Secret Labs AB 31 * Copyright (c) 1999 by Fredrik Lundh 32 * 33 * By obtaining, using, and/or copying this software and/or its 34 * associated documentation, you agree that you have read, understood, 35 * and will comply with the following terms and conditions: 36 * 37 * Permission to use, copy, modify, and distribute this software and its 38 * associated documentation for any purpose and without fee is hereby 39 * granted, provided that the above copyright notice appears in all 40 * copies, and that both that copyright notice and this permission notice 41 * appear in supporting documentation, and that the name of Secret Labs 42 * AB or the author not be used in advertising or publicity pertaining to 43 * distribution of the software without specific, written prior 44 * permission. 45 * 46 * SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO 47 * THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND 48 * FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR 49 * ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 50 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 51 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 52 * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 53 * -------------------------------------------------------------------- */ 54 55#include "ctype.h" 56 57/* === Internal API ======================================================= */ 58 59/* --- Internal Unicode Format -------------------------------------------- */ 60 61/* Set these flags if the platform has "wchar.h", "wctype.h" and the 62 wchar_t type is a 16-bit unsigned type */ 63/* #define HAVE_WCHAR_H */ 64/* #define HAVE_USABLE_WCHAR_T */ 65 66/* Defaults for various platforms */ 67#ifndef HAVE_USABLE_WCHAR_T 68 69/* Windows has a usable wchar_t type */ 70# if defined(MS_WIN32) 71# define HAVE_USABLE_WCHAR_T 72# endif 73 74#endif 75 76/* If the compiler provides a wchar_t type we try to support it 77 through the interface functions PyUnicode_FromWideChar() and 78 PyUnicode_AsWideChar(). */ 79 80#ifdef HAVE_USABLE_WCHAR_T 81# define HAVE_WCHAR_H 82#endif 83 84#ifdef HAVE_WCHAR_H 85/* Work around a cosmetic bug in BSDI 4.x wchar.h; thanks to Thomas Wouters */ 86# ifdef _HAVE_BSDI 87# include <time.h> 88# endif 89# include "wchar.h" 90#endif 91 92#ifdef HAVE_USABLE_WCHAR_T 93 94/* If the compiler defines whcar_t as a 16-bit unsigned type we can 95 use the compiler type directly. Works fine with all modern Windows 96 platforms. */ 97 98typedef wchar_t Py_UNICODE; 99 100#else 101 102/* Use if you have a standard ANSI compiler, without wchar_t support. 103 If a short is not 16 bits on your platform, you have to fix the 104 typedef below, or the module initialization code will complain. */ 105 106typedef unsigned short Py_UNICODE; 107 108#endif 109 110/* --- Internal Unicode Operations ---------------------------------------- */ 111 112/* If you want Python to use the compiler's wctype.h functions instead 113 of the ones supplied with Python, define WANT_WCTYPE_FUNCTIONS or 114 configure Python using --with-ctype-functions. This reduces the 115 interpreter's code size. */ 116 117#if defined(HAVE_USABLE_WCHAR_T) && defined(WANT_WCTYPE_FUNCTIONS) 118 119#include "wctype.h" 120 121#define Py_UNICODE_ISSPACE(ch) iswspace(ch) 122 123#define Py_UNICODE_ISLOWER(ch) iswlower(ch) 124#define Py_UNICODE_ISUPPER(ch) iswupper(ch) 125#define Py_UNICODE_ISTITLE(ch) _PyUnicode_IsTitlecase(ch) 126#define Py_UNICODE_ISLINEBREAK(ch) _PyUnicode_IsLinebreak(ch) 127 128#define Py_UNICODE_TOLOWER(ch) towlower(ch) 129#define Py_UNICODE_TOUPPER(ch) towupper(ch) 130#define Py_UNICODE_TOTITLE(ch) _PyUnicode_ToTitlecase(ch) 131 132#define Py_UNICODE_ISDECIMAL(ch) _PyUnicode_IsDecimalDigit(ch) 133#define Py_UNICODE_ISDIGIT(ch) _PyUnicode_IsDigit(ch) 134#define Py_UNICODE_ISNUMERIC(ch) _PyUnicode_IsNumeric(ch) 135 136#define Py_UNICODE_TODECIMAL(ch) _PyUnicode_ToDecimalDigit(ch) 137#define Py_UNICODE_TODIGIT(ch) _PyUnicode_ToDigit(ch) 138#define Py_UNICODE_TONUMERIC(ch) _PyUnicode_ToNumeric(ch) 139 140#else 141 142#define Py_UNICODE_ISSPACE(ch) _PyUnicode_IsWhitespace(ch) 143 144#define Py_UNICODE_ISLOWER(ch) _PyUnicode_IsLowercase(ch) 145#define Py_UNICODE_ISUPPER(ch) _PyUnicode_IsUppercase(ch) 146#define Py_UNICODE_ISTITLE(ch) _PyUnicode_IsTitlecase(ch) 147#define Py_UNICODE_ISLINEBREAK(ch) _PyUnicode_IsLinebreak(ch) 148 149#define Py_UNICODE_TOLOWER(ch) _PyUnicode_ToLowercase(ch) 150#define Py_UNICODE_TOUPPER(ch) _PyUnicode_ToUppercase(ch) 151#define Py_UNICODE_TOTITLE(ch) _PyUnicode_ToTitlecase(ch) 152 153#define Py_UNICODE_ISDECIMAL(ch) _PyUnicode_IsDecimalDigit(ch) 154#define Py_UNICODE_ISDIGIT(ch) _PyUnicode_IsDigit(ch) 155#define Py_UNICODE_ISNUMERIC(ch) _PyUnicode_IsNumeric(ch) 156 157#define Py_UNICODE_TODECIMAL(ch) _PyUnicode_ToDecimalDigit(ch) 158#define Py_UNICODE_TODIGIT(ch) _PyUnicode_ToDigit(ch) 159#define Py_UNICODE_TONUMERIC(ch) _PyUnicode_ToNumeric(ch) 160 161#endif 162 163#define Py_UNICODE_COPY(target, source, length)\ 164 (memcpy((target), (source), (length)*sizeof(Py_UNICODE))) 165 166#define Py_UNICODE_FILL(target, value, length) do\ 167 {int i; for (i = 0; i < (length); i++) (target)[i] = (value);}\ 168 while (0) 169 170#define Py_UNICODE_MATCH(string, offset, substring)\ 171 (!memcmp((string)->str + (offset), (substring)->str,\ 172 (substring)->length*sizeof(Py_UNICODE))) 173 174#ifdef __cplusplus 175extern "C" { 176#endif 177 178/* --- Unicode Type ------------------------------------------------------- */ 179 180typedef struct { 181 PyObject_HEAD 182 int length; /* Length of raw Unicode data in buffer */ 183 Py_UNICODE *str; /* Raw Unicode buffer */ 184 long hash; /* Hash value; -1 if not set */ 185 PyObject *utf8str; /* UTF-8 encoded version as Python string, 186 or NULL */ 187} PyUnicodeObject; 188 189extern DL_IMPORT(PyTypeObject) PyUnicode_Type; 190 191#define PyUnicode_Check(op) (((op)->ob_type == &PyUnicode_Type)) 192 193/* Fast access macros */ 194#define PyUnicode_GET_SIZE(op) \ 195 (((PyUnicodeObject *)(op))->length) 196#define PyUnicode_GET_DATA_SIZE(op) \ 197 (((PyUnicodeObject *)(op))->length * sizeof(Py_UNICODE)) 198#define PyUnicode_AS_UNICODE(op) \ 199 (((PyUnicodeObject *)(op))->str) 200#define PyUnicode_AS_DATA(op) \ 201 ((const char *)((PyUnicodeObject *)(op))->str) 202 203/* --- Constants ---------------------------------------------------------- */ 204 205/* This Unicode character will be used as replacement character during 206 decoding if the errors argument is set to "replace". Note: the 207 Unicode character U+FFFD is the official REPLACEMENT CHARACTER in 208 Unicode 3.0. */ 209 210#define Py_UNICODE_REPLACEMENT_CHARACTER ((Py_UNICODE) 0xFFFD) 211 212/* === Public API ========================================================= */ 213 214/* --- Plain Py_UNICODE --------------------------------------------------- */ 215 216/* Create a Unicode Object from the Py_UNICODE buffer u of the given 217 size. u may be NULL which causes the contents to be undefined. It 218 is the user's responsibility to fill in the needed data. 219 220 The buffer is copied into the new object. */ 221 222extern DL_IMPORT(PyObject*) PyUnicode_FromUnicode( 223 const Py_UNICODE *u, /* Unicode buffer */ 224 int size /* size of buffer */ 225 ); 226 227/* Return a read-only pointer to the Unicode object's internal 228 Py_UNICODE buffer. */ 229 230extern DL_IMPORT(Py_UNICODE *) PyUnicode_AsUnicode( 231 PyObject *unicode /* Unicode object */ 232 ); 233 234/* Get the length of the Unicode object. */ 235 236extern DL_IMPORT(int) PyUnicode_GetSize( 237 PyObject *unicode /* Unicode object */ 238 ); 239 240/* Coerce obj to an Unicode object and return a reference with 241 *incremented* refcount. 242 243 Coercion is done in the following way: 244 245 1. Unicode objects are passed back as-is with incremented 246 refcount. 247 248 2. String and other char buffer compatible objects are decoded 249 under the assumptions that they contain UTF-8 data. Decoding 250 is done in "strict" mode. 251 252 3. All other objects raise an exception. 253 254 The API returns NULL in case of an error. The caller is responsible 255 for decref'ing the returned objects. 256 257*/ 258 259extern DL_IMPORT(PyObject*) PyUnicode_FromObject( 260 register PyObject *obj /* Object */ 261 ); 262 263/* --- wchar_t support for platforms which support it --------------------- */ 264 265#ifdef HAVE_WCHAR_H 266 267/* Create a Unicode Object from the whcar_t buffer w of the given 268 size. 269 270 The buffer is copied into the new object. */ 271 272extern DL_IMPORT(PyObject*) PyUnicode_FromWideChar( 273 register const wchar_t *w, /* wchar_t buffer */ 274 int size /* size of buffer */ 275 ); 276 277/* Copies the Unicode Object contents into the whcar_t buffer w. At 278 most size wchar_t characters are copied. 279 280 Returns the number of wchar_t characters copied or -1 in case of an 281 error. */ 282 283extern DL_IMPORT(int) PyUnicode_AsWideChar( 284 PyUnicodeObject *unicode, /* Unicode object */ 285 register wchar_t *w, /* wchar_t buffer */ 286 int size /* size of buffer */ 287 ); 288 289#endif 290 291/* === Builtin Codecs ===================================================== 292 293 Many of these APIs take two arguments encoding and errors. These 294 parameters encoding and errors have the same semantics as the ones 295 of the builtin unicode() API. 296 297 Setting encoding to NULL causes the default encoding to be used 298 which is UTF-8. 299 300 Error handling is set by errors which may also be set to NULL 301 meaning to use the default handling defined for the codec. Default 302 error handling for all builtin codecs is "strict" (ValueErrors are 303 raised). 304 305 The codecs all use a similar interface. Only deviation from the 306 generic ones are documented. 307 308*/ 309 310/* --- Generic Codecs ----------------------------------------------------- */ 311 312/* Create a Unicode object by decoding the encoded string s of the 313 given size. */ 314 315extern DL_IMPORT(PyObject*) PyUnicode_Decode( 316 const char *s, /* encoded string */ 317 int size, /* size of buffer */ 318 const char *encoding, /* encoding */ 319 const char *errors /* error handling */ 320 ); 321 322/* Encodes a Py_UNICODE buffer of the given size and returns a 323 Python string object. */ 324 325extern DL_IMPORT(PyObject*) PyUnicode_Encode( 326 const Py_UNICODE *s, /* Unicode char buffer */ 327 int size, /* number of Py_UNICODE chars to encode */ 328 const char *encoding, /* encoding */ 329 const char *errors /* error handling */ 330 ); 331 332/* Encodes a Unicode object and returns the result as Python string 333 object. */ 334 335extern DL_IMPORT(PyObject*) PyUnicode_AsEncodedString( 336 PyObject *unicode, /* Unicode object */ 337 const char *encoding, /* encoding */ 338 const char *errors /* error handling */ 339 ); 340 341/* --- UTF-8 Codecs ------------------------------------------------------- */ 342 343extern DL_IMPORT(PyObject*) PyUnicode_DecodeUTF8( 344 const char *string, /* UTF-8 encoded string */ 345 int length, /* size of string */ 346 const char *errors /* error handling */ 347 ); 348 349extern DL_IMPORT(PyObject*) PyUnicode_AsUTF8String( 350 PyObject *unicode /* Unicode object */ 351 ); 352 353extern DL_IMPORT(PyObject*) PyUnicode_EncodeUTF8( 354 const Py_UNICODE *data, /* Unicode char buffer */ 355 int length, /* number of Py_UNICODE chars to encode */ 356 const char *errors /* error handling */ 357 ); 358 359/* --- UTF-16 Codecs ------------------------------------------------------ */ 360 361/* Decodes length bytes from a UTF-16 encoded buffer string and returns 362 the corresponding Unicode object. 363 364 errors (if non-NULL) defines the error handling. It defaults 365 to "strict". 366 367 If byteorder is non-NULL, the decoder starts decoding using the 368 given byte order: 369 370 *byteorder == -1: little endian 371 *byteorder == 0: native order 372 *byteorder == 1: big endian 373 374 and then switches according to all BOM marks it finds in the input 375 data. BOM marks are not copied into the resulting Unicode string. 376 After completion, *byteorder is set to the current byte order at 377 the end of input data. 378 379 If byteorder is NULL, the codec starts in native order mode. 380 381*/ 382 383extern DL_IMPORT(PyObject*) PyUnicode_DecodeUTF16( 384 const char *string, /* UTF-16 encoded string */ 385 int length, /* size of string */ 386 const char *errors, /* error handling */ 387 int *byteorder /* pointer to byteorder to use 388 0=native;-1=LE,1=BE; updated on 389 exit */ 390 ); 391 392/* Returns a Python string using the UTF-16 encoding in native byte 393 order. The string always starts with a BOM mark. */ 394 395extern DL_IMPORT(PyObject*) PyUnicode_AsUTF16String( 396 PyObject *unicode /* Unicode object */ 397 ); 398 399/* Returns a Python string object holding the UTF-16 encoded value of 400 the Unicode data. 401 402 If byteorder is not 0, output is written according to the following 403 byte order: 404 405 byteorder == -1: little endian 406 byteorder == 0: native byte order (writes a BOM mark) 407 byteorder == 1: big endian 408 409 If byteorder is 0, the output string will always start with the 410 Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is 411 prepended. 412 413 Note that Py_UNICODE data is being interpreted as UTF-16 reduced to 414 UCS-2. This trick makes it possible to add full UTF-16 capabilities 415 at a later point without comprimising the APIs. 416 417*/ 418 419extern DL_IMPORT(PyObject*) PyUnicode_EncodeUTF16( 420 const Py_UNICODE *data, /* Unicode char buffer */ 421 int length, /* number of Py_UNICODE chars to encode */ 422 const char *errors, /* error handling */ 423 int byteorder /* byteorder to use 0=BOM+native;-1=LE,1=BE */ 424 ); 425 426/* --- Unicode-Escape Codecs ---------------------------------------------- */ 427 428extern DL_IMPORT(PyObject*) PyUnicode_DecodeUnicodeEscape( 429 const char *string, /* Unicode-Escape encoded string */ 430 int length, /* size of string */ 431 const char *errors /* error handling */ 432 ); 433 434extern DL_IMPORT(PyObject*) PyUnicode_AsUnicodeEscapeString( 435 PyObject *unicode /* Unicode object */ 436 ); 437 438extern DL_IMPORT(PyObject*) PyUnicode_EncodeUnicodeEscape( 439 const Py_UNICODE *data, /* Unicode char buffer */ 440 int length /* Number of Py_UNICODE chars to encode */ 441 ); 442 443/* --- Raw-Unicode-Escape Codecs ------------------------------------------ */ 444 445extern DL_IMPORT(PyObject*) PyUnicode_DecodeRawUnicodeEscape( 446 const char *string, /* Raw-Unicode-Escape encoded string */ 447 int length, /* size of string */ 448 const char *errors /* error handling */ 449 ); 450 451extern DL_IMPORT(PyObject*) PyUnicode_AsRawUnicodeEscapeString( 452 PyObject *unicode /* Unicode object */ 453 ); 454 455extern DL_IMPORT(PyObject*) PyUnicode_EncodeRawUnicodeEscape( 456 const Py_UNICODE *data, /* Unicode char buffer */ 457 int length /* Number of Py_UNICODE chars to encode */ 458 ); 459 460/* --- Latin-1 Codecs ----------------------------------------------------- 461 462 Note: Latin-1 corresponds to the first 256 Unicode ordinals. 463 464*/ 465 466extern DL_IMPORT(PyObject*) PyUnicode_DecodeLatin1( 467 const char *string, /* Latin-1 encoded string */ 468 int length, /* size of string */ 469 const char *errors /* error handling */ 470 ); 471 472extern DL_IMPORT(PyObject*) PyUnicode_AsLatin1String( 473 PyObject *unicode /* Unicode object */ 474 ); 475 476extern DL_IMPORT(PyObject*) PyUnicode_EncodeLatin1( 477 const Py_UNICODE *data, /* Unicode char buffer */ 478 int length, /* Number of Py_UNICODE chars to encode */ 479 const char *errors /* error handling */ 480 ); 481 482/* --- ASCII Codecs ------------------------------------------------------- 483 484 Only 7-bit ASCII data is excepted. All other codes generate errors. 485 486*/ 487 488extern DL_IMPORT(PyObject*) PyUnicode_DecodeASCII( 489 const char *string, /* ASCII encoded string */ 490 int length, /* size of string */ 491 const char *errors /* error handling */ 492 ); 493 494extern DL_IMPORT(PyObject*) PyUnicode_AsASCIIString( 495 PyObject *unicode /* Unicode object */ 496 ); 497 498extern DL_IMPORT(PyObject*) PyUnicode_EncodeASCII( 499 const Py_UNICODE *data, /* Unicode char buffer */ 500 int length, /* Number of Py_UNICODE chars to encode */ 501 const char *errors /* error handling */ 502 ); 503 504/* --- Character Map Codecs ----------------------------------------------- 505 506 This codec uses mappings to encode and decode characters. 507 508 Decoding mappings must map single string characters to single 509 Unicode characters, integers (which are then interpreted as Unicode 510 ordinals) or None (meaning "undefined mapping" and causing an 511 error). 512 513 Encoding mappings must map single Unicode characters to single 514 string characters, integers (which are then interpreted as Latin-1 515 ordinals) or None (meaning "undefined mapping" and causing an 516 error). 517 518 If a character lookup fails with a LookupError, the character is 519 copied as-is meaning that its ordinal value will be interpreted as 520 Unicode or Latin-1 ordinal resp. Because of this mappings only need 521 to contain those mappings which map characters to different code 522 points. 523 524*/ 525 526extern DL_IMPORT(PyObject*) PyUnicode_DecodeCharmap( 527 const char *string, /* Encoded string */ 528 int length, /* size of string */ 529 PyObject *mapping, /* character mapping 530 (char ordinal -> unicode ordinal) */ 531 const char *errors /* error handling */ 532 ); 533 534extern DL_IMPORT(PyObject*) PyUnicode_AsCharmapString( 535 PyObject *unicode, /* Unicode object */ 536 PyObject *mapping /* character mapping 537 (unicode ordinal -> char ordinal) */ 538 ); 539 540extern DL_IMPORT(PyObject*) PyUnicode_EncodeCharmap( 541 const Py_UNICODE *data, /* Unicode char buffer */ 542 int length, /* Number of Py_UNICODE chars to encode */ 543 PyObject *mapping, /* character mapping 544 (unicode ordinal -> char ordinal) */ 545 const char *errors /* error handling */ 546 ); 547 548/* Translate a Py_UNICODE buffer of the given length by applying a 549 character mapping table to it and return the resulting Unicode 550 object. 551 552 The mapping table must map Unicode ordinal integers to Unicode 553 ordinal integers or None (causing deletion of the character). 554 555 Mapping tables may be dictionaries or sequences. Unmapped character 556 ordinals (ones which cause a LookupError) are left untouched and 557 are copied as-is. 558 559*/ 560 561extern DL_IMPORT(PyObject *) PyUnicode_TranslateCharmap( 562 const Py_UNICODE *data, /* Unicode char buffer */ 563 int length, /* Number of Py_UNICODE chars to encode */ 564 PyObject *table, /* Translate table */ 565 const char *errors /* error handling */ 566 ); 567 568#ifdef MS_WIN32 569 570/* --- MBCS codecs for Windows -------------------------------------------- */ 571 572extern DL_IMPORT(PyObject*) PyUnicode_DecodeMBCS( 573 const char *string, /* MBCS encoded string */ 574 int length, /* size of string */ 575 const char *errors /* error handling */ 576 ); 577 578extern DL_IMPORT(PyObject*) PyUnicode_AsMBCSString( 579 PyObject *unicode /* Unicode object */ 580 ); 581 582extern DL_IMPORT(PyObject*) PyUnicode_EncodeMBCS( 583 const Py_UNICODE *data, /* Unicode char buffer */ 584 int length, /* Number of Py_UNICODE chars to encode */ 585 const char *errors /* error handling */ 586 ); 587 588#endif /* MS_WIN32 */ 589 590/* --- Decimal Encoder ---------------------------------------------------- */ 591 592/* Takes a Unicode string holding a decimal value and writes it into 593 an output buffer using standard ASCII digit codes. 594 595 The output buffer has to provide at least length+1 bytes of storage 596 area. The output string is 0-terminated. 597 598 The encoder converts whitespace to ' ', decimal characters to their 599 corresponding ASCII digit and all other Latin-1 characters except 600 \0 as-is. Characters outside this range (Unicode ordinals 1-256) 601 are treated as errors. This includes embedded NULL bytes. 602 603 Error handling is defined by the errors argument: 604 605 NULL or "strict": raise a ValueError 606 "ignore": ignore the wrong characters (these are not copied to the 607 output buffer) 608 "replace": replaces illegal characters with '?' 609 610 Returns 0 on success, -1 on failure. 611 612*/ 613 614extern DL_IMPORT(int) PyUnicode_EncodeDecimal( 615 Py_UNICODE *s, /* Unicode buffer */ 616 int length, /* Number of Py_UNICODE chars to encode */ 617 char *output, /* Output buffer; must have size >= length */ 618 const char *errors /* error handling */ 619 ); 620 621/* --- Methods & Slots ---------------------------------------------------- 622 623 These are capable of handling Unicode objects and strings on input 624 (we refer to them as strings in the descriptions) and return 625 Unicode objects or integers as apporpriate. */ 626 627/* Concat two strings giving a new Unicode string. */ 628 629extern DL_IMPORT(PyObject*) PyUnicode_Concat( 630 PyObject *left, /* Left string */ 631 PyObject *right /* Right string */ 632 ); 633 634/* Split a string giving a list of Unicode strings. 635 636 If sep is NULL, splitting will be done at all whitespace 637 substrings. Otherwise, splits occur at the given separator. 638 639 At most maxsplit splits will be done. If negative, no limit is set. 640 641 Separators are not included in the resulting list. 642 643*/ 644 645extern DL_IMPORT(PyObject*) PyUnicode_Split( 646 PyObject *s, /* String to split */ 647 PyObject *sep, /* String separator */ 648 int maxsplit /* Maxsplit count */ 649 ); 650 651/* Dito, but split at line breaks. 652 653 CRLF is considered to be one line break. Line breaks are not 654 included in the resulting list. */ 655 656extern DL_IMPORT(PyObject*) PyUnicode_Splitlines( 657 PyObject *s, /* String to split */ 658 int maxsplit /* Maxsplit count */ 659 ); 660 661/* Translate a string by applying a character mapping table to it and 662 return the resulting Unicode object. 663 664 The mapping table must map Unicode ordinal integers to Unicode 665 ordinal integers or None (causing deletion of the character). 666 667 Mapping tables may be dictionaries or sequences. Unmapped character 668 ordinals (ones which cause a LookupError) are left untouched and 669 are copied as-is. 670 671*/ 672 673extern DL_IMPORT(PyObject *) PyUnicode_Translate( 674 PyObject *str, /* String */ 675 PyObject *table, /* Translate table */ 676 const char *errors /* error handling */ 677 ); 678 679/* Join a sequence of strings using the given separator and return 680 the resulting Unicode string. */ 681 682extern DL_IMPORT(PyObject*) PyUnicode_Join( 683 PyObject *separator, /* Separator string */ 684 PyObject *seq /* Sequence object */ 685 ); 686 687/* Return 1 if substr matches str[start:end] at the given tail end, 0 688 otherwise. */ 689 690extern DL_IMPORT(int) PyUnicode_Tailmatch( 691 PyObject *str, /* String */ 692 PyObject *substr, /* Prefix or Suffix string */ 693 int start, /* Start index */ 694 int end, /* Stop index */ 695 int direction /* Tail end: -1 prefix, +1 suffix */ 696 ); 697 698/* Return the first position of substr in str[start:end] using the 699 given search direction or -1 if not found. */ 700 701extern DL_IMPORT(int) PyUnicode_Find( 702 PyObject *str, /* String */ 703 PyObject *substr, /* Substring to find */ 704 int start, /* Start index */ 705 int end, /* Stop index */ 706 int direction /* Find direction: +1 forward, -1 backward */ 707 ); 708 709/* Count the number of occurrences of substr in str[start:end]. */ 710 711extern DL_IMPORT(int) PyUnicode_Count( 712 PyObject *str, /* String */ 713 PyObject *substr, /* Substring to count */ 714 int start, /* Start index */ 715 int end /* Stop index */ 716 ); 717 718/* Replace at most maxcount occurrences of substr in str with replstr 719 and return the resulting Unicode object. */ 720 721extern DL_IMPORT(PyObject *) PyUnicode_Replace( 722 PyObject *str, /* String */ 723 PyObject *substr, /* Substring to find */ 724 PyObject *replstr, /* Substring to replace */ 725 int maxcount /* Max. number of replacements to apply; 726 -1 = all */ 727 ); 728 729/* Compare two strings and return -1, 0, 1 for less than, equal, 730 greater than resp. */ 731 732extern DL_IMPORT(int) PyUnicode_Compare( 733 PyObject *left, /* Left string */ 734 PyObject *right /* Right string */ 735 ); 736 737/* Apply a argument tuple or dictionar to a format string and return 738 the resulting Unicode string. */ 739 740extern DL_IMPORT(PyObject *) PyUnicode_Format( 741 PyObject *format, /* Format string */ 742 PyObject *args /* Argument tuple or dictionary */ 743 ); 744 745/* Checks whether element is contained in container and return 1/0 746 accordingly. 747 748 element has to coerce to an one element Unicode string. -1 is 749 returned in case of an error. */ 750 751extern DL_IMPORT(int) PyUnicode_Contains( 752 PyObject *container, /* Container string */ 753 PyObject *element /* Element string */ 754 ); 755 756/* === Characters Type APIs =============================================== */ 757 758/* These should not be used directly. Use the Py_UNICODE_IS* and 759 Py_UNICODE_TO* macros instead. 760 761 These APIs are implemented in Objects/unicodectype.c. 762 763*/ 764 765extern DL_IMPORT(int) _PyUnicode_IsLowercase( 766 register const Py_UNICODE ch /* Unicode character */ 767 ); 768 769extern DL_IMPORT(int) _PyUnicode_IsUppercase( 770 register const Py_UNICODE ch /* Unicode character */ 771 ); 772 773extern DL_IMPORT(int) _PyUnicode_IsTitlecase( 774 register const Py_UNICODE ch /* Unicode character */ 775 ); 776 777extern DL_IMPORT(int) _PyUnicode_IsWhitespace( 778 register const Py_UNICODE ch /* Unicode character */ 779 ); 780 781extern DL_IMPORT(int) _PyUnicode_IsLinebreak( 782 register const Py_UNICODE ch /* Unicode character */ 783 ); 784 785extern DL_IMPORT(Py_UNICODE) _PyUnicode_ToLowercase( 786 register const Py_UNICODE ch /* Unicode character */ 787 ); 788 789extern DL_IMPORT(Py_UNICODE) _PyUnicode_ToUppercase( 790 register const Py_UNICODE ch /* Unicode character */ 791 ); 792 793extern DL_IMPORT(Py_UNICODE) _PyUnicode_ToTitlecase( 794 register const Py_UNICODE ch /* Unicode character */ 795 ); 796 797extern DL_IMPORT(int) _PyUnicode_ToDecimalDigit( 798 register const Py_UNICODE ch /* Unicode character */ 799 ); 800 801extern DL_IMPORT(int) _PyUnicode_ToDigit( 802 register const Py_UNICODE ch /* Unicode character */ 803 ); 804 805extern DL_IMPORT(double) _PyUnicode_ToNumeric( 806 register const Py_UNICODE ch /* Unicode character */ 807 ); 808 809extern DL_IMPORT(int) _PyUnicode_IsDecimalDigit( 810 register const Py_UNICODE ch /* Unicode character */ 811 ); 812 813extern DL_IMPORT(int) _PyUnicode_IsDigit( 814 register const Py_UNICODE ch /* Unicode character */ 815 ); 816 817extern DL_IMPORT(int) _PyUnicode_IsNumeric( 818 register const Py_UNICODE ch /* Unicode character */ 819 ); 820 821#ifdef __cplusplus 822} 823#endif 824#endif /* !Py_UNICODEOBJECT_H */ 825