7.2.1 String Objects

PyStringObject

This subtype of PyObject represents a Python string object.

PyTypeObject PyString_Type

This instance of PyTypeObject represents the Python string type.

int PyString_Check(PyObject *o)

Returns true if the object o is a string object.

PyObject* PyString_FromStringAndSize(const char *v, int len)

Returns a new string object with the value v and length len on success, and NULL on failure. If v is NULL, the contents of the string are uninitialized.

PyObject* PyString_FromString(const char *v)

Returns a new string object with the value v on success, and NULL on failure.

int PyString_Size(PyObject *string)

Returns the length of the string in string object string.

char* PyString_AsString(PyObject *string)

Resturns a NULL terminated representation of the contents of string.

void PyString_Concat(PyObject **string, PyObject *newpart)

Creates a new string object in *string containing the contents of newpart appended to string.

void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)

Creates a new string object in *string containing the contents of newpart appended to string. This version decrements the reference count of newpart.

int _PyString_Resize(PyObject **string, int newsize)

A way to resize a string object even though it is ``immutable''. Only use this to build up a brand new string object; don't use this if the string may already be known in other parts of the code.

PyObject* PyString_Format(PyObject *format, PyObject *args)

Returns a new string object from format and args. Analogous to format % args. The args argument must be a tuple.

void PyString_InternInPlace(PyObject **string)

Intern the argument *string in place. The argument must be the address of a pointer variable pointing to a Python string object. If there is an existing interned string that is the same as *string, it sets *string to it (decrementing the reference count of the old string object and incrementing the reference count of the interned string object), otherwise it leaves *string alone and interns it (incrementing its reference count). (Clarification: even though there is a lot of talk about reference counts, think of this function as reference-count-neutral; you own the object after the call if and only if you owned it before the call.)

PyObject* PyString_InternFromString(const char *v)

A combination of PyString_FromString() and PyString_InternInPlace(), returning either a new string object that has been interned, or a new (``owned'') reference to an earlier interned string object with the same value.

char* PyString_AS_STRING(PyObject *string)

Macro form of PyString_AsString() but without error checking.

int PyString_GET_SIZE(PyObject *string)

Macro form of PyString_GetSize() but without error checking.