[Python-checkins] cpython: Move deprecated functions at the end of their respective sections.
antoine.pitrou
python-checkins at python.org
Sat Oct 22 22:00:21 CEST 2011
http://hg.python.org/cpython/rev/e66b7c62eec0
changeset: 73055:e66b7c62eec0
parent: 73053:941d015053c6
user: Antoine Pitrou <solipsis at pitrou.net>
date: Sat Oct 22 21:56:20 2011 +0200
summary:
Move deprecated functions at the end of their respective sections.
files:
Doc/c-api/unicode.rst | 376 +++++++++++++++---------------
1 files changed, 188 insertions(+), 188 deletions(-)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -81,6 +81,112 @@
subtype.
+.. c:function:: int PyUnicode_READY(PyObject *o)
+
+ Ensure the string object *o* is in the "canonical" representation. This is
+ required before using any of the access macros described below.
+
+ .. XXX expand on when it is not required
+
+ Returns 0 on success and -1 with an exception set on failure, which in
+ particular happens if memory allocation fails.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
+
+ Return the length of the Unicode string, in code points. *o* has to be a
+ Unicode object in the "canonical" representation (not checked).
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)
+ Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)
+ Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)
+
+ Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4
+ integer types for direct character access. No checks are performed if the
+ canonical representation has the correct character size; use
+ :c:func:`PyUnicode_KIND` to select the right macro. Make sure
+ :c:func:`PyUnicode_READY` has been called before accessing this.
+
+ .. versionadded:: 3.3
+
+
+.. c:macro:: PyUnicode_1BYTE_KIND
+ PyUnicode_2BYTE_KIND
+ PyUnicode_4BYTE_KIND
+
+ Return values of the :c:func:`PyUnicode_KIND` macro.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: int PyUnicode_KIND(PyObject *o)
+
+ Return one of the PyUnicode kind constants (see above) that indicate how many
+ bytes per character this Unicode object uses to store its data. *o* has to
+ be a Unicode object in the "canonical" representation (not checked).
+
+ .. XXX document "0" return value?
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: void* PyUnicode_DATA(PyObject *o)
+
+ Return a void pointer to the raw unicode buffer. *o* has to be a Unicode
+ object in the "canonical" representation (not checked).
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, \
+ Py_UCS4 value)
+
+ Write into a canonical representation *data* (as obtained with
+ :c:func:`PyUnicode_DATA`). This macro does not do any sanity checks and is
+ intended for usage in loops. The caller should cache the *kind* value and
+ *data* pointer as obtained from other macro calls. *index* is the index in
+ the string (starts at 0) and *value* is the new code point value which should
+ be written to that location.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
+
+ Read a code point from a canonical representation *data* (as obtained with
+ :c:func:`PyUnicode_DATA`). No checks or ready calls are performed.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)
+
+ Read a character from a Unicode object *o*, which must be in the "canonical"
+ representation. This is less efficient than :c:func:`PyUnicode_READ` if you
+ do multiple consecutive reads.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o)
+
+ Return the maximum code point that is suitable for creating another string
+ based on *o*, which must be in the "canonical" representation. This is
+ always an approximation but more efficient than iterating over the string.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: int PyUnicode_ClearFreeList()
+
+ Clear the free list. Return the total number of freed items.
+
+
.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
@@ -121,112 +227,6 @@
:c:func:`PyUnicode_nBYTE_DATA` family of macros.
-.. c:function:: int PyUnicode_READY(PyObject *o)
-
- Ensure the string object *o* is in the "canonical" representation. This is
- required before using any of the access macros described below.
-
- .. XXX expand on when it is not required
-
- Returns 0 on success and -1 with an exception set on failure, which in
- particular happens if memory allocation fails.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
-
- Return the length of the Unicode string, in code points. *o* has to be a
- Unicode object in the "canonical" representation (not checked).
-
- .. versionadded:: 3.3
-
-
-.. c:function:: Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)
- Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)
- Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)
-
- Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4
- integer types for direct character access. No checks are performed if the
- canonical representation has the correct character size; use
- :c:func:`PyUnicode_KIND` to select the right macro. Make sure
- :c:func:`PyUnicode_READY` has been called before accessing this.
-
- .. versionadded:: 3.3
-
-
-.. c:macro:: PyUnicode_1BYTE_KIND
- PyUnicode_2BYTE_KIND
- PyUnicode_4BYTE_KIND
-
- Return values of the :c:func:`PyUnicode_KIND` macro.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: int PyUnicode_KIND(PyObject *o)
-
- Return one of the PyUnicode kind constants (see above) that indicate how many
- bytes per character this Unicode object uses to store its data. *o* has to
- be a Unicode object in the "canonical" representation (not checked).
-
- .. XXX document "0" return value?
-
- .. versionadded:: 3.3
-
-
-.. c:function:: void* PyUnicode_DATA(PyObject *o)
-
- Return a void pointer to the raw unicode buffer. *o* has to be a Unicode
- object in the "canonical" representation (not checked).
-
- .. versionadded:: 3.3
-
-
-.. c:function:: void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, \
- Py_UCS4 value)
-
- Write into a canonical representation *data* (as obtained with
- :c:func:`PyUnicode_DATA`). This macro does not do any sanity checks and is
- intended for usage in loops. The caller should cache the *kind* value and
- *data* pointer as obtained from other macro calls. *index* is the index in
- the string (starts at 0) and *value* is the new code point value which should
- be written to that location.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
-
- Read a code point from a canonical representation *data* (as obtained with
- :c:func:`PyUnicode_DATA`). No checks or ready calls are performed.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)
-
- Read a character from a Unicode object *o*, which must be in the "canonical"
- representation. This is less efficient than :c:func:`PyUnicode_READ` if you
- do multiple consecutive reads.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o)
-
- Return the maximum code point that is suitable for creating another string
- based on *o*, which must be in the "canonical" representation. This is
- always an approximation but more efficient than iterating over the string.
-
- .. versionadded:: 3.3
-
-
-.. c:function:: int PyUnicode_ClearFreeList()
-
- Clear the free list. Return the total number of freed items.
-
-
Unicode Character Properties
""""""""""""""""""""""""""""
@@ -856,6 +856,16 @@
the codec.
+.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, \
+ const char *encoding, const char *errors)
+
+ Encode a Unicode object and return the result as Python bytes object.
+ *encoding* and *errors* have the same meaning as the parameters of the same
+ name in the Unicode :meth:`encode` method. The codec to be used is looked up
+ using the Python codec registry. Return *NULL* if an exception was raised by
+ the codec.
+
+
.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, \
const char *encoding, const char *errors)
@@ -870,16 +880,6 @@
:c:func:`PyUnicode_AsEncodedString`.
-.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, \
- const char *encoding, const char *errors)
-
- Encode a Unicode object and return the result as Python bytes object.
- *encoding* and *errors* have the same meaning as the parameters of the same
- name in the Unicode :meth:`encode` method. The codec to be used is looked up
- using the Python codec registry. Return *NULL* if an exception was raised by
- the codec.
-
-
UTF-8 Codecs
""""""""""""
@@ -901,17 +901,6 @@
that have been decoded will be stored in *consumed*.
-.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
- Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and
- return a Python bytes object. Return *NULL* if an exception was raised by
- the codec.
-
- .. deprecated-removed:: 3.3 4.0
- Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
- :c:func:`PyUnicode_AsUTF8String` or :c:func:`PyUnicode_AsUTF8AndSize`.
-
-
.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Encode a Unicode object using UTF-8 and return the result as Python bytes
@@ -942,6 +931,17 @@
.. versionadded:: 3.3
+.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and
+ return a Python bytes object. Return *NULL* if an exception was raised by
+ the codec.
+
+ .. deprecated-removed:: 3.3 4.0
+ Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+ :c:func:`PyUnicode_AsUTF8String` or :c:func:`PyUnicode_AsUTF8AndSize`.
+
+
UTF-32 Codecs
"""""""""""""
@@ -987,6 +987,13 @@
that have been decoded will be stored in *consumed*.
+.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
+
+ Return a Python byte string using the UTF-32 encoding in native byte
+ order. The string always starts with a BOM mark. Error handling is "strict".
+ Return *NULL* if an exception was raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, \
const char *errors, int byteorder)
@@ -1010,13 +1017,6 @@
:c:func:`PyUnicode_AsUTF32String`.
-.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
-
- Return a Python byte string using the UTF-32 encoding in native byte
- order. The string always starts with a BOM mark. Error handling is "strict".
- Return *NULL* if an exception was raised by the codec.
-
-
UTF-16 Codecs
"""""""""""""
@@ -1061,6 +1061,13 @@
number of bytes that have been decoded will be stored in *consumed*.
+.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
+
+ Return a Python byte string using the UTF-16 encoding in native byte
+ order. The string always starts with a BOM mark. Error handling is "strict".
+ Return *NULL* if an exception was raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, \
const char *errors, int byteorder)
@@ -1085,13 +1092,6 @@
:c:func:`PyUnicode_AsUTF16String`.
-.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
-
- Return a Python byte string using the UTF-16 encoding in native byte
- order. The string always starts with a BOM mark. Error handling is "strict".
- Return *NULL* if an exception was raised by the codec.
-
-
UTF-7 Codecs
""""""""""""
@@ -1144,6 +1144,13 @@
string *s*. Return *NULL* if an exception was raised by the codec.
+.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
+
+ Encode a Unicode object using Unicode-Escape and return the result as Python
+ string object. Error handling is "strict". Return *NULL* if an exception was
+ raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and
@@ -1155,13 +1162,6 @@
:c:func:`PyUnicode_AsUnicodeEscapeString`.
-.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
-
- Encode a Unicode object using Unicode-Escape and return the result as Python
- string object. Error handling is "strict". Return *NULL* if an exception was
- raised by the codec.
-
-
Raw-Unicode-Escape Codecs
"""""""""""""""""""""""""
@@ -1175,6 +1175,13 @@
encoded string *s*. Return *NULL* if an exception was raised by the codec.
+.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
+
+ Encode a Unicode object using Raw-Unicode-Escape and return the result as
+ Python string object. Error handling is "strict". Return *NULL* if an exception
+ was raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, \
Py_ssize_t size, const char *errors)
@@ -1187,13 +1194,6 @@
:c:func:`PyUnicode_AsRawUnicodeEscapeString`.
-.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
-
- Encode a Unicode object using Raw-Unicode-Escape and return the result as
- Python string object. Error handling is "strict". Return *NULL* if an exception
- was raised by the codec.
-
-
Latin-1 Codecs
""""""""""""""
@@ -1207,6 +1207,13 @@
*s*. Return *NULL* if an exception was raised by the codec.
+.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
+
+ Encode a Unicode object using Latin-1 and return the result as Python bytes
+ object. Error handling is "strict". Return *NULL* if an exception was
+ raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and
@@ -1218,13 +1225,6 @@
:c:func:`PyUnicode_AsLatin1String`.
-.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
-
- Encode a Unicode object using Latin-1 and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
- raised by the codec.
-
-
ASCII Codecs
""""""""""""
@@ -1238,6 +1238,13 @@
*s*. Return *NULL* if an exception was raised by the codec.
+.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
+
+ Encode a Unicode object using ASCII and return the result as Python bytes
+ object. Error handling is "strict". Return *NULL* if an exception was
+ raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and
@@ -1249,13 +1256,6 @@
:c:func:`PyUnicode_AsASCIIString`.
-.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
-
- Encode a Unicode object using ASCII and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
- raised by the codec.
-
-
Character Map Codecs
""""""""""""""""""""
@@ -1293,18 +1293,6 @@
treated as "undefined mapping".
-.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, \
- PyObject *mapping, const char *errors)
-
- Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
- *mapping* object and return a Python string object. Return *NULL* if an
- exception was raised by the codec.
-
- .. deprecated-removed:: 3.3 4.0
- Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
- :c:func:`PyUnicode_AsCharmapString`.
-
-
.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Encode a Unicode object using the given *mapping* object and return the result
@@ -1334,6 +1322,18 @@
.. XXX replace with what?
+.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, \
+ PyObject *mapping, const char *errors)
+
+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
+ *mapping* object and return a Python string object. Return *NULL* if an
+ exception was raised by the codec.
+
+ .. deprecated-removed:: 3.3 4.0
+ Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+ :c:func:`PyUnicode_AsCharmapString`.
+
+
MBCS codecs for Windows
"""""""""""""""""""""""
@@ -1357,6 +1357,13 @@
in *consumed*.
+.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
+
+ Encode a Unicode object using MBCS and return the result as Python bytes
+ object. Error handling is "strict". Return *NULL* if an exception was
+ raised by the codec.
+
+
.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return
@@ -1368,13 +1375,6 @@
:c:func:`PyUnicode_AsMBCSString`.
-.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
-
- Encode a Unicode object using MBCS and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
- raised by the codec.
-
-
Methods & Slots
"""""""""""""""
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list