| blob | 2fb350201539f5761b4276003c443daa741a7f28 |
1 from cpython.ref cimport PyObject
3 cdef extern from "Python.h":
4 ctypedef struct va_list
6 ############################################################################
7 # 7.3.1 String Objects
8 ############################################################################
10 # These functions raise TypeError when expecting a string
11 # parameter and are called with a non-string parameter.
12 # PyStringObject
13 # This subtype of PyObject represents a Python bytes object.
14 # PyTypeObject PyBytes_Type
15 # This instance of PyTypeObject represents the Python bytes type;
16 # it is the same object as bytes and types.BytesType in the Python
17 # layer.
19 bint PyBytes_Check(object o)
20 # Return true if the object o is a string object or an instance of
21 # a subtype of the string type.
23 bint PyBytes_CheckExact(object o)
24 # Return true if the object o is a string object, but not an instance of a subtype of the string type.
26 bytes PyBytes_FromString(char *v)
27 # Return value: New reference.
28 # Return a new string object with the value v on success, and NULL
29 # on failure. The parameter v must not be NULL; it will not be
30 # checked.
32 bytes PyBytes_FromStringAndSize(char *v, Py_ssize_t len)
33 # Return value: New reference.
34 # Return a new string object with the value v and length len on
35 # success, and NULL on failure. If v is NULL, the contents of the
36 # string are uninitialized.
38 bytes PyBytes_FromFormat(char *format, ...)
39 # Return value: New reference.
40 # Take a C printf()-style format string and a variable number of
41 # arguments, calculate the size of the resulting Python string and
42 # return a string with the values formatted into it. The variable
43 # arguments must be C types and must correspond exactly to the
44 # format characters in the format string. The following format
45 # characters are allowed:
46 # Format Characters Type Comment
47 # %% n/a The literal % character.
48 # %c int A single character, represented as an C int.
49 # %d int Exactly equivalent to printf("%d").
50 # %u unsigned int Exactly equivalent to printf("%u").
51 # %ld long Exactly equivalent to printf("%ld").
52 # %lu unsigned long Exactly equivalent to printf("%lu").
53 # %zd Py_ssize_t Exactly equivalent to printf("%zd").
54 # %zu size_t Exactly equivalent to printf("%zu").
55 # %i int Exactly equivalent to printf("%i").
56 # %x int Exactly equivalent to printf("%x").
57 # %s char* A null-terminated C character array.
59 # %p void* The hex representation of a C pointer.
60 # Mostly equivalent to printf("%p") except that it is guaranteed to
61 # start with the literal 0x regardless of what the platform's printf
62 # yields.
63 # An unrecognized format character causes all the rest of the
64 # format string to be copied as-is to the result string, and any
65 # extra arguments discarded.
67 bytes PyBytes_FromFormatV(char *format, va_list vargs)
68 # Return value: New reference.
69 # Identical to PyBytes_FromFormat() except that it takes exactly two arguments.
71 Py_ssize_t PyBytes_Size(object string) except -1
72 # Return the length of the string in string object string.
74 Py_ssize_t PyBytes_GET_SIZE(object string)
75 # Macro form of PyBytes_Size() but without error checking.
77 char* PyBytes_AsString(object string) except NULL
78 # Return a NUL-terminated representation of the contents of
79 # string. The pointer refers to the internal buffer of string, not
80 # a copy. The data must not be modified in any way, unless the
81 # string was just created using PyBytes_FromStringAndSize(NULL,
82 # size). It must not be deallocated. If string is a Unicode
83 # object, this function computes the default encoding of string
84 # and operates on that. If string is not a string object at all,
85 # PyBytes_AsString() returns NULL and raises TypeError.
87 char* PyBytes_AS_STRING(object string)
88 # Macro form of PyBytes_AsString() but without error
89 # checking. Only string objects are supported; no Unicode objects
90 # should be passed.
92 int PyBytes_AsStringAndSize(object obj, char **buffer, Py_ssize_t *length) except -1
93 # Return a NULL-terminated representation of the contents of the
94 # object obj through the output variables buffer and length.
95 #
96 # The function accepts both string and Unicode objects as
97 # input. For Unicode objects it returns the default encoded
98 # version of the object. If length is NULL, the resulting buffer
99 # may not contain NUL characters; if it does, the function returns
100 # -1 and a TypeError is raised.
102 # The buffer refers to an internal string buffer of obj, not a
103 # copy. The data must not be modified in any way, unless the
104 # string was just created using PyBytes_FromStringAndSize(NULL,
105 # size). It must not be deallocated. If string is a Unicode
106 # object, this function computes the default encoding of string
107 # and operates on that. If string is not a string object at all,
108 # PyBytes_AsStringAndSize() returns -1 and raises TypeError.
110 void PyBytes_Concat(PyObject **string, object newpart)
111 # Create a new string object in *string containing the contents of
112 # newpart appended to string; the caller will own the new
113 # reference. The reference to the old value of string will be
114 # stolen. If the new string cannot be created, the old reference
115 # to string will still be discarded and the value of *string will
116 # be set to NULL; the appropriate exception will be set.
118 void PyBytes_ConcatAndDel(PyObject **string, object newpart)
119 # Create a new string object in *string containing the contents of
120 # newpart appended to string. This version decrements the
121 # reference count of newpart.
123 int _PyBytes_Resize(PyObject **string, Py_ssize_t newsize) except -1
124 # A way to resize a string object even though it is
125 # ``immutable''. Only use this to build up a brand new string
126 # object; don't use this if the string may already be known in
127 # other parts of the code. It is an error to call this function if
128 # the refcount on the input string object is not one. Pass the
129 # address of an existing string object as an lvalue (it may be
130 # written into), and the new size desired. On success, *string
131 # holds the resized string object and 0 is returned; the address
132 # in *string may differ from its input value. If the reallocation
133 # fails, the original string object at *string is deallocated,
134 # *string is set to NULL, a memory exception is set, and -1 is
135 # returned.
137 bytes PyBytes_Format(object format, object args)
138 # Return value: New reference. Return a new string object from
139 # format and args. Analogous to format % args. The args argument
140 # must be a tuple.
142 void PyBytes_InternInPlace(PyObject **string)
143 # Intern the argument *string in place. The argument must be the
144 # address of a pointer variable pointing to a Python string
145 # object. If there is an existing interned string that is the same
146 # as *string, it sets *string to it (decrementing the reference
147 # count of the old string object and incrementing the reference
148 # count of the interned string object), otherwise it leaves
149 # *string alone and interns it (incrementing its reference
150 # count). (Clarification: even though there is a lot of talk about
151 # reference counts, think of this function as
152 # reference-count-neutral; you own the object after the call if
153 # and only if you owned it before the call.)
155 bytes PyBytes_InternFromString(char *v)
156 # Return value: New reference.
157 # A combination of PyBytes_FromString() and
158 # PyBytes_InternInPlace(), returning either a new string object
159 # that has been interned, or a new (``owned'') reference to an
160 # earlier interned string object with the same value.
162 object PyBytes_Decode(char *s, Py_ssize_t size, char *encoding, char *errors)
163 # Return value: New reference.
164 # Create an object by decoding size bytes of the encoded buffer s
165 # using the codec registered for encoding. encoding and errors
166 # have the same meaning as the parameters of the same name in the
167 # unicode() built-in function. The codec to be used is looked up
168 # using the Python codec registry. Return NULL if an exception was
169 # raised by the codec.
171 object PyBytes_AsDecodedObject(object str, char *encoding, char *errors)
172 # Return value: New reference.
173 # Decode a string object by passing it to the codec registered for
174 # encoding and return the result as Python object. encoding and
175 # errors have the same meaning as the parameters of the same name
176 # in the string encode() method. The codec to be used is looked up
177 # using the Python codec registry. Return NULL if an exception was
178 # raised by the codec.
180 object PyBytes_Encode(char *s, Py_ssize_t size, char *encoding, char *errors)
181 # Return value: New reference.
182 # Encode the char buffer of the given size by passing it to the
183 # codec registered for encoding and return a Python
184 # object. encoding and errors have the same meaning as the
185 # parameters of the same name in the string encode() method. The
186 # codec to be used is looked up using the Python codec
187 # registry. Return NULL if an exception was raised by the codec.
189 object PyBytes_AsEncodedObject(object str, char *encoding, char *errors)
190 # Return value: New reference.
191 # Encode a string object using the codec registered for encoding
192 # and return the result as Python object. encoding and errors have
193 # the same meaning as the parameters of the same name in the
194 # string encode() method. The codec to be used is looked up using
195 # the Python codec registry. Return NULL if an exception was
196 # raised by the codec.