Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/string.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 74ff71b2f53d
children 405245885569
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _stringobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
47305
708a561279ca note that PyString and has been aliased to PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 44796
diff changeset
5 String/Bytes Objects
708a561279ca note that PyString and has been aliased to PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 44796
diff changeset
6 --------------------
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 These functions raise :exc:`TypeError` when expecting a string parameter and are
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 called with a non-string parameter.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
47305
708a561279ca note that PyString and has been aliased to PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 44796
diff changeset
11 .. note::
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
12
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
13 These functions have been renamed to PyBytes_* in Python 3.x. Unless
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
14 otherwise noted, the PyBytes functions available in 3.x are aliased to their
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
15 PyString_* equivalents to help porting.
47305
708a561279ca note that PyString and has been aliased to PyBytes
Benjamin Peterson <benjamin@python.org>
parents: 44796
diff changeset
16
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 .. index:: object: string
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
20 .. c:type:: PyStringObject
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
22 This subtype of :c:type:`PyObject` represents a Python string object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
25 .. c:var:: PyTypeObject PyString_Type
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 .. index:: single: StringType (in module types)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
29 This instance of :c:type:`PyTypeObject` represents the Python string type; it is
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 the same object as ``str`` and ``types.StringType`` in the Python layer. .
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
33 .. c:function:: int PyString_Check(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 Return true if the object *o* is a string object or an instance of a subtype of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 the string type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
42 .. c:function:: int PyString_CheckExact(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 Return true if the object *o* is a string object, but not an instance of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 subtype of the string type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
50 .. c:function:: PyObject* PyString_FromString(const char *v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 Return a new string object with a copy of the string *v* as value on success,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 checked.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
57 .. c:function:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
58
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 Return a new string object with a copy of the string *v* as value and length
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 string are uninitialized.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
63 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
64 This function used an :c:type:`int` type for *len*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
65 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
66
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
68 .. c:function:: PyObject* PyString_FromFormat(const char *format, ...)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
70 Take a C :c:func:`printf`\ -style *format* string and a variable number of
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 arguments, calculate the size of the resulting Python string and return a string
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 with the values formatted into it. The variable arguments must be C types and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 must correspond exactly to the format characters in the *format* string. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 following format characters are allowed:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 .. % This should be exactly the same as the table in PyErr_Format.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 .. % One should just refer to the other.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 .. % because not all compilers support the %z width modifier -- we fake it
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 .. % when necessary via interpolating PY_FORMAT_SIZE_T.
57277
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
81 .. % Similar comments apply to the %ll width modifier and
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
82 .. % PY_FORMAT_LONG_LONG.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 | Format Characters | Type | Comment |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 +===================+===============+================================+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 | :attr:`%%` | *n/a* | The literal % character. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 | :attr:`%c` | int | A single character, |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 | | | represented as an C int. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 | :attr:`%d` | int | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 | | | ``printf("%d")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 | :attr:`%u` | unsigned int | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 | | | ``printf("%u")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 | :attr:`%ld` | long | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 | | | ``printf("%ld")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 | :attr:`%lu` | unsigned long | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 | | | ``printf("%lu")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 +-------------------+---------------+--------------------------------+
57277
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
105 | :attr:`%lld` | long long | Exactly equivalent to |
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
106 | | | ``printf("%lld")``. |
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
107 +-------------------+---------------+--------------------------------+
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
108 | :attr:`%llu` | unsigned | Exactly equivalent to |
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
109 | | long long | ``printf("%llu")``. |
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
110 +-------------------+---------------+--------------------------------+
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 | :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 | | | ``printf("%zd")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 | :attr:`%zu` | size_t | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 | | | ``printf("%zu")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 | :attr:`%i` | int | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 | | | ``printf("%i")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 | :attr:`%x` | int | Exactly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 | | | ``printf("%x")``. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 | :attr:`%s` | char\* | A null-terminated C character |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 | | | array. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 | :attr:`%p` | void\* | The hex representation of a C |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 | | | pointer. Mostly equivalent to |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 | | | ``printf("%p")`` except that |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 | | | it is guaranteed to start with |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 | | | the literal ``0x`` regardless |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 | | | of what the platform's |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 | | | ``printf`` yields. |
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 An unrecognized format character causes all the rest of the format string to be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 copied as-is to the result string, and any extra arguments discarded.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
57277
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
138 .. note::
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
139
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
140 The `"%lld"` and `"%llu"` format specifiers are only available
59528
62d7f049703b Fix warnings from "make check".
Georg Brandl <georg@python.org>
parents: 57277
diff changeset
141 when :const:`HAVE_LONG_LONG` is defined.
57277
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
142
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
143 .. versionchanged:: 2.7
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
144 Support for `"%lld"` and `"%llu"` added.
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString,
Mark Dickinson <dickinsm@gmail.com>
parents: 53436
diff changeset
145
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
147 .. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
149 Identical to :c:func:`PyString_FromFormat` except that it takes exactly two
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 arguments.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
153 .. c:function:: Py_ssize_t PyString_Size(PyObject *string)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 Return the length of the string in string object *string*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
157 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
158 This function returned an :c:type:`int` type. This might require changes
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
159 in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
160
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
162 .. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
164 Macro form of :c:func:`PyString_Size` but without error checking.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
166 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
167 This macro returned an :c:type:`int` type. This might require changes in
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
168 your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
169
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
171 .. c:function:: char* PyString_AsString(PyObject *string)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 Return a NUL-terminated representation of the contents of *string*. The pointer
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 refers to the internal buffer of *string*, not a copy. The data must not be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 modified in any way, unless the string was just created using
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 *string* is a Unicode object, this function computes the default encoding of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 *string* and operates on that. If *string* is not a string object at all,
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
179 :c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
182 .. c:function:: char* PyString_AS_STRING(PyObject *string)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
184 Macro form of :c:func:`PyString_AsString` but without error checking. Only
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 string objects are supported; no Unicode objects should be passed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
188 .. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 Return a NUL-terminated representation of the contents of the object *obj*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 through the output variables *buffer* and *length*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 The function accepts both string and Unicode objects as input. For Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 objects it returns the default encoded version of the object. If *length* is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 *NULL*, the resulting buffer may not contain NUL characters; if it does, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 function returns ``-1`` and a :exc:`TypeError` is raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 The buffer refers to an internal string buffer of *obj*, not a copy. The data
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 must not be modified in any way, unless the string was just created using
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 *string* is a Unicode object, this function computes the default encoding of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 *string* and operates on that. If *string* is not a string object at all,
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
203 :c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
205 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
206 This function used an :c:type:`int *` type for *length*. This might
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
207 require changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
208
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
209
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
210 .. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 Create a new string object in *\*string* containing the contents of *newpart*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 appended to *string*; the caller will own the new reference. The reference to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 the old value of *string* will be stolen. If the new string cannot be created,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 the old reference to *string* will still be discarded and the value of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 *\*string* will be set to *NULL*; the appropriate exception will be set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
217
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
219 .. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 Create a new string object in *\*string* containing the contents of *newpart*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 appended to *string*. This version decrements the reference count of *newpart*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
225 .. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 A way to resize a string object even though it is "immutable". Only use this to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 build up a brand new string object; don't use this if the string may already be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 known in other parts of the code. It is an error to call this function if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 refcount on the input string object is not one. Pass the address of an existing
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 string object as an lvalue (it may be written into), and the new size desired.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 On success, *\*string* holds the resized string object and ``0`` is returned;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 the address in *\*string* may differ from its input value. If the reallocation
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 fails, the original string object at *\*string* is deallocated, *\*string* is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 set to *NULL*, a memory exception is set, and ``-1`` is returned.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
237 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
238 This function used an :c:type:`int` type for *newsize*. This might
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
239 require changes in your code for properly supporting 64-bit systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
241 .. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 Return a new string object from *format* and *args*. Analogous to ``format %
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 args``. The *args* argument must be a tuple.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
246
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
247 .. c:function:: void PyString_InternInPlace(PyObject **string)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 Intern the argument *\*string* in place. The argument must be the address of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 pointer variable pointing to a Python string object. If there is an existing
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 interned string that is the same as *\*string*, it sets *\*string* to it
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 (decrementing the reference count of the old string object and incrementing the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 reference count of the interned string object), otherwise it leaves *\*string*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 alone and interns it (incrementing its reference count). (Clarification: even
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 though there is a lot of talk about reference counts, think of this function as
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 reference-count-neutral; you own the object after the call if and only if you
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 owned it before the call.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
258
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
259 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
260
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
261 This function is not available in 3.x and does not have a PyBytes alias.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
262
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
263
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
264 .. c:function:: PyObject* PyString_InternFromString(const char *v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
265
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
266 A combination of :c:func:`PyString_FromString` and
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
267 :c:func:`PyString_InternInPlace`, returning either a new string object that has
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 been interned, or a new ("owned") reference to an earlier interned string object
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 with the same value.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
270
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
271 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
272
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
273 This function is not available in 3.x and does not have a PyBytes alias.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
274
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
276 .. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
277
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 Create an object by decoding *size* bytes of the encoded buffer *s* using the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 codec registered for *encoding*. *encoding* and *errors* have the same meaning
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 as the parameters of the same name in the :func:`unicode` built-in function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 The codec to be used is looked up using the Python codec registry. Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 *NULL* if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
284 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
285
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
286 This function is not available in 3.x and does not have a PyBytes alias.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
287
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
288 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
289 This function used an :c:type:`int` type for *size*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
290 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
291
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
292
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
293 .. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
294
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 Decode a string object by passing it to the codec registered for *encoding* and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 return the result as Python object. *encoding* and *errors* have the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 meaning as the parameters of the same name in the string :meth:`encode` method.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
298 The codec to be used is looked up using the Python codec registry. Return *NULL*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
300
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
301 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
302
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
303 This function is not available in 3.x and does not have a PyBytes alias.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
304
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
305
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
306 .. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
307
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
308 Encode the :c:type:`char` buffer of the given size by passing it to the codec
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
309 registered for *encoding* and return a Python object. *encoding* and *errors*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 have the same meaning as the parameters of the same name in the string
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 :meth:`encode` method. The codec to be used is looked up using the Python codec
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 registry. Return *NULL* if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
313
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
314 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
315
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
316 This function is not available in 3.x and does not have a PyBytes alias.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
317
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
318 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
319 This function used an :c:type:`int` type for *size*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
320 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 47307
diff changeset
321
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
322
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
323 .. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
324
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 Encode a string object using the codec registered for *encoding* and return the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 result as Python object. *encoding* and *errors* have the same meaning as the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 parameters of the same name in the string :meth:`encode` method. The codec to be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 used is looked up using the Python codec registry. Return *NULL* if an exception
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 was raised by the codec.
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
330
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
331 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
332
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53588
diff changeset
333 This function is not available in 3.x and does not have a PyBytes alias.