diff options
| -rw-r--r-- | Doc/c-api/long.rst | 28 | ||||
| -rw-r--r-- | Doc/c-api/unicode.rst | 105 | ||||
| -rw-r--r-- | Doc/data/refcounts.dat | 24 |
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:: |