Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

#1945: document Unicode functions backported from py3k branch.

This commit is contained in:
Georg Brandl 2010-10-17 10:54:57 +00:00
parent 27fa482afd
commit 79cdff0b9b
3 changed files with 157 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Doc/c-api/long.rst
View File

@ -65,6 +65,22 @@ Long Integer Objects
.. versionadded:: 2.6
.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
on failure.
.. versionadded:: 2.6
.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
on failure.
.. versionadded:: 2.6
.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
@ -183,6 +199,18 @@ Long Integer Objects
raised.
.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
.. index::
single: PY_SSIZE_T_MAX
Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*. If
*pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is
raised.
.. versionadded:: 2.6
.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
.. index::

105
Doc/c-api/unicode.rst
View File

@ -220,6 +220,111 @@ APIs:
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
Create a Unicode Object from the char buffer *u*. The bytes will be interpreted
as being UTF-8 encoded. *u* may also be *NULL* which
causes the contents to be undefined. It is the user's responsibility to fill in
the needed data. The buffer is copied into the new object. If the buffer is not
*NULL*, the return value might be a shared object. Therefore, modification of
the resulting Unicode object is only allowed when *u* is *NULL*.
.. versionadded:: 2.6
.. cfunction:: PyObject *PyUnicode_FromString(const char *u)
Create a Unicode object from an UTF-8 encoded null-terminated char buffer
*u*.
.. versionadded:: 2.6
.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...)
Take a C :cfunc:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python unicode string and return
a string with the values formatted into it. The variable arguments must be C
types and must correspond exactly to the format characters in the *format*
string. The following format characters are allowed:
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
+-------------------+---------------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+=====================+================================+
| :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------------+--------------------------------+
| :attr:`%c` | int | A single character, |
| | | represented as an C int. |
+-------------------+---------------------+--------------------------------+
| :attr:`%d` | int | Exactly equivalent to |
| | | ``printf("%d")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%u` | unsigned int | Exactly equivalent to |
| | | ``printf("%u")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%ld` | long | Exactly equivalent to |
| | | ``printf("%ld")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%lu` | unsigned long | Exactly equivalent to |
| | | ``printf("%lu")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
| | | ``printf("%zd")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%zu` | size_t | Exactly equivalent to |
| | | ``printf("%zu")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%i` | int | Exactly equivalent to |
| | | ``printf("%i")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
| | | the literal ``0x`` regardless |
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------------+--------------------------------+
| :attr:`%U` | PyObject\* | A unicode object. |
+-------------------+---------------------+--------------------------------+
| :attr:`%V` | PyObject\*, char \* | A unicode object (which may be |
| | | *NULL*) and a null-terminated |
| | | C character array as a second |
| | | parameter (which will be used, |
| | | if the first parameter is |
| | | *NULL*). |
+-------------------+---------------------+--------------------------------+
| :attr:`%S` | PyObject\* | The result of calling |
| | | :func:`PyObject_Unicode`. |
+-------------------+---------------------+--------------------------------+
| :attr:`%R` | PyObject\* | The result of calling |
| | | :func:`PyObject_Repr`. |
+-------------------+---------------------+--------------------------------+
An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.
.. versionadded:: 2.6
.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
arguments.
.. versionadded:: 2.6
.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`

24
Doc/data/refcounts.dat
View File

@ -638,6 +638,9 @@ PyLong_AsDouble:PyObject*:pylong:0:
PyLong_AsLong:long:::
PyLong_AsLong:PyObject*:pylong:0:
PyLong_AsSsize_t:ssize_t:::
PyLong_AsSsize_t:PyObject*:pylong:0:
PyLong_AsUnsignedLong:unsigned long:::
PyLong_AsUnsignedLong:PyObject*:pylong:0:
@ -656,6 +659,12 @@ PyLong_FromLongLong:long long:v::
PyLong_FromUnsignedLongLong:PyObject*::+1:
PyLong_FromUnsignedLongLong:unsigned long long:v::
PyLong_FromSize_t:PyObject*::+1:
PyLong_FromSize_t:size_t:v::
PyLong_FromSsize_t:PyObject*::+1:
PyLong_FromSsize_t:ssize_t:v::
PyLong_FromString:PyObject*::+1:
PyLong_FromString:char*:str::
PyLong_FromString:char**:pend::
@ -1473,6 +1482,21 @@ PyUnicode_FromEncodedObject:PyObject*:*obj:0:
PyUnicode_FromEncodedObject:const char*:encoding::
PyUnicode_FromEncodedObject:const char*:errors::
PyUnicode_FromFormat:PyObject*::+1:
PyUnicode_FromFormat:const char*:format::
PyUnicode_FromFormat::...::
PyUnicode_FromFormatV:PyObject*::+1:
PyUnicode_FromFormatV:const char*:format::
PyUnicode_FromFormatV:va_list:vargs::
PyUnicode_FromString:PyObject*::+1:
PyUnicode_FromString:const char*:u::
PyUnicode_FromStringAndSize:PyObject*::+1:
PyUnicode_FromStringAndSize:const char*:u::
PyUnicode_FromStringAndSize:ssize_t:size::
PyUnicode_FromWideChar:PyObject*::+1:
PyUnicode_FromWideChar:const wchar_t*:w::
PyUnicode_FromWideChar:int:size::