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

annotate Doc/c-api/unicode.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	74ff71b2f53d
children	75512a165318

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
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	14 Unicode Type
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	15 """"""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	16
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	17 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	18 Python:
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	21 .. c:type:: Py_UNICODE
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	22
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	23 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	24 basis for holding Unicode ordinals. Python's default builds use a 16-bit type
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	25 for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	26 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	27 with UCS4 builds of Python). These builds then use a 32-bit type for
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	28 :c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	29 where :c:type:`wchar_t` is available and compatible with the chosen Python
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	30 Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	31 :c:type:`wchar_t` to enhance native platform compatibility. On all other
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	32 platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	33 short` (UCS2) or :c:type:`unsigned long` (UCS4).
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	34
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	35 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	36 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	37
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	38
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	39 .. c:type:: PyUnicodeObject
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	40
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	41 This subtype of :c:type:`PyObject` represents a Python Unicode object.
44796 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	44 .. c:var:: PyTypeObject PyUnicode_Type
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	45
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	46 This instance of :c:type:`PyTypeObject` represents the Python Unicode type. It
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	47 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	48
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	49 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	50 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	51
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	52
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	53 .. c:function:: int PyUnicode_Check(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	54
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	55 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	56 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	57
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	58 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	59 Allowed subtypes to be accepted.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	62 .. c:function:: int PyUnicode_CheckExact(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	63
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	64 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	65 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	66
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	67 .. versionadded:: 2.2
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	70 .. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	71
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	72 Return the size of the object. o has to be a :c:type:`PyUnicodeObject` (not
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	73 checked).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	74
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	75 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	76 This function returned an :c:type:`int` type. This might require changes
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	77 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	78
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	79
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	80 .. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	81
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	82 Return the size of the object's internal buffer in bytes. o has to be a
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	83 :c:type:`PyUnicodeObject` (not checked).
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	84
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	85 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	86 This function returned an :c:type:`int` type. This might require changes
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	87 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	88
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	89
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	90 .. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	91
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	92 Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object. o
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	93 has to be a :c:type:`PyUnicodeObject` (not checked).
44796 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	96 .. c:function:: const char* PyUnicode_AS_DATA(PyObject *o)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	97
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	98 Return a pointer to the internal buffer of the object. o has to be a
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	99 :c:type:`PyUnicodeObject` (not checked).
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	100
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	101
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	102 .. c:function:: int PyUnicode_ClearFreeList()
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	103
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 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	105
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 .. 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	107
56816 66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 53588 diff changeset	108
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	109 Unicode Character Properties
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	110 """"""""""""""""""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	111
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	112 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	113 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	114 the Python configuration.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	117 .. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
44796 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 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	120
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	121
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	122 .. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
44796 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 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	125
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	126
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	127 .. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
44796 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 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	130
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	131
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	132 .. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
44796 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 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	135
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	136
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	137 .. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
44796 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 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	140
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	141
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	142 .. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
44796 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 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	145
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	146
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	147 .. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
44796 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 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	150
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	151
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	152 .. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
44796 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 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	155
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	156
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	157 .. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
44796 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 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	160
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	161
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	162 .. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	163
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	164 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	165
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	166 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	167
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	168
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	169 .. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
44796 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 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	172
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	173
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	174 .. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
44796 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 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	177
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	178
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	179 .. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
44796 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 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	182
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	183
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	184 .. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
44796 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 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	187 ``-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	188
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	189
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	190 .. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
44796 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 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	193 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	194
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	195
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	196 .. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
44796 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 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	199 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	200
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	201
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	202 Plain Py_UNICODE
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	203 """"""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	204
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	205 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	206 APIs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	207
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	208
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	209 .. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	210
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65462 diff changeset	211 Create a Unicode object from the Py_UNICODE buffer u of the given size. u
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	212 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	213 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	214 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	215 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	216 is NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	217
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	218 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	219 This function used an :c:type:`int` type for size. This might require
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	220 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	221
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	222
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	223 .. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	224
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65462 diff changeset	225 Create a Unicode object from the char buffer u. The bytes will be interpreted
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	226 as being UTF-8 encoded. u may also be NULL which
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	227 causes the contents to be undefined. It is the user's responsibility to fill in
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	228 the needed data. The buffer is copied into the new object. If the buffer is not
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	229 NULL, the return value might be a shared object. Therefore, modification of
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	230 the resulting Unicode object is only allowed when u is NULL.
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	231
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	232 .. versionadded:: 2.6
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	233
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	234
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	235 .. c:function:: PyObject PyUnicode_FromString(const char u)
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	236
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	237 Create a Unicode object from an UTF-8 encoded null-terminated char buffer
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	238 u.
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	239
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	240 .. versionadded:: 2.6
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	241
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	242
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	243 .. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	244
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	245 Take a C :c:func:`printf`\ -style format string and a variable number of
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	246 arguments, calculate the size of the resulting Python unicode string and return
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	247 a string with the values formatted into it. The variable arguments must be C
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	248 types and must correspond exactly to the format characters in the format
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	249 string. The following format characters are allowed:
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	250
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	251 .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	252 .. % because not all compilers support the %z width modifier -- we fake it
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	253 .. % when necessary via interpolating PY_FORMAT_SIZE_T.
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	254
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	255 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	256 \| Format Characters \| Type \| Comment \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	257 +===================+=====================+================================+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	258 \| :attr:`%%` \| n/a \| The literal % character. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	259 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	260 \| :attr:`%c` \| int \| A single character, \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	261 \| \| \| represented as an C int. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	262 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	263 \| :attr:`%d` \| int \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	264 \| \| \| ``printf("%d")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	265 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	266 \| :attr:`%u` \| unsigned int \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	267 \| \| \| ``printf("%u")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	268 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	269 \| :attr:`%ld` \| long \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	270 \| \| \| ``printf("%ld")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	271 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	272 \| :attr:`%lu` \| unsigned long \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	273 \| \| \| ``printf("%lu")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	274 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	275 \| :attr:`%zd` \| Py_ssize_t \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	276 \| \| \| ``printf("%zd")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	277 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	278 \| :attr:`%zu` \| size_t \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	279 \| \| \| ``printf("%zu")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	280 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	281 \| :attr:`%i` \| int \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	282 \| \| \| ``printf("%i")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	283 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	284 \| :attr:`%x` \| int \| Exactly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	285 \| \| \| ``printf("%x")``. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	286 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	287 \| :attr:`%s` \| char\* \| A null-terminated C character \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	288 \| \| \| array. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	289 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	290 \| :attr:`%p` \| void\* \| The hex representation of a C \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	291 \| \| \| pointer. Mostly equivalent to \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	292 \| \| \| ``printf("%p")`` except that \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	293 \| \| \| it is guaranteed to start with \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	294 \| \| \| the literal ``0x`` regardless \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	295 \| \| \| of what the platform's \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	296 \| \| \| ``printf`` yields. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	297 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	298 \| :attr:`%U` \| PyObject\* \| A unicode object. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	299 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	300 \| :attr:`%V` \| PyObject\, char \ \| A unicode object (which may be \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	301 \| \| \| NULL) and a null-terminated \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	302 \| \| \| C character array as a second \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	303 \| \| \| parameter (which will be used, \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	304 \| \| \| if the first parameter is \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	305 \| \| \| NULL). \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	306 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	307 \| :attr:`%S` \| PyObject\* \| The result of calling \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	308 \| \| \| :func:`PyObject_Unicode`. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	309 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	310 \| :attr:`%R` \| PyObject\* \| The result of calling \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	311 \| \| \| :func:`PyObject_Repr`. \|
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	312 +-------------------+---------------------+--------------------------------+
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	313
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	314 An unrecognized format character causes all the rest of the format string to be
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	315 copied as-is to the result string, and any extra arguments discarded.
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	316
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	317 .. versionadded:: 2.6
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	318
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	319
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	320 .. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
65462 31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	321
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	322 Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	323 arguments.
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	324
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	325 .. versionadded:: 2.6
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	326
31750c727ae3 #1945: document Unicode functions backported from py3k branch. Georg Brandl <georg@python.org> parents: 65127 diff changeset	327
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	328 .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	329
74054 1c4d9534263e Issue #13617: Document that the result PyUnicode_AsUnicode() and Victor Stinner <victor.stinner@haypocalc.com> parents: 69345 diff changeset	330 Return a read-only pointer to the Unicode object's internal
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	331 :c:type:`Py_UNICODE` buffer, NULL if unicode is not a Unicode object.
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	332 Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded
74054 1c4d9534263e Issue #13617: Document that the result PyUnicode_AsUnicode() and Victor Stinner <victor.stinner@haypocalc.com> parents: 69345 diff changeset	333 null characters, which would cause the string to be truncated when used in
1c4d9534263e Issue #13617: Document that the result PyUnicode_AsUnicode() and Victor Stinner <victor.stinner@haypocalc.com> parents: 69345 diff changeset	334 most C functions.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	335
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	336
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	337 .. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	338
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	339 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	340
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	341 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	342 This function returned an :c:type:`int` type. This might require changes
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	343 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	344
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	345
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	346 .. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject obj, const char encoding, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	347
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	348 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	349 incremented refcount.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	350
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	351 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	352 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	353 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	354 details).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	355
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	356 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	357 set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	358
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	359 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	360 decref'ing the returned objects.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	361
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	362
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	363 .. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	364
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	365 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	366 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	367
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	368 If the platform supports :c:type:`wchar_t` and provides a header file wchar.h,
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	369 Python can interface directly to this type using the following functions.
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	370 Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	371 the system's :c:type:`wchar_t`.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	372
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	373
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	374 wchar_t Support
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	375 """""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	376
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	377 :c:type:`wchar_t` support for platforms which support it:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	378
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	379 .. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	380
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	381 Create a Unicode object from the :c:type:`wchar_t` buffer w of the given size.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	382 Return NULL on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	383
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	384 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	385 This function used an :c:type:`int` type for size. This might require
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	386 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	387
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	388
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	389 .. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject unicode, wchar_t w, Py_ssize_t size)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	390
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	391 Copy the Unicode object contents into the :c:type:`wchar_t` buffer w. At most
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	392 size :c:type:`wchar_t` characters are copied (excluding a possibly trailing
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	393 0-termination character). Return the number of :c:type:`wchar_t` characters
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	394 copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t`
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	395 string may or may not be 0-terminated. It is the responsibility of the caller
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	396 to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	397 required by the application. Also, note that the :c:type:`wchar_t*` string
74054 1c4d9534263e Issue #13617: Document that the result PyUnicode_AsUnicode() and Victor Stinner <victor.stinner@haypocalc.com> parents: 69345 diff changeset	398 might contain null characters, which would cause the string to be truncated
1c4d9534263e Issue #13617: Document that the result PyUnicode_AsUnicode() and Victor Stinner <victor.stinner@haypocalc.com> parents: 69345 diff changeset	399 when used with most C functions.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	400
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	401 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	402 This function returned an :c:type:`int` type and used an :c:type:`int`
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	403 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	404 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	405
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	406
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	407 .. _builtincodecs:
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 Built-in Codecs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	410 ^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	411
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56816 diff changeset	412 Python provides a set of built-in codecs which are written in C for speed. All of
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	413 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	414
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	415 Many of the following APIs take two arguments encoding and errors, and they
7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	416 have the same semantics as the ones of the built-in :func:`unicode` Unicode
7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	417 object constructor.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	418
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	419 Setting encoding to NULL causes the default encoding to be used which is
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	420 ASCII. The file system calls should use :c:data:`Py_FileSystemDefaultEncoding`
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	421 as the encoding for file names. This variable should be treated as read-only: on
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	422 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	423 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	424
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	425 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	426 the default handling defined for the codec. Default error handling for all
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56816 diff changeset	427 built-in codecs is "strict" (:exc:`ValueError` is raised).
44796 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 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	430 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	431
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	432
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	433 Generic Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	434 """"""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	435
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	436 These are the generic codec APIs:
44796 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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	439 .. c:function:: PyObject* PyUnicode_Decode(const char s, Py_ssize_t size, const char encoding, const char *errors)
44796 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 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	442 encoding and errors have the same meaning as the parameters of the same name
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56816 diff changeset	443 in the :func:`unicode` built-in function. The codec to be used is looked up
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	444 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	445 the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	446
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	447 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	448 This function used an :c:type:`int` type for size. This might require
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	449 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	450
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	451
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	452 .. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE s, Py_ssize_t size, const char encoding, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	453
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	454 Encode the :c:type:`Py_UNICODE` buffer s of the given size and return a Python
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	455 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	456 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	457 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	458 raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	459
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	460 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	461 This function used an :c:type:`int` type for size. This might require
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	462 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	463
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	464
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	465 .. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject unicode, const char encoding, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	466
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	467 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	468 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	469 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	470 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	471 codec.
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
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	474 UTF-8 Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	475 """"""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	476
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	477 These are the UTF-8 codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	478
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	479
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	480 .. c:function:: PyObject* PyUnicode_DecodeUTF8(const char s, Py_ssize_t size, const char errors)
44796 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 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	483 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	484
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	485 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	486 This function used an :c:type:`int` type for size. This might require
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	487 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	488
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	489
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	490 .. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char s, Py_ssize_t size, const char errors, Py_ssize_t *consumed)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	491
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	492 If consumed is NULL, behave like :c:func:`PyUnicode_DecodeUTF8`. If
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	493 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	494 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	495 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	496
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	497 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	498
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	499 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	500 This function used an :c:type:`int` type for size. This might require
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	501 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	502
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	503
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	504 .. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	505
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	506 Encode the :c:type:`Py_UNICODE` buffer s of the given size using UTF-8 and return a
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	507 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	508
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	509 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	510 This function used an :c:type:`int` type for size. This might require
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	511 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	512
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	513
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	514 .. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	515
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	516 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	517 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	518 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	519
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	520
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	521 UTF-32 Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	522 """""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	523
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	524 These are the UTF-32 codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	525
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	526
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	527 .. c:function:: PyObject* PyUnicode_DecodeUTF32(const char s, Py_ssize_t size, const char errors, int *byteorder)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	528
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	529 Decode size bytes from a UTF-32 encoded buffer string and return the
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	530 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	531 handling. It defaults to "strict".
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	532
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	533 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	534 order::
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 *byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	537 *byteorder == 0: native order
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	538 *byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	539
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	540 If ``*byteorder`` is zero, and the first four bytes of the input data are a
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	541 byte order mark (BOM), the decoder switches to this byte order and the BOM is
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	542 not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	543 ``1``, any byte order mark is copied to the output.
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	544
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	545 After completion, \byteorder* is set to the current byte order at the end
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	546 of input data.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	547
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	548 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	549
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	550 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	551
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	552 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	553
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	554 .. versionadded:: 2.6
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	557 .. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char s, Py_ssize_t size, const char errors, int byteorder, Py_ssize_t consumed)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	558
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	559 If consumed is NULL, behave like :c:func:`PyUnicode_DecodeUTF32`. If
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	560 consumed is not NULL, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	561 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	562 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	563 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	564
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	565 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	566
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	567
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	568 .. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE s, Py_ssize_t size, const char errors, int byteorder)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	569
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	570 Return a Python bytes object holding the UTF-32 encoded value of the Unicode
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	571 data in s. Output is written according to the following byte order::
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	572
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	573 byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	574 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	575 byteorder == 1: big endian
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 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	578 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	579
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	580 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	581 as a single codepoint.
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 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	584
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	585 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	586
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	587
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	588 .. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	589
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	590 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	591 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	592 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	593
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	594 .. versionadded:: 2.6
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
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	597 UTF-16 Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	598 """""""""""""
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	599
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	600 These are the UTF-16 codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	601
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	602
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	603 .. c:function:: PyObject* PyUnicode_DecodeUTF16(const char s, Py_ssize_t size, const char errors, int *byteorder)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	604
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	605 Decode size bytes from a UTF-16 encoded buffer string and return the
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	606 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	607 handling. It defaults to "strict".
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 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	610 order::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	611
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	612 *byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	613 *byteorder == 0: native order
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	614 *byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	615
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	616 If ``*byteorder`` is zero, and the first two bytes of the input data are a
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	617 byte order mark (BOM), the decoder switches to this byte order and the BOM is
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	618 not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	619 ``1``, any byte order mark is copied to the output (where it will result in
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	620 either a ``\ufeff`` or a ``\ufffe`` character).
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	621
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	622 After completion, \byteorder* is set to the current byte order at the end
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	623 of input data.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	624
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	625 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	626
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	627 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	628
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	629 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	630 This function used an :c:type:`int` type for size. This might require
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	631 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	632
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	633
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	634 .. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char s, Py_ssize_t size, const char errors, int byteorder, Py_ssize_t consumed)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	635
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	636 If consumed is NULL, behave like :c:func:`PyUnicode_DecodeUTF16`. If
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	637 consumed is not NULL, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	638 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	639 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	640 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	641
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	642 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	643
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	644 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	645 This function used an :c:type:`int` type for size and an :c:type:`int *`
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	646 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	647 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	648
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	649
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	650 .. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE s, Py_ssize_t size, const char errors, int byteorder)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	651
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	652 Return a Python string object holding the UTF-16 encoded value of the Unicode
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	653 data in s. Output is written according to the following byte order::
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	654
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	655 byteorder == -1: little endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	656 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	657 byteorder == 1: big endian
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	658
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	659 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	660 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	661
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	662 If Py_UNICODE_WIDE is defined, a single :c:type:`Py_UNICODE` value may get
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	663 represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	664 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	665
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	666 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	667
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	668 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	669 This function used an :c:type:`int` type for size. This might require
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	670 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	671
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	672
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	673 .. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	674
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	675 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	676 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	677 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	678
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	679
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	680 UTF-7 Codecs
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	681 """"""""""""
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	682
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	683 These are the UTF-7 codec APIs:
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	684
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	685
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	686 .. c:function:: PyObject* PyUnicode_DecodeUTF7(const char s, Py_ssize_t size, const char errors)
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	687
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	688 Create a Unicode object by decoding size bytes of the UTF-7 encoded string
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	689 s. Return NULL if an exception was raised by the codec.
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	690
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	691
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	692 .. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char s, Py_ssize_t size, const char errors, Py_ssize_t *consumed)
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	693
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	694 If consumed is NULL, behave like :c:func:`PyUnicode_DecodeUTF7`. If
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	695 consumed is not NULL, trailing incomplete UTF-7 base-64 sections will not
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	696 be treated as an error. Those bytes will not be decoded and the number of
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	697 bytes that have been decoded will be stored in consumed.
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	698
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	699
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	700 .. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char errors)
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	701
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	702 Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
63608 595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	703 return a Python bytes object. Return NULL if an exception was raised by
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	704 the codec.
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	705
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	706 If base64SetO is nonzero, "Set O" (punctuation that has no otherwise
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	707 special meaning) will be encoded in base-64. If base64WhiteSpace is
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	708 nonzero, whitespace will be encoded in base-64. Both are set to zero for the
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	709 Python "utf-7" codec.
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	710
595676e466c0 Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from Georg Brandl <georg@python.org> parents: 61574 diff changeset	711
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	712 Unicode-Escape Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	713 """""""""""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	714
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	715 These are the "Unicode Escape" codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	716
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	717
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	718 .. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char s, Py_ssize_t size, const char errors)
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 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	721 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	722
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	723 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	724 This function used an :c:type:`int` type for size. This might require
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	725 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	726
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	727
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	728 .. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	729
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	730 Encode the :c:type:`Py_UNICODE` buffer of the given size using Unicode-Escape and
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	731 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	732 codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	733
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	734 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	735 This function used an :c:type:`int` type for size. This might require
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	736 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	737
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	738
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	739 .. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	740
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	741 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	742 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	743 raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	744
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	745
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	746 Raw-Unicode-Escape Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	747 """""""""""""""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	748
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	749 These are the "Raw Unicode Escape" codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	750
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	751
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	752 .. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	753
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	754 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	755 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	756
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	757 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	758 This function used an :c:type:`int` type for size. This might require
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	759 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	760
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	761
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	762 .. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	763
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	764 Encode the :c:type:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	765 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	766 the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	767
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	768 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	769 This function used an :c:type:`int` type for size. This might require
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 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	771
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	772
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	773 .. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
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 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	776 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	777 was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	778
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	779
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	780 Latin-1 Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	781 """"""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	782
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	783 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	784 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	785
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	786
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	787 .. c:function:: PyObject* PyUnicode_DecodeLatin1(const char s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	788
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	789 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	790 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	791
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	792 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	793 This function used an :c:type:`int` type for size. This might require
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	794 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	795
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	796
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	797 .. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	798
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	799 Encode the :c:type:`Py_UNICODE` buffer of the given size using Latin-1 and return
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	800 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	801
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	802 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	803 This function used an :c:type:`int` type for size. This might require
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	804 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	805
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	806
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	807 .. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
44796 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 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	810 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	811 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	812
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	813
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	814 ASCII Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	815 """"""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	816
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	817 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	818 codes generate errors.
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
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	821 .. c:function:: PyObject* PyUnicode_DecodeASCII(const char s, Py_ssize_t size, const char errors)
44796 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 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	824 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	825
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	826 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	827 This function used an :c:type:`int` type for size. This might require
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 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	829
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	830
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	831 .. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	832
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	833 Encode the :c:type:`Py_UNICODE` buffer of the given size using ASCII and return a
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	834 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	835
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	836 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	837 This function used an :c:type:`int` type for size. This might require
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	838 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	839
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	840
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	841 .. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	842
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	843 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	844 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	845 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	846
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	847
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	848 Character Map Codecs
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	849 """"""""""""""""""""
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	850
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	851 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	852 (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	853 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	854 decode characters.
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 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	857 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	858 (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	859
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	860 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	861 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	862 (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	863
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	864 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	865 interface.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	866
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	867 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	868 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	869 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	870 characters to different code points.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	871
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	872 These are the mapping codec APIs:
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	873
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	874 .. c:function:: PyObject* PyUnicode_DecodeCharmap(const char s, Py_ssize_t size, PyObject mapping, const char *errors)
44796 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 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	877 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	878 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	879 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	880 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	881 treated as "undefined mapping".
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	882
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	883 .. versionchanged:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	884 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	885
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	886 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	887 This function used an :c:type:`int` type for size. This might require
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	888 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	889
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	890
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	891 .. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE s, Py_ssize_t size, PyObject mapping, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	892
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	893 Encode the :c:type:`Py_UNICODE` buffer of the given size using the given
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	894 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	895 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	896
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	897 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	898 This function used an :c:type:`int` type for size. This might require
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	899 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	900
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	901
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	902 .. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject unicode, PyObject mapping)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	903
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	904 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	905 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	906 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	907
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	908 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	909
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	910
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	911 .. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE s, Py_ssize_t size, PyObject table, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	912
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	913 Translate a :c:type:`Py_UNICODE` buffer of the given size by applying a
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	914 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	915 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	916
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	917 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	918 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	919
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	920 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	921 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	922 :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	923
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	924 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	925 This function used an :c:type:`int` type for size. This might require
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	926 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	927
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	928
7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	929 MBCS codecs for Windows
7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	930 """""""""""""""""""""""
7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	931
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	932 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	933 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	934 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	935 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	936
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	937
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	938 .. c:function:: PyObject* PyUnicode_DecodeMBCS(const char s, Py_ssize_t size, const char errors)
44796 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 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	941 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	942
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	943 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	944 This function used an :c:type:`int` type for size. This might require
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	945 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	946
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	947
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	948 .. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char s, int size, const char errors, int *consumed)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	949
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	950 If consumed is NULL, behave like :c:func:`PyUnicode_DecodeMBCS`. If
74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	951 consumed is not NULL, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	952 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	953 in consumed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	954
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	955 .. versionadded:: 2.5
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	956
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	957
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	958 .. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE s, Py_ssize_t size, const char errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	959
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	960 Encode the :c:type:`Py_UNICODE` buffer of the given size using MBCS and return a
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	961 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	962
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	963 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	964 This function used an :c:type:`int` type for size. This might require
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	965 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	966
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	967
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	968 .. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	969
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	970 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	971 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	972 by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	973
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	974
61574 252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	975 Methods & Slots
252fe5c4cd53 Issue #8711: add paragraph titles to c-api/unicode.rst Victor Stinner <victor.stinner@haypocalc.com> parents: 56822 diff changeset	976 """""""""""""""
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	977
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	978 .. _unicodemethodsandslots:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	979
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	980 Methods and Slot Functions
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	981 ^^^^^^^^^^^^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	982
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	983 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	984 (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	985 integers as appropriate.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	986
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	987 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	988
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	989
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	990 .. c:function:: PyObject* PyUnicode_Concat(PyObject left, PyObject right)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	991
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	992 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	993
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	994
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	995 .. c:function:: PyObject* PyUnicode_Split(PyObject s, PyObject sep, Py_ssize_t maxsplit)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	996
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	997 Split a string giving a list of Unicode strings. If sep is NULL, splitting
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	998 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	999 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	1000 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	1001
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	1002 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1003 This function used an :c:type:`int` type for maxsplit. This might require
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	1004 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	1005
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1006
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1007 .. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1008
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1009 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	1010 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	1011 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	1012
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1013
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1014 .. c:function:: PyObject* PyUnicode_Translate(PyObject str, PyObject table, const char *errors)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1015
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1016 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	1017 resulting Unicode object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1018
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1019 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	1020 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	1021
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1022 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	1023 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	1024 :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	1025
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1026 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	1027 use the default error handling.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1028
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1029
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1030 .. c:function:: PyObject* PyUnicode_Join(PyObject separator, PyObject seq)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1031
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	1032 Join a sequence of strings using the given separator and return the resulting
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1033 Unicode string.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1034
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1035
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1036 .. c:function:: int PyUnicode_Tailmatch(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end, int direction)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1037
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	1038 Return 1 if substr matches ``str[start:end]`` at the given tail end
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1039 (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	1040 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	1041
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	1042 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1043 This function used an :c:type:`int` type for start and end. This
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	1044 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	1045 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	1046
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1047
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1048 .. c:function:: Py_ssize_t PyUnicode_Find(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end, int direction)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1049
69345 7f873729484c #11840: Improve c-api/unicode documentation. Patch by Sandro Tosi. Ezio Melotti <ezio.melotti@gmail.com> parents: 66457 diff changeset	1050 Return the first position of substr in ``str[start:end]`` using the given
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1051 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	1052 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	1053 ``-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	1054 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	1055
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	1056 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1057 This function used an :c:type:`int` type for start and end. This
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	1058 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	1059 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	1060
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1061
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1062 .. c:function:: Py_ssize_t PyUnicode_Count(PyObject str, PyObject substr, Py_ssize_t start, Py_ssize_t end)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1063
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1064 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	1065 ``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	1066
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	1067 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1068 This function returned an :c:type:`int` type and used an :c:type:`int`
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	1069 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	1070 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	1071
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1072
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1073 .. c:function:: PyObject* PyUnicode_Replace(PyObject str, PyObject substr, PyObject *replstr, Py_ssize_t maxcount)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1074
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1075 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	1076 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	1077 occurrences.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1078
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	1079 .. versionchanged:: 2.5
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1080 This function used an :c:type:`int` type for maxcount. This might
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	1081 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	1082
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1083
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1084 .. c:function:: int PyUnicode_Compare(PyObject left, PyObject right)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1085
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1086 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	1087 respectively.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1088
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1089
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1090 .. c:function:: int PyUnicode_RichCompare(PyObject left, PyObject right, int op)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1091
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1092 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	1093
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1094 * ``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	1095 * :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	1096 * :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	1097
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1098 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	1099 :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	1100 with a :exc:`UnicodeDecodeError`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1101
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1102 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	1103 :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	1104
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1105
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1106 .. c:function:: PyObject* PyUnicode_Format(PyObject format, PyObject args)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1107
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1108 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	1109 ``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	1110
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1111
74395 74ff71b2f53d update to new C roles and directives Sandro Tosi <sandro.tosi@gmail.com> parents: 74068 diff changeset	1112 .. c:function:: int PyUnicode_Contains(PyObject container, PyObject element)
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1113
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1114 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	1115 accordingly.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1116
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1117 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	1118 there was an error.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/unicode.rst @ 79675:c0a2294de787 2.7