← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/c-api/bytes.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/bytes.rst
 
1
.. highlightlang:: c
 
2
 
 
3
.. _bytesobjects:
 
4
 
 
5
Bytes Objects
 
6
-------------
 
7
 
 
8
These functions raise :exc:`TypeError` when expecting a bytes parameter and are
 
9
called with a non-bytes parameter.
 
10
 
 
11
.. index:: object: bytes
 
12
 
 
13
 
 
14
.. c:type:: PyBytesObject
 
15
 
 
16
   This subtype of :c:type:`PyObject` represents a Python bytes object.
 
17
 
 
18
 
 
19
.. c:var:: PyTypeObject PyBytes_Type
 
20
 
 
21
   This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
 
22
   is the same object as :class:`bytes` in the Python layer.
 
23
 
 
24
 
 
25
.. c:function:: int PyBytes_Check(PyObject *o)
 
26
 
 
27
   Return true if the object *o* is a bytes object or an instance of a subtype
 
28
   of the bytes type.
 
29
 
 
30
 
 
31
.. c:function:: int PyBytes_CheckExact(PyObject *o)
 
32
 
 
33
   Return true if the object *o* is a bytes object, but not an instance of a
 
34
   subtype of the bytes type.
 
35
 
 
36
 
 
37
.. c:function:: PyObject* PyBytes_FromString(const char *v)
 
38
 
 
39
   Return a new bytes object with a copy of the string *v* as value on success,
 
40
   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
 
41
   checked.
 
42
 
 
43
 
 
44
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
 
45
 
 
46
   Return a new bytes object with a copy of the string *v* as value and length
 
47
   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of
 
48
   the bytes object are uninitialized.
 
49
 
 
50
 
 
51
.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
 
52
 
 
53
   Take a C :c:func:`printf`\ -style *format* string and a variable number of
 
54
   arguments, calculate the size of the resulting Python bytes object and return
 
55
   a bytes object with the values formatted into it.  The variable arguments
 
56
   must be C types and must correspond exactly to the format characters in the
 
57
   *format* string.  The following format characters are allowed:
 
58
 
 
59
   .. % XXX: This should be exactly the same as the table in PyErr_Format.
 
60
   .. % One should just refer to the other.
 
61
   .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
 
62
   .. % because not all compilers support the %z width modifier -- we fake it
 
63
   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 
64
 
 
65
   .. tabularcolumns:: |l|l|L|
 
66
 
 
67
   +-------------------+---------------+--------------------------------+
 
68
   | Format Characters | Type          | Comment                        |
 
69
   +===================+===============+================================+
 
70
   | :attr:`%%`        | *n/a*         | The literal % character.       |
 
71
   +-------------------+---------------+--------------------------------+
 
72
   | :attr:`%c`        | int           | A single character,            |
 
73
   |                   |               | represented as an C int.       |
 
74
   +-------------------+---------------+--------------------------------+
 
75
   | :attr:`%d`        | int           | Exactly equivalent to          |
 
76
   |                   |               | ``printf("%d")``.              |
 
77
   +-------------------+---------------+--------------------------------+
 
78
   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
 
79
   |                   |               | ``printf("%u")``.              |
 
80
   +-------------------+---------------+--------------------------------+
 
81
   | :attr:`%ld`       | long          | Exactly equivalent to          |
 
82
   |                   |               | ``printf("%ld")``.             |
 
83
   +-------------------+---------------+--------------------------------+
 
84
   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
 
85
   |                   |               | ``printf("%lu")``.             |
 
86
   +-------------------+---------------+--------------------------------+
 
87
   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
 
88
   |                   |               | ``printf("%zd")``.             |
 
89
   +-------------------+---------------+--------------------------------+
 
90
   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
 
91
   |                   |               | ``printf("%zu")``.             |
 
92
   +-------------------+---------------+--------------------------------+
 
93
   | :attr:`%i`        | int           | Exactly equivalent to          |
 
94
   |                   |               | ``printf("%i")``.              |
 
95
   +-------------------+---------------+--------------------------------+
 
96
   | :attr:`%x`        | int           | Exactly equivalent to          |
 
97
   |                   |               | ``printf("%x")``.              |
 
98
   +-------------------+---------------+--------------------------------+
 
99
   | :attr:`%s`        | char\*        | A null-terminated C character  |
 
100
   |                   |               | array.                         |
 
101
   +-------------------+---------------+--------------------------------+
 
102
   | :attr:`%p`        | void\*        | The hex representation of a C  |
 
103
   |                   |               | pointer. Mostly equivalent to  |
 
104
   |                   |               | ``printf("%p")`` except that   |
 
105
   |                   |               | it is guaranteed to start with |
 
106
   |                   |               | the literal ``0x`` regardless  |
 
107
   |                   |               | of what the platform's         |
 
108
   |                   |               | ``printf`` yields.             |
 
109
   +-------------------+---------------+--------------------------------+
 
110
 
 
111
   An unrecognized format character causes all the rest of the format string to be
 
112
   copied as-is to the result string, and any extra arguments discarded.
 
113
 
 
114
 
 
115
.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
 
116
 
 
117
   Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
 
118
   arguments.
 
119
 
 
120
 
 
121
.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
 
122
 
 
123
   Return the bytes representation of object *o* that implements the buffer
 
124
   protocol.
 
125
 
 
126
 
 
127
.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
 
128
 
 
129
   Return the length of the bytes in bytes object *o*.
 
130
 
 
131
 
 
132
.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
 
133
 
 
134
   Macro form of :c:func:`PyBytes_Size` but without error checking.
 
135
 
 
136
 
 
137
.. c:function:: char* PyBytes_AsString(PyObject *o)
 
138
 
 
139
   Return a NUL-terminated representation of the contents of *o*.  The pointer
 
140
   refers to the internal buffer of *o*, not a copy.  The data must not be
 
141
   modified in any way, unless the string was just created using
 
142
   ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
 
143
   *o* is not a string object at all, :c:func:`PyBytes_AsString` returns *NULL*
 
144
   and raises :exc:`TypeError`.
 
145
 
 
146
 
 
147
.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
 
148
 
 
149
   Macro form of :c:func:`PyBytes_AsString` but without error checking.
 
150
 
 
151
 
 
152
.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
 
153
 
 
154
   Return a NUL-terminated representation of the contents of the object *obj*
 
155
   through the output variables *buffer* and *length*.
 
156
 
 
157
   If *length* is *NULL*, the resulting buffer may not contain NUL characters;
 
158
   if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
 
159
 
 
160
   The buffer refers to an internal string buffer of *obj*, not a copy. The data
 
161
   must not be modified in any way, unless the string was just created using
 
162
   ``PyBytes_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
 
163
   *string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
 
164
   returns ``-1`` and raises :exc:`TypeError`.
 
165
 
 
166
 
 
167
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
 
168
 
 
169
   Create a new bytes object in *\*bytes* containing the contents of *newpart*
 
170
   appended to *bytes*; the caller will own the new reference.  The reference to
 
171
   the old value of *bytes* will be stolen.  If the new string cannot be
 
172
   created, the old reference to *bytes* will still be discarded and the value
 
173
   of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
 
174
 
 
175
 
 
176
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
 
177
 
 
178
   Create a new string object in *\*bytes* containing the contents of *newpart*
 
179
   appended to *bytes*.  This version decrements the reference count of
 
180
   *newpart*.
 
181
 
 
182
 
 
183
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
 
184
 
 
185
   A way to resize a bytes object even though it is "immutable". Only use this
 
186
   to build up a brand new bytes object; don't use this if the bytes may already
 
187
   be known in other parts of the code.  It is an error to call this function if
 
188
   the refcount on the input bytes object is not one. Pass the address of an
 
189
   existing bytes object as an lvalue (it may be written into), and the new size
 
190
   desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
 
191
   returned; the address in *\*bytes* may differ from its input value.  If the
 
192
   reallocation fails, the original bytes object at *\*bytes* is deallocated,
 
193
   *\*bytes* is set to *NULL*, a memory exception is set, and ``-1`` is
 
194
   returned.