#1945: document Unicode functions backported from py3k branch.

3 files changed, 157 insertions, 0 deletions

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index b9920a9..11d2908 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -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::
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index e7e5b47..fc9368d 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -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`
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 8a6eb66..1fc896f 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -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::