src/third_party/cython/src/Cython/Includes/cpython/string.pxd

   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