Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/bytes.rst @ 87690:66c1c9f32567 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859
author Radomir Dopieralski <devel@sheep.art.pl>
date Tue, 03 Dec 2013 16:02:48 +0100
parents 3ae74b361f53
children
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
82986
3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text.
Georg Brandl <georg@python.org>
parents: 68257
diff changeset
65 .. tabularcolumns:: |l|l|L|
3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text.
Georg Brandl <georg@python.org>
parents: 68257
diff changeset
66
44812
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 | Format Characters | Type | Comment |
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:`%%` | *n/a* | The literal % character. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 | :attr:`%c` | int | A single character, |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 | | | represented as an C int. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 | :attr:`%d` | int | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 | | | ``printf("%d")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 | :attr:`%u` | unsigned int | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 | | | ``printf("%u")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 | :attr:`%ld` | long | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 | | | ``printf("%ld")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 | :attr:`%lu` | unsigned long | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 | | | ``printf("%lu")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 | :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 | | | ``printf("%zd")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 | :attr:`%zu` | size_t | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 | | | ``printf("%zu")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 | :attr:`%i` | int | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 | | | ``printf("%i")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 | :attr:`%x` | int | Exactly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 | | | ``printf("%x")``. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 | :attr:`%s` | char\* | A null-terminated C character |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 | | | array. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 | :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
103 | | | pointer. Mostly equivalent to |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 | | | ``printf("%p")`` except that |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 | | | it is guaranteed to start with |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 | | | the literal ``0x`` regardless |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 | | | of what the platform's |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 | | | ``printf`` yields. |
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 +-------------------+---------------+--------------------------------+
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 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
112 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
113
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 .. 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
116
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
117 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
118 arguments.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
121 .. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
48871
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 47311
diff changeset
122
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 47311
diff changeset
123 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
124 protocol.
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 47311
diff changeset
125
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 47311
diff changeset
126
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
127 .. 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
128
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
129 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
130
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 .. 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
133
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
134 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
135
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
137 .. c:function:: char* PyBytes_AsString(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
139 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
140 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
141 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
142 ``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
143 *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
144 and raises :exc:`TypeError`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
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 .. 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
148
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
149 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
150
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
152 .. 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
153
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 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
155 through the output variables *buffer* and *length*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
157 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
158 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
159
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 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
161 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
162 ``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
163 *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
164 returns ``-1`` and raises :exc:`TypeError`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
167 .. 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
168
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
169 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
170 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
171 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
172 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
173 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
174
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
176 .. 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
177
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
178 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
179 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
180 *newpart*.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64132
diff changeset
183 .. 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
184
47311
a946bf766654 update docs after renaming of PyString -> PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 46963
diff changeset
185 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
186 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
187 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
188 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
189 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
190 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
191 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
192 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
193 *\*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
194 returned.