Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/c-api/string.rst

    r2 r391  
    1818
    1919
    20 .. ctype:: PyStringObject
    21 
    22    This subtype of :ctype:`PyObject` represents a Python string object.
    23 
    24 
    25 .. cvar:: PyTypeObject PyString_Type
     20.. c:type:: PyStringObject
     21
     22   This subtype of :c:type:`PyObject` represents a Python string object.
     23
     24
     25.. c:var:: PyTypeObject PyString_Type
    2626
    2727   .. index:: single: StringType (in module types)
    2828
    29    This instance of :ctype:`PyTypeObject` represents the Python string type; it is
     29   This instance of :c:type:`PyTypeObject` represents the Python string type; it is
    3030   the same object as ``str`` and ``types.StringType`` in the Python layer. .
    3131
    3232
    33 .. cfunction:: int PyString_Check(PyObject *o)
     33.. c:function:: int PyString_Check(PyObject *o)
    3434
    3535   Return true if the object *o* is a string object or an instance of a subtype of
    … …  
    4040
    4141
    42 .. cfunction:: int PyString_CheckExact(PyObject *o)
     42.. c:function:: int PyString_CheckExact(PyObject *o)
    4343
    4444   Return true if the object *o* is a string object, but not an instance of a
    … …  
    4848
    4949
    50 .. cfunction:: PyObject* PyString_FromString(const char *v)
     50.. c:function:: PyObject* PyString_FromString(const char *v)
    5151
    5252   Return a new string object with a copy of the string *v* as value on success,
    … …  
    5555
    5656
    57 .. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
     57.. c:function:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
    5858
    5959   Return a new string object with a copy of the string *v* as value and length
    … …  
    6262
    6363   .. versionchanged:: 2.5
    64       This function used an :ctype:`int` type for *len*. This might require
     64      This function used an :c:type:`int` type for *len*. This might require
    6565      changes in your code for properly supporting 64-bit systems.
    6666
    6767
    68 .. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
    69 
    70    Take a C :cfunc:`printf`\ -style *format* string and a variable number of
     68.. c:function:: PyObject* PyString_FromFormat(const char *format, ...)
     69
     70   Take a C :c:func:`printf`\ -style *format* string and a variable number of
    7171   arguments, calculate the size of the resulting Python string and return a string
    7272   with the values formatted into it.  The variable arguments must be C types and
    … …  
    7979   .. % because not all compilers support the %z width modifier -- we fake it
    8080   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
     81   .. % Similar comments apply to the %ll width modifier and
     82   .. % PY_FORMAT_LONG_LONG.
    8183   .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
    8284
    … …  
    100102   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
    101103   |                   |               | ``printf("%lu")``.             |
     104   +-------------------+---------------+--------------------------------+
     105   | :attr:`%lld`      | long long     | Exactly equivalent to          |
     106   |                   |               | ``printf("%lld")``.            |
     107   +-------------------+---------------+--------------------------------+
     108   | :attr:`%llu`      | unsigned      | Exactly equivalent to          |
     109   |                   | long long     | ``printf("%llu")``.            |
    102110   +-------------------+---------------+--------------------------------+
    103111   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
    … …  
    128136   copied as-is to the result string, and any extra arguments discarded.
    129137
    130 
    131 .. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
    132 
    133    Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two
     138   .. note::
     139
     140      The `"%lld"` and `"%llu"` format specifiers are only available
     141      when :const:`HAVE_LONG_LONG` is defined.
     142
     143   .. versionchanged:: 2.7
     144      Support for `"%lld"` and `"%llu"` added.
     145
     146
     147.. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
     148
     149   Identical to :c:func:`PyString_FromFormat` except that it takes exactly two
    134150   arguments.
    135151
    136152
    137 .. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
     153.. c:function:: Py_ssize_t PyString_Size(PyObject *string)
    138154
    139155   Return the length of the string in string object *string*.
    140156
    141157   .. versionchanged:: 2.5
    142       This function returned an :ctype:`int` type. This might require changes
     158      This function returned an :c:type:`int` type. This might require changes
    143159      in your code for properly supporting 64-bit systems.
    144160
    145161
    146 .. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
    147 
    148    Macro form of :cfunc:`PyString_Size` but without error checking.
    149 
    150    .. versionchanged:: 2.5
    151       This macro returned an :ctype:`int` type. This might require changes in
     162.. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
     163
     164   Macro form of :c:func:`PyString_Size` but without error checking.
     165
     166   .. versionchanged:: 2.5
     167      This macro returned an :c:type:`int` type. This might require changes in
    152168      your code for properly supporting 64-bit systems.
    153169
    154170
    155 .. cfunction:: char* PyString_AsString(PyObject *string)
     171.. c:function:: char* PyString_AsString(PyObject *string)
    156172
    157173   Return a NUL-terminated representation of the contents of *string*.  The pointer
    … …  
    161177   *string* is a Unicode object, this function computes the default encoding of
    162178   *string* and operates on that.  If *string* is not a string object at all,
    163    :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
    164 
    165 
    166 .. cfunction:: char* PyString_AS_STRING(PyObject *string)
    167 
    168    Macro form of :cfunc:`PyString_AsString` but without error checking.  Only
     179   :c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
     180
     181
     182.. c:function:: char* PyString_AS_STRING(PyObject *string)
     183
     184   Macro form of :c:func:`PyString_AsString` but without error checking.  Only
    169185   string objects are supported; no Unicode objects should be passed.
    170186
    171187
    172 .. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
     188.. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
    173189
    174190   Return a NUL-terminated representation of the contents of the object *obj*
    … …  
    185201   *string* is a Unicode object, this function computes the default encoding of
    186202   *string* and operates on that.  If *string* is not a string object at all,
    187    :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
    188 
    189    .. versionchanged:: 2.5
    190       This function used an :ctype:`int *` type for *length*. This might
     203   :c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
     204
     205   .. versionchanged:: 2.5
     206      This function used an :c:type:`int *` type for *length*. This might
    191207      require changes in your code for properly supporting 64-bit systems.
    192208
    193209
    194 .. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
     210.. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart)
    195211
    196212   Create a new string object in *\*string* containing the contents of *newpart*
    … …  
    201217
    202218
    203 .. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
     219.. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
    204220
    205221   Create a new string object in *\*string* containing the contents of *newpart*
    … …  
    207223
    208224
    209 .. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
     225.. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
    210226
    211227   A way to resize a string object even though it is "immutable". Only use this to
    … …  
    220236
    221237   .. versionchanged:: 2.5
    222       This function used an :ctype:`int` type for *newsize*. This might
     238      This function used an :c:type:`int` type for *newsize*. This might
    223239      require changes in your code for properly supporting 64-bit systems.
    224240
    225 .. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
     241.. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args)
    226242
    227243   Return a new string object from *format* and *args*. Analogous to ``format %
    228    args``.  The *args* argument must be a tuple.
    229 
    230 
    231 .. cfunction:: void PyString_InternInPlace(PyObject **string)
     244   args``.  The *args* argument must be a tuple or dict.
     245
     246
     247.. c:function:: void PyString_InternInPlace(PyObject **string)
    232248
    233249   Intern the argument *\*string* in place.  The argument must be the address of a
    … …  
    246262
    247263
    248 .. cfunction:: PyObject* PyString_InternFromString(const char *v)
    249 
    250    A combination of :cfunc:`PyString_FromString` and
    251    :cfunc:`PyString_InternInPlace`, returning either a new string object that has
     264.. c:function:: PyObject* PyString_InternFromString(const char *v)
     265
     266   A combination of :c:func:`PyString_FromString` and
     267   :c:func:`PyString_InternInPlace`, returning either a new string object that has
    252268   been interned, or a new ("owned") reference to an earlier interned string object
    253269   with the same value.
    … …  
    258274
    259275
    260 .. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
     276.. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
    261277
    262278   Create an object by decoding *size* bytes of the encoded buffer *s* using the
    … …  
    271287
    272288   .. versionchanged:: 2.5
    273       This function used an :ctype:`int` type for *size*. This might require
     289      This function used an :c:type:`int` type for *size*. This might require
    274290      changes in your code for properly supporting 64-bit systems.
    275291
    276292
    277 .. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
     293.. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
    278294
    279295   Decode a string object by passing it to the codec registered for *encoding* and
    … …  
    288304
    289305
    290 .. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
    291 
    292    Encode the :ctype:`char` buffer of the given size by passing it to the codec
     306.. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
     307
     308   Encode the :c:type:`char` buffer of the given size by passing it to the codec
    293309   registered for *encoding* and return a Python object. *encoding* and *errors*
    294310   have the same meaning as the parameters of the same name in the string
    … …  
    301317
    302318   .. versionchanged:: 2.5
    303       This function used an :ctype:`int` type for *size*. This might require
     319      This function used an :c:type:`int` type for *size*. This might require
    304320      changes in your code for properly supporting 64-bit systems.
    305321
    306322
    307 .. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
     323.. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
    308324
    309325   Encode a string object using the codec registered for *encoding* and return the
Note: See TracChangeset for help on using the changeset viewer.