Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/bytes.rst @ 79691:05c8928362ee

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