[Python-checkins] r85632 - in python/branches/release27-maint/Doc: c-api/long.rst c-api/unicode.rst data/refcounts.dat
georg.brandl
python-checkins at python.org
Sun Oct 17 12:54:57 CEST 2010
Author: georg.brandl
Date: Sun Oct 17 12:54:57 2010
New Revision: 85632
Log:
#1945: document Unicode functions backported from py3k branch.
Modified:
python/branches/release27-maint/Doc/c-api/long.rst
python/branches/release27-maint/Doc/c-api/unicode.rst
python/branches/release27-maint/Doc/data/refcounts.dat
Modified: python/branches/release27-maint/Doc/c-api/long.rst
==============================================================================
--- python/branches/release27-maint/Doc/c-api/long.rst (original)
+++ python/branches/release27-maint/Doc/c-api/long.rst Sun Oct 17 12:54:57 2010
@@ -65,6 +65,22 @@
.. 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 @@
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::
Modified: python/branches/release27-maint/Doc/c-api/unicode.rst
==============================================================================
--- python/branches/release27-maint/Doc/c-api/unicode.rst (original)
+++ python/branches/release27-maint/Doc/c-api/unicode.rst Sun Oct 17 12:54:57 2010
@@ -220,6 +220,111 @@
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`
Modified: python/branches/release27-maint/Doc/data/refcounts.dat
==============================================================================
--- python/branches/release27-maint/Doc/data/refcounts.dat (original)
+++ python/branches/release27-maint/Doc/data/refcounts.dat Sun Oct 17 12:54:57 2010
@@ -638,6 +638,9 @@
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_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: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::
More information about the Python-checkins
mailing list