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