1 from cpython.ref cimport PyObject 2 3 cdef extern from "Python.h": 4 ctypedef struct va_list 5 6 ############################################################################ 7 # 7.3.1 String Objects 8 ############################################################################ 9 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 string object. 14 # PyTypeObject PyString_Type 15 # This instance of PyTypeObject represents the Python string type; 16 # it is the same object as str and types.StringType in the Python 17 # layer. 18 19 bint PyString_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. 22 23 bint PyString_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. 25 26 object PyString_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. 31 32 object PyString_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. 37 38 object PyString_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. 58 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. 66 67 object PyString_FromFormatV(char *format, va_list vargs) 68 # Return value: New reference. 69 # Identical to PyString_FromFormat() except that it takes exactly two arguments. 70 71 Py_ssize_t PyString_Size(object string) except -1 72 # Return the length of the string in string object string. 73 74 Py_ssize_t PyString_GET_SIZE(object string) 75 # Macro form of PyString_Size() but without error checking. 76 77 char* PyString_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 PyString_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 # PyString_AsString() returns NULL and raises TypeError. 86 87 char* PyString_AS_STRING(object string) 88 # Macro form of PyString_AsString() but without error 89 # checking. Only string objects are supported; no Unicode objects 90 # should be passed. 91 92 int PyString_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. 101 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 PyString_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 # PyString_AsStringAndSize() returns -1 and raises TypeError. 109 110 void PyString_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. 117 118 void PyString_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. 122 123 int _PyString_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. 136 137 object PyString_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. 141 142 void PyString_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.) 154 155 object PyString_InternFromString(char *v) 156 # Return value: New reference. 157 # A combination of PyString_FromString() and 158 # PyString_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. 161 162 object PyString_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. 170 171 object PyString_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. 179 180 object PyString_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. 188 189 object PyString_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. 197 198 199
