cpython-lru_cache-weakref: Doc/c-api/unicode.rst annotate

annotate Doc/c-api/unicode.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	817d8b28cd6b
children	66de7111230a

rev	line source
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	3 .. _unicodeobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	5 Unicode Objects and Codecs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	6 --------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	7
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	9
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	10 Unicode Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	11 ^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	12
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	13
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	14 These are the basic Unicode object types used for the Unicode implementation in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	15 Python:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	16
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	17 .. % --- Unicode Type -------------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	18
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	19
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	20 .. ctype:: Py_UNICODE
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	21
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	22 This type represents the storage type which is used by Python internally as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	23 basis for holding Unicode ordinals. Python's default builds use a 16-bit type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	24 for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	25 possible to build a UCS4 version of Python (most recent Linux distributions come
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	26 with UCS4 builds of Python). These builds then use a 32-bit type for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	27 :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	28 where :ctype:`wchar_t` is available and compatible with the chosen Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	29 Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	30 :ctype:`wchar_t` to enhance native platform compatibility. On all other
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	31 platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	32 short` (UCS2) or :ctype:`unsigned long` (UCS4).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	33
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	34 Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	35 this in mind when writing extensions or interfaces.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	36
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	37
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	38 .. ctype:: PyUnicodeObject
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	39
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	40 This subtype of :ctype:`PyObject` represents a Python Unicode object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	41
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	42
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	43 .. cvar:: PyTypeObject PyUnicode_Type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	44
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	45 This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	46 is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	47
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	48 The following APIs are really C macros and can be used to do fast checks and to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	49 access internal read-only data of Unicode objects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	50
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	51
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	52 .. cfunction:: int PyUnicode_Check(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	53
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	54 Return true if the object o is a Unicode object or an instance of a Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	55 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	56
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	57 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	58 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	59
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	60
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	61 .. cfunction:: int PyUnicode_CheckExact(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	62
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	63 Return true if the object o is a Unicode object, but not an instance of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	64 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	65
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	66 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	67
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	68
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	69 .. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	70
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	71 Return the size of the object. o has to be a :ctype:`PyUnicodeObject` (not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	72 checked).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	73
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	74 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	75 This function returned an :ctype:`int` type. This might require changes
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	76 in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	77
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	78
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	79 .. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	80
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	81 Return the size of the object's internal buffer in bytes. o has to be a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	82 :ctype:`PyUnicodeObject` (not checked).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	83
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	84 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	85 This function returned an :ctype:`int` type. This might require changes
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	86 in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	87
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	88
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	89 .. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	90
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	91 Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. o
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	92 has to be a :ctype:`PyUnicodeObject` (not checked).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	93
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	94
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	95 .. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	96
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	97 Return a pointer to the internal buffer of the object. o has to be a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	98 :ctype:`PyUnicodeObject` (not checked).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	99
45341 65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	100
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	101 .. cfunction:: int PyUnicode_ClearFreeList(void)
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	102
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	103 Clear the free list. Return the total number of freed items.
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	104
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	105 .. versionadded:: 2.6
65ae68c7aca3 Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. Christian Heimes <christian@cheimes.de> parents: 44796 diff changeset	106
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	107 Unicode provides many different character properties. The most often needed ones
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	108 are available through these macros which are mapped to C functions depending on
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	109 the Python configuration.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	110
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	111 .. % --- Unicode character properties ---------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	112
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	113
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	114 .. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	115
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	116 Return 1 or 0 depending on whether ch is a whitespace character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	117
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	118
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	119 .. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	120
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	121 Return 1 or 0 depending on whether ch is a lowercase character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	122
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	123
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	124 .. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	125
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	126 Return 1 or 0 depending on whether ch is an uppercase character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	127
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	128
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	129 .. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	130
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	131 Return 1 or 0 depending on whether ch is a titlecase character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	132
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	133
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	134 .. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	135
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	136 Return 1 or 0 depending on whether ch is a linebreak character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	137
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	138
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	139 .. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	140
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	141 Return 1 or 0 depending on whether ch is a decimal character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	142
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	143
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	144 .. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	145
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	146 Return 1 or 0 depending on whether ch is a digit character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	147
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	148
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	149 .. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	150
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	151 Return 1 or 0 depending on whether ch is a numeric character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	152
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	153
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	154 .. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	155
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	156 Return 1 or 0 depending on whether ch is an alphabetic character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	157
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	158
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	159 .. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	160
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	161 Return 1 or 0 depending on whether ch is an alphanumeric character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	162
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	163 These APIs can be used for fast direct character conversions:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	164
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	165
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	166 .. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	167
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	168 Return the character ch converted to lower case.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	169
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	170
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	171 .. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	172
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	173 Return the character ch converted to upper case.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	174
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	175
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	176 .. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	177
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	178 Return the character ch converted to title case.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	179
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	180
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	181 .. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	182
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	183 Return the character ch converted to a decimal positive integer. Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	184 ``-1`` if this is not possible. This macro does not raise exceptions.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	185
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	186
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	187 .. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	188
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	189 Return the character ch converted to a single digit integer. Return ``-1`` if
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	190 this is not possible. This macro does not raise exceptions.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	191
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	192
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	193 .. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	194
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	195 Return the character ch converted to a double. Return ``-1.0`` if this is not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	196 possible. This macro does not raise exceptions.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	197
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	198 To create Unicode objects and access their basic sequence properties, use these
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	199 APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	200
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	201 .. % --- Plain Py_UNICODE ---------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	202
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	203
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	204 .. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	205
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	206 Create a Unicode Object from the Py_UNICODE buffer u of the given size. u
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	207 may be NULL which causes the contents to be undefined. It is the user's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	208 responsibility to fill in the needed data. The buffer is copied into the new
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	209 object. If the buffer is not NULL, the return value might be a shared object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	210 Therefore, modification of the resulting Unicode object is only allowed when u
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	211 is NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	212
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	213 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	214 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	215 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	216
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	217
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	218 .. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	219
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	220 Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	221 buffer, NULL if unicode is not a Unicode object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	222
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	223
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	224 .. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	225
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	226 Return the length of the Unicode object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	227
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	228 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	229 This function returned an :ctype:`int` type. This might require changes
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	230 in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	231
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	232
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	233 .. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject obj, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	234
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	235 Coerce an encoded object obj to an Unicode object and return a reference with
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	236 incremented refcount.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	237
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	238 String and other char buffer compatible objects are decoded according to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	239 given encoding and using the error handling defined by errors. Both can be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	240 NULL to have the interface use the default values (see the next section for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	241 details).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	242
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	243 All other objects, including Unicode objects, cause a :exc:`TypeError` to be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	244 set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	245
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	246 The API returns NULL if there was an error. The caller is responsible for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	247 decref'ing the returned objects.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	248
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	249
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	250 .. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	251
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	252 Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	253 throughout the interpreter whenever coercion to Unicode is needed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	254
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	255 If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	256 Python can interface directly to this type using the following functions.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	257 Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	258 the system's :ctype:`wchar_t`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	259
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	260 .. % --- wchar_t support for platforms which support it ---------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	261
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	262
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	263 .. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	264
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	265 Create a Unicode object from the :ctype:`wchar_t` buffer w of the given size.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	266 Return NULL on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	267
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	268 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	269 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	270 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	271
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	272
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	273 .. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject unicode, wchar_t w, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	274
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	275 Copy the Unicode object contents into the :ctype:`wchar_t` buffer w. At most
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	276 size :ctype:`wchar_t` characters are copied (excluding a possibly trailing
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	277 0-termination character). Return the number of :ctype:`wchar_t` characters
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	278 copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	279 string may or may not be 0-terminated. It is the responsibility of the caller
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	280 to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	281 required by the application.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	282
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	283 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	284 This function returned an :ctype:`int` type and used an :ctype:`int`
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	285 type for size. This might require changes in your code for properly
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	286 supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	287
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	288
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	289 .. _builtincodecs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	290
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	291 Built-in Codecs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	292 ^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	293
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	294 Python provides a set of builtin codecs which are written in C for speed. All of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	295 these codecs are directly usable via the following functions.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	296
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	297 Many of the following APIs take two arguments encoding and errors. These
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	298 parameters encoding and errors have the same semantics as the ones of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	299 builtin unicode() Unicode object constructor.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	300
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	301 Setting encoding to NULL causes the default encoding to be used which is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	302 ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	303 as the encoding for file names. This variable should be treated as read-only: On
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	304 some systems, it will be a pointer to a static string, on others, it will change
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	305 at run-time (such as when the application invokes setlocale).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	306
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	307 Error handling is set by errors which may also be set to NULL meaning to use
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	308 the default handling defined for the codec. Default error handling for all
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	309 builtin codecs is "strict" (:exc:`ValueError` is raised).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	310
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	311 The codecs all use a similar interface. Only deviation from the following
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	312 generic ones are documented for simplicity.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	313
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	314 These are the generic codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	315
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	316 .. % --- Generic Codecs -----------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	317
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	318
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	319 .. cfunction:: PyObject* PyUnicode_Decode(const char s, Py_ssize_t size, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	320
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	321 Create a Unicode object by decoding size bytes of the encoded string s.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	322 encoding and errors have the same meaning as the parameters of the same name
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	323 in the :func:`unicode` builtin function. The codec to be used is looked up
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	324 using the Python codec registry. Return NULL if an exception was raised by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	325 the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	326
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	327 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	328 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	329 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	330
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	331
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	332 .. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE s, Py_ssize_t size, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	333
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	334 Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	335 string object. encoding and errors have the same meaning as the parameters
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	336 of the same name in the Unicode :meth:`encode` method. The codec to be used is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	337 looked up using the Python codec registry. Return NULL if an exception was
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	338 raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	339
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	340 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	341 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	342 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	343
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	344
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	345 .. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject unicode, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	346
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	347 Encode a Unicode object and return the result as Python string object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	348 encoding and errors have the same meaning as the parameters of the same name
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	349 in the Unicode :meth:`encode` method. The codec to be used is looked up using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	350 the Python codec registry. Return NULL if an exception was raised by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	351 codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	352
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	353 These are the UTF-8 codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	354
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	355 .. % --- UTF-8 Codecs -------------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	356
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	357
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	358 .. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	359
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	360 Create a Unicode object by decoding size bytes of the UTF-8 encoded string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	361 s. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	362
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	363 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	364 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	365 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	366
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	367
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	368 .. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char s, Py_ssize_t size, const char errors, Py_ssize_t *consumed)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	369
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	370 If consumed is NULL, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	371 consumed is not NULL, trailing incomplete UTF-8 byte sequences will not be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	372 treated as an error. Those bytes will not be decoded and the number of bytes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	373 that have been decoded will be stored in consumed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	374
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	375 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	376
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	377 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	378 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	379 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	380
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	381
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	382 .. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	383
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	384 Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	385 Python string object. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	386
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	387 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	388 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	389 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	390
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	391
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	392 .. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	393
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	394 Encode a Unicode object using UTF-8 and return the result as Python string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	395 object. Error handling is "strict". Return NULL if an exception was raised
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	396 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	397
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	398 These are the UTF-32 codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	399
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	400 .. % --- UTF-32 Codecs ------------------------------------------------------ */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	401
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	402
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	403 .. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char s, Py_ssize_t size, const char errors, int *byteorder)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	404
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	405 Decode length bytes from a UTF-32 encoded buffer string and return the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	406 corresponding Unicode object. errors (if non-NULL) defines the error
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	407 handling. It defaults to "strict".
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	408
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	409 If byteorder is non-NULL, the decoder starts decoding using the given byte
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	410 order::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	411
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	412 *byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	413 *byteorder == 0: native order
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	414 *byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	415
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	416 and then switches if the first four bytes of the input data are a byte order mark
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	417 (BOM) and the specified byte order is native order. This BOM is not copied into
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	418 the resulting Unicode string. After completion, \byteorder* is set to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	419 current byte order at the end of input data.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	420
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	421 In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	422
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	423 If byteorder is NULL, the codec starts in native order mode.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	424
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	425 Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	426
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	427 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	428
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	429
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	430 .. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char s, Py_ssize_t size, const char errors, int byteorder, Py_ssize_t consumed)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	431
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	432 If consumed is NULL, behave like :cfunc:`PyUnicode_DecodeUTF32`. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	433 consumed is not NULL, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	434 trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	435 by four) as an error. Those bytes will not be decoded and the number of bytes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	436 that have been decoded will be stored in consumed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	437
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	438 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	439
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	440
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	441 .. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE s, Py_ssize_t size, const char errors, int byteorder)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	442
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	443 Return a Python bytes object holding the UTF-32 encoded value of the Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	444 data in s. If byteorder is not ``0``, output is written according to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	445 following byte order::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	446
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	447 byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	448 byteorder == 0: native byte order (writes a BOM mark)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	449 byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	450
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	451 If byteorder is ``0``, the output string will always start with the Unicode BOM
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	452 mark (U+FEFF). In the other two modes, no BOM mark is prepended.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	453
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	454 If Py_UNICODE_WIDE is not defined, surrogate pairs will be output
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	455 as a single codepoint.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	456
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	457 Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	458
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	459 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	460
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	461
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	462 .. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	463
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	464 Return a Python string using the UTF-32 encoding in native byte order. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	465 string always starts with a BOM mark. Error handling is "strict". Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	466 NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	467
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	468 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	469
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	470
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	471 These are the UTF-16 codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	472
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	473 .. % --- UTF-16 Codecs ------------------------------------------------------ */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	474
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	475
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	476 .. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char s, Py_ssize_t size, const char errors, int *byteorder)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	477
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	478 Decode length bytes from a UTF-16 encoded buffer string and return the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	479 corresponding Unicode object. errors (if non-NULL) defines the error
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	480 handling. It defaults to "strict".
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	481
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	482 If byteorder is non-NULL, the decoder starts decoding using the given byte
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	483 order::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	484
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	485 *byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	486 *byteorder == 0: native order
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	487 *byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	488
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	489 and then switches if the first two bytes of the input data are a byte order mark
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	490 (BOM) and the specified byte order is native order. This BOM is not copied into
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	491 the resulting Unicode string. After completion, \byteorder* is set to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	492 current byte order at the.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	493
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	494 If byteorder is NULL, the codec starts in native order mode.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	495
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	496 Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	497
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	498 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	499 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	500 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	501
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	502
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	503 .. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char s, Py_ssize_t size, const char errors, int byteorder, Py_ssize_t consumed)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	504
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	505 If consumed is NULL, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	506 consumed is not NULL, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	507 trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	508 split surrogate pair) as an error. Those bytes will not be decoded and the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	509 number of bytes that have been decoded will be stored in consumed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	510
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	511 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	512
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	513 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	514 This function used an :ctype:`int` type for size and an :ctype:`int *`
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	515 type for consumed. This might require changes in your code for
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	516 properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	517
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	518
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	519 .. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE s, Py_ssize_t size, const char errors, int byteorder)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	520
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	521 Return a Python string object holding the UTF-16 encoded value of the Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	522 data in s. If byteorder is not ``0``, output is written according to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	523 following byte order::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	524
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	525 byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	526 byteorder == 0: native byte order (writes a BOM mark)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	527 byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	528
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	529 If byteorder is ``0``, the output string will always start with the Unicode BOM
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	530 mark (U+FEFF). In the other two modes, no BOM mark is prepended.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	531
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	532 If Py_UNICODE_WIDE is defined, a single :ctype:`Py_UNICODE` value may get
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	533 represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	534 values is interpreted as an UCS-2 character.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	535
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	536 Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	537
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	538 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	539 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	540 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	541
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	542
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	543 .. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	544
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	545 Return a Python string using the UTF-16 encoding in native byte order. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	546 string always starts with a BOM mark. Error handling is "strict". Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	547 NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	548
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	549 These are the "Unicode Escape" codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	550
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	551 .. % --- Unicode-Escape Codecs ----------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	552
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	553
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	554 .. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	555
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	556 Create a Unicode object by decoding size bytes of the Unicode-Escape encoded
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	557 string s. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	558
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	559 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	560 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	561 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	562
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	563
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	564 .. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	565
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	566 Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	567 return a Python string object. Return NULL if an exception was raised by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	568 codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	569
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	570 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	571 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	572 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	573
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	574
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	575 .. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	576
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	577 Encode a Unicode object using Unicode-Escape and return the result as Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	578 string object. Error handling is "strict". Return NULL if an exception was
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	579 raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	580
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	581 These are the "Raw Unicode Escape" codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	582
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	583 .. % --- Raw-Unicode-Escape Codecs ------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	584
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	585
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	586 .. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	587
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	588 Create a Unicode object by decoding size bytes of the Raw-Unicode-Escape
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	589 encoded string s. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	590
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	591 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	592 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	593 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	594
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	595
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	596 .. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	597
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	598 Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	599 and return a Python string object. Return NULL if an exception was raised by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	600 the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	601
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	602 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	603 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	604 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	605
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	606
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	607 .. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	608
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	609 Encode a Unicode object using Raw-Unicode-Escape and return the result as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	610 Python string object. Error handling is "strict". Return NULL if an exception
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	611 was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	612
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	613 These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	614 ordinals and only these are accepted by the codecs during encoding.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	615
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	616 .. % --- Latin-1 Codecs -----------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	617
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	618
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	619 .. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	620
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	621 Create a Unicode object by decoding size bytes of the Latin-1 encoded string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	622 s. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	623
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	624 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	625 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	626 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	627
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	628
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	629 .. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	630
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	631 Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	632 a Python string object. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	633
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	634 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	635 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	636 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	637
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	638
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	639 .. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	640
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	641 Encode a Unicode object using Latin-1 and return the result as Python string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	642 object. Error handling is "strict". Return NULL if an exception was raised
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	643 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	644
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	645 These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	646 codes generate errors.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	647
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	648 .. % --- ASCII Codecs -------------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	649
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	650
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	651 .. cfunction:: PyObject* PyUnicode_DecodeASCII(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	652
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	653 Create a Unicode object by decoding size bytes of the ASCII encoded string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	654 s. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	655
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	656 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	657 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	658 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	659
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	660
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	661 .. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	662
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	663 Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	664 Python string object. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	665
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	666 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	667 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	668 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	669
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	670
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	671 .. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	672
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	673 Encode a Unicode object using ASCII and return the result as Python string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	674 object. Error handling is "strict". Return NULL if an exception was raised
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	675 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	676
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	677 These are the mapping codec APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	678
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	679 .. % --- Character Map Codecs -----------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	680
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	681 This codec is special in that it can be used to implement many different codecs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	682 (and this is in fact what was done to obtain most of the standard codecs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	683 included in the :mod:`encodings` package). The codec uses mapping to encode and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	684 decode characters.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	685
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	686 Decoding mappings must map single string characters to single Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	687 characters, integers (which are then interpreted as Unicode ordinals) or None
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	688 (meaning "undefined mapping" and causing an error).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	689
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	690 Encoding mappings must map single Unicode characters to single string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	691 characters, integers (which are then interpreted as Latin-1 ordinals) or None
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	692 (meaning "undefined mapping" and causing an error).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	693
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	694 The mapping objects provided must only support the __getitem__ mapping
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	695 interface.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	696
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	697 If a character lookup fails with a LookupError, the character is copied as-is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	698 meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	699 resp. Because of this, mappings only need to contain those mappings which map
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	700 characters to different code points.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	701
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	702
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	703 .. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char s, Py_ssize_t size, PyObject mapping, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	704
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	705 Create a Unicode object by decoding size bytes of the encoded string s using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	706 the given mapping object. Return NULL if an exception was raised by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	707 codec. If mapping is NULL latin-1 decoding will be done. Else it can be a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	708 dictionary mapping byte or a unicode string, which is treated as a lookup table.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	709 Byte values greater that the length of the string and U+FFFE "characters" are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	710 treated as "undefined mapping".
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	711
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	712 .. versionchanged:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	713 Allowed unicode string as mapping argument.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	714
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	715 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	716 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	717 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	718
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	719
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	720 .. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE s, Py_ssize_t size, PyObject mapping, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	721
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	722 Encode the :ctype:`Py_UNICODE` buffer of the given size using the given
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	723 mapping object and return a Python string object. Return NULL if an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	724 exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	725
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	726 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	727 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	728 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	729
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	730
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	731 .. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject unicode, PyObject mapping)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	732
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	733 Encode a Unicode object using the given mapping object and return the result
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	734 as Python string object. Error handling is "strict". Return NULL if an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	735 exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	736
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	737 The following codec API is special in that maps Unicode to Unicode.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	738
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	739
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	740 .. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE s, Py_ssize_t size, PyObject table, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	741
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	742 Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	743 character mapping table to it and return the resulting Unicode object. Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	744 NULL when an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	745
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	746 The mapping table must map Unicode ordinal integers to Unicode ordinal
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	747 integers or None (causing deletion of the character).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	748
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	749 Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	750 and sequences work well. Unmapped character ordinals (ones which cause a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	751 :exc:`LookupError`) are left untouched and are copied as-is.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	752
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	753 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	754 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	755 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	756
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	757 These are the MBCS codec APIs. They are currently only available on Windows and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	758 use the Win32 MBCS converters to implement the conversions. Note that MBCS (or
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	759 DBCS) is a class of encodings, not just one. The target encoding is defined by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	760 the user settings on the machine running the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	761
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	762 .. % --- MBCS codecs for Windows --------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	763
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	764
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	765 .. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	766
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	767 Create a Unicode object by decoding size bytes of the MBCS encoded string s.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	768 Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	769
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	770 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	771 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	772 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	773
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	774
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	775 .. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char s, int size, const char errors, int *consumed)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	776
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	777 If consumed is NULL, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	778 consumed is not NULL, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	779 trailing lead byte and the number of bytes that have been decoded will be stored
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	780 in consumed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	781
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	782 .. versionadded:: 2.5
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	783
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	784
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	785 .. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE s, Py_ssize_t size, const char errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	786
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	787 Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	788 Python string object. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	789
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	790 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	791 This function used an :ctype:`int` type for size. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	792 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	793
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	794
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	795 .. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	796
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	797 Encode a Unicode object using MBCS and return the result as Python string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	798 object. Error handling is "strict". Return NULL if an exception was raised
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	799 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	800
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	801 .. % --- Methods & Slots ----------------------------------------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	802
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	803
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	804 .. _unicodemethodsandslots:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	805
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	806 Methods and Slot Functions
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	807 ^^^^^^^^^^^^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	808
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	809 The following APIs are capable of handling Unicode objects and strings on input
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	810 (we refer to them as strings in the descriptions) and return Unicode objects or
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	811 integers as appropriate.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	812
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	813 They all return NULL or ``-1`` if an exception occurs.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	814
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	815
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	816 .. cfunction:: PyObject* PyUnicode_Concat(PyObject left, PyObject right)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	817
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	818 Concat two strings giving a new Unicode string.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	819
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	820
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	821 .. cfunction:: PyObject* PyUnicode_Split(PyObject s, PyObject sep, Py_ssize_t maxsplit)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	822
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	823 Split a string giving a list of Unicode strings. If sep is NULL, splitting
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	824 will be done at all whitespace substrings. Otherwise, splits occur at the given
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	825 separator. At most maxsplit splits will be done. If negative, no limit is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	826 set. Separators are not included in the resulting list.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	827
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	828 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	829 This function used an :ctype:`int` type for maxsplit. This might require
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	830 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	831
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	832
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	833 .. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	834
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	835 Split a Unicode string at line breaks, returning a list of Unicode strings.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	836 CRLF is considered to be one line break. If keepend is 0, the Line break
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	837 characters are not included in the resulting strings.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	838
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	839
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	840 .. cfunction:: PyObject* PyUnicode_Translate(PyObject str, PyObject table, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	841
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	842 Translate a string by applying a character mapping table to it and return the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	843 resulting Unicode object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	844
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	845 The mapping table must map Unicode ordinal integers to Unicode ordinal integers
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	846 or None (causing deletion of the character).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	847
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	848 Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	849 and sequences work well. Unmapped character ordinals (ones which cause a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	850 :exc:`LookupError`) are left untouched and are copied as-is.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	851
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	852 errors has the usual meaning for codecs. It may be NULL which indicates to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	853 use the default error handling.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	854
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	855
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	856 .. cfunction:: PyObject* PyUnicode_Join(PyObject separator, PyObject seq)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	857
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	858 Join a sequence of strings using the given separator and return the resulting
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	859 Unicode string.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	860
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	861
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	862 .. cfunction:: int PyUnicode_Tailmatch(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end, int direction)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	863
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	864 Return 1 if substr matches str[start:end] at the given tail end
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	865 (direction == -1 means to do a prefix match, direction == 1 a suffix match),
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	866 0 otherwise. Return ``-1`` if an error occurred.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	867
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	868 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	869 This function used an :ctype:`int` type for start and end. This
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	870 might require changes in your code for properly supporting 64-bit
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	871 systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	872
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	873
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	874 .. cfunction:: Py_ssize_t PyUnicode_Find(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end, int direction)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	875
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	876 Return the first position of substr in str[start:end] using the given
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	877 direction (direction == 1 means to do a forward search, direction == -1 a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	878 backward search). The return value is the index of the first match; a value of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	879 ``-1`` indicates that no match was found, and ``-2`` indicates that an error
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	880 occurred and an exception has been set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	881
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	882 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	883 This function used an :ctype:`int` type for start and end. This
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	884 might require changes in your code for properly supporting 64-bit
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	885 systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	886
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	887
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	888 .. cfunction:: Py_ssize_t PyUnicode_Count(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	889
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	890 Return the number of non-overlapping occurrences of substr in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	891 ``str[start:end]``. Return ``-1`` if an error occurred.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	892
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	893 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	894 This function returned an :ctype:`int` type and used an :ctype:`int`
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	895 type for start and end. This might require changes in your code for
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	896 properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	897
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	898
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	899 .. cfunction:: PyObject* PyUnicode_Replace(PyObject str, PyObject substr, PyObject *replstr, Py_ssize_t maxcount)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	900
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	901 Replace at most maxcount occurrences of substr in str with replstr and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	902 return the resulting Unicode object. maxcount == -1 means replace all
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	903 occurrences.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	904
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	905 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	906 This function used an :ctype:`int` type for maxcount. This might
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	907 require changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45341 diff changeset	908
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	909
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	910 .. cfunction:: int PyUnicode_Compare(PyObject left, PyObject right)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	911
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	912 Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	913 respectively.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	914
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	915
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	916 .. cfunction:: int PyUnicode_RichCompare(PyObject left, PyObject right, int op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	917
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	918 Rich compare two unicode strings and return one of the following:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	919
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	920 * ``NULL`` in case an exception was raised
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	921 * :const:`Py_True` or :const:`Py_False` for successful comparisons
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	922 * :const:`Py_NotImplemented` in case the type combination is unknown
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	923
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	924 Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	925 :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	926 with a :exc:`UnicodeDecodeError`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	927
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	928 Possible values for op are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	929 :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	930
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	931
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	932 .. cfunction:: PyObject* PyUnicode_Format(PyObject format, PyObject args)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	933
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	934 Return a new string object from format and args; this is analogous to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	935 ``format % args``. The args argument must be a tuple.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	936
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	937
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	938 .. cfunction:: int PyUnicode_Contains(PyObject container, PyObject element)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	939
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	940 Check whether element is contained in container and return true or false
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	941 accordingly.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	942
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	943 element has to coerce to a one element Unicode string. ``-1`` is returned if
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	944 there was an error.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/unicode.rst @ 54294:dba767bc3155 legacy-trunk