mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-08 03:45:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

bpo-28749: Fixed the documentation of the mapping codec APIs. (#487)

Browse source 
Added the documentation for PyUnicode_Translate().
This commit is contained in:
Serhiy Storchaka 2017-03-19 08:15:17 +02:00 • committed by GitHub
parent 909a6f626f
commit c85a26628c
2 changed files with 67 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

43
Include/unicodeobject.h
View file

@ -1613,50 +1613,41 @@ PyAPI_FUNC(PyObject*) PyUnicode_EncodeASCII(
This codec uses mappings to encode and decode characters.
Decoding mappings must map single string characters to single
Unicode characters, integers (which are then interpreted as Unicode
ordinals) or None (meaning "undefined mapping" and causing an
error).
Decoding mappings must map byte ordinals (integers in the range from 0 to
255) to Unicode strings, integers (which are then interpreted as Unicode
ordinals) or None. Unmapped data bytes (ones which cause a LookupError)
as well as mapped to None, 0xFFFE or '\ufffe' are treated as "undefined
mapping" and cause an error.
Encoding mappings must map single Unicode characters to single
string characters, integers (which are then interpreted as Latin-1
ordinals) or None (meaning "undefined mapping" and causing an
error).
If a character lookup fails with a LookupError, the character is
copied as-is meaning that its ordinal value will be interpreted as
Unicode or Latin-1 ordinal resp. Because of this mappings only need
to contain those mappings which map characters to different code
points.
Encoding mappings must map Unicode ordinal integers to bytes objects,
integers in the range from 0 to 255 or None. Unmapped character
ordinals (ones which cause a LookupError) as well as mapped to
None are treated as "undefined mapping" and cause an error.
*/
PyAPI_FUNC(PyObject*) PyUnicode_DecodeCharmap(
const char *string, /* Encoded string */
Py_ssize_t length, /* size of string */
PyObject *mapping, /* character mapping
(char ordinal -> unicode ordinal) */
PyObject *mapping, /* decoding mapping */
const char *errors /* error handling */
);
PyAPI_FUNC(PyObject*) PyUnicode_AsCharmapString(
PyObject *unicode, /* Unicode object */
PyObject *mapping /* character mapping
(unicode ordinal -> char ordinal) */
PyObject *mapping /* encoding mapping */
);
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject*) PyUnicode_EncodeCharmap(
const Py_UNICODE *data, /* Unicode char buffer */
Py_ssize_t length, /* Number of Py_UNICODE chars to encode */
PyObject *mapping, /* character mapping
(unicode ordinal -> char ordinal) */
PyObject *mapping, /* encoding mapping */
const char *errors /* error handling */
) Py_DEPRECATED(3.3);
PyAPI_FUNC(PyObject*) _PyUnicode_EncodeCharmap(
PyObject *unicode, /* Unicode object */
PyObject *mapping, /* character mapping
(unicode ordinal -> char ordinal) */
PyObject *mapping, /* encoding mapping */
const char *errors /* error handling */
);
#endif
@ -1665,8 +1656,8 @@ PyAPI_FUNC(PyObject*) _PyUnicode_EncodeCharmap(
character mapping table to it and return the resulting Unicode
object.
The mapping table must map Unicode ordinal integers to Unicode
ordinal integers or None (causing deletion of the character).
The mapping table must map Unicode ordinal integers to Unicode strings,
Unicode ordinal integers or None (causing deletion of the character).
Mapping tables may be dictionaries or sequences. Unmapped character
ordinals (ones which cause a LookupError) are left untouched and
@ -1964,8 +1955,8 @@ PyAPI_FUNC(PyObject*) PyUnicode_RSplit(
/* Translate a string by applying a character mapping table to it and
return the resulting Unicode object.
The mapping table must map Unicode ordinal integers to Unicode
ordinal integers or None (causing deletion of the character).
The mapping table must map Unicode ordinal integers to Unicode strings,
Unicode ordinal integers or None (causing deletion of the character).
Mapping tables may be dictionaries or sequences. Unmapped character
ordinals (ones which cause a LookupError) are left untouched and