String/Bytes Objects¶

These functions raiseTypeError when expecting a string parameter and arecalled with a non-string parameter.

PyStringObject¶

This subtype ofPyObject represents a Python string object.

PyTypeObjectPyString_Type¶

This instance ofPyTypeObject represents the Python string type; it isthe same object asstr andtypes.StringType in the Python layer. .

intPyString_Check(PyObject *o)¶

Return true if the objecto is a string object or an instance of a subtype ofthe string type.

Changed in version 2.2:Allowed subtypes to be accepted.

intPyString_CheckExact(PyObject *o)¶

Return true if the objecto is a string object, but not an instance of asubtype of the string type.

New in version 2.2.

PyObject*PyString_FromString(const char *v)¶

Return value: New reference.

Return a new string object with a copy of the stringv as value on success,andNULL on failure. The parameterv must not beNULL; it will not bechecked.

PyObject*PyString_FromStringAndSize(const char *v, Py_ssize_t len)¶

Return value: New reference.

Return a new string object with a copy of the stringv as value and lengthlen on success, andNULL on failure. Ifv isNULL, the contents of thestring are uninitialized.

Changed in version 2.5:This function used anint type forlen. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyString_FromFormat(const char *format, ...)¶

Return value: New reference.

Take a Cprintf()-styleformat string and a variable number ofarguments, calculate the size of the resulting Python string and return a stringwith the values formatted into it. The variable arguments must be C types andmust correspond exactly to the format characters in theformat string. Thefollowing format characters are allowed:

Format Characters	Type	Comment
%%	n/a	The literal % character.
%c	int	A single character,represented as a C int.
%d	int	Exactly equivalent toprintf("%d").
%u	unsigned int	Exactly equivalent toprintf("%u").
%ld	long	Exactly equivalent toprintf("%ld").
%lu	unsigned long	Exactly equivalent toprintf("%lu").
%lld	long long	Exactly equivalent toprintf("%lld").
%llu	unsignedlong long	Exactly equivalent toprintf("%llu").
%zd	Py_ssize_t	Exactly equivalent toprintf("%zd").
%zu	size_t	Exactly equivalent toprintf("%zu").
%i	int	Exactly equivalent toprintf("%i").
%x	int	Exactly equivalent toprintf("%x").
%s	char*	A null-terminated C characterarray.
%p	void*	The hex representation of a Cpointer. Mostly equivalent toprintf("%p") except thatit is guaranteed to start withthe literal0x regardlessof what the platform’sprintf yields.

An unrecognized format character causes all the rest of the format string to becopied as-is to the result string, and any extra arguments discarded.

Note

The“%lld” and“%llu” format specifiers are only availablewhenHAVE_LONG_LONG is defined.

Changed in version 2.7:Support for“%lld” and“%llu” added.

PyObject*PyString_FromFormatV(const char *format, va_list vargs)¶

Return value: New reference.

Identical toPyString_FromFormat() except that it takes exactly twoarguments.

Py_ssize_tPyString_Size(PyObject *string)¶

Return the length of the string in string objectstring.

Changed in version 2.5:This function returned anint type. This might require changesin your code for properly supporting 64-bit systems.

Py_ssize_tPyString_GET_SIZE(PyObject *string)¶

Macro form ofPyString_Size() but without error checking.

Changed in version 2.5:This macro returned anint type. This might require changes inyour code for properly supporting 64-bit systems.

char*PyString_AsString(PyObject *string)¶

Return a NUL-terminated representation of the contents ofstring. The pointerrefers to the internal buffer ofstring, not a copy. The data must not bemodified in any way, unless the string was just created usingPyString_FromStringAndSize(NULL,size). It must not be deallocated. Ifstring is a Unicode object, this function computes the default encoding ofstring and operates on that. Ifstring is not a string object at all,PyString_AsString() returnsNULL and raisesTypeError.

char*PyString_AS_STRING(PyObject *string)¶

Macro form ofPyString_AsString() but without error checking. Onlystring objects are supported; no Unicode objects should be passed.

intPyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶

Return a NUL-terminated representation of the contents of the objectobjthrough the output variablesbuffer andlength.

The function accepts both string and Unicode objects as input. For Unicodeobjects it returns the default encoded version of the object. Iflength isNULL, the resulting buffer may not contain NUL characters; if it does, thefunction returns-1 and aTypeError is raised.

The buffer refers to an internal string buffer ofobj, not a copy. The datamust not be modified in any way, unless the string was just created usingPyString_FromStringAndSize(NULL,size). It must not be deallocated. Ifstring is a Unicode object, this function computes the default encoding ofstring and operates on that. Ifstring is not a string object at all,PyString_AsStringAndSize() returns-1 and raisesTypeError.

Changed in version 2.5:This function used anint* type forlength. This mightrequire changes in your code for properly supporting 64-bit systems.

voidPyString_Concat(PyObject **string,PyObject *newpart)¶

Create a new string object in*string containing the contents ofnewpartappended tostring; the caller will own the new reference. The reference tothe old value ofstring will be stolen. If the new string cannot be created,the old reference tostring will still be discarded and the value of*string will be set toNULL; the appropriate exception will be set.

voidPyString_ConcatAndDel(PyObject **string,PyObject *newpart)¶

Create a new string object in*string containing the contents ofnewpartappended tostring. This version decrements the reference count ofnewpart.

int_PyString_Resize(PyObject **string, Py_ssize_t newsize)¶

A way to resize a string object even though it is “immutable”. Only use this tobuild up a brand new string object; don’t use this if the string may already beknown in other parts of the code. It is an error to call this function if therefcount on the input string object is not one. Pass the address of an existingstring object as an lvalue (it may be written into), and the new size desired.On success,*string holds the resized string object and0 is returned;the address in*string may differ from its input value. If the reallocationfails, the original string object at*string is deallocated,*string isset toNULL, a memory exception is set, and-1 is returned.

Changed in version 2.5:This function used anint type fornewsize. This mightrequire changes in your code for properly supporting 64-bit systems.

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

Return value: New reference.

Return a new string object fromformat andargs. Analogous toformat%args. Theargs argument must be a tuple or dict.

voidPyString_InternInPlace(PyObject **string)¶

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

Note

This function is not available in 3.x and does not have a PyBytes alias.

PyObject*PyString_InternFromString(const char *v)¶

Return value: New reference.

A combination ofPyString_FromString() andPyString_InternInPlace(), returning either a new string object that hasbeen interned, or a new (“owned”) reference to an earlier interned string objectwith the same value.

Note

This function is not available in 3.x and does not have a PyBytes alias.

PyObject*PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶

Return value: New reference.

Create an object by decodingsize bytes of the encoded buffers using thecodec registered forencoding.encoding anderrors have the same meaningas the parameters of the same name in theunicode() built-in function.The codec to be used is looked up using the Python codec registry. ReturnNULL if an exception was raised by the codec.

Note

This function is not available in 3.x and does not have a PyBytes alias.

Changed in version 2.5:This function used anint type forsize. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)¶

Return value: New reference.

Decode a string object by passing it to the codec registered forencoding andreturn the result as Python object.encoding anderrors have the samemeaning as the parameters of the same name in the stringencode() method.The codec to be used is looked up using the Python codec registry. ReturnNULLif an exception was raised by the codec.

Note

This function is not available in 3.x and does not have a PyBytes alias.

PyObject*PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶

Return value: New reference.

Encode thechar buffer of the given size by passing it to the codecregistered forencoding and return a Python object.encoding anderrorshave the same meaning as the parameters of the same name in the stringencode() method. The codec to be used is looked up using the Python codecregistry. ReturnNULL if an exception was raised by the codec.

Note

This function is not available in 3.x and does not have a PyBytes alias.

Changed in version 2.5:This function used anint type forsize. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)¶

Return value: New reference.

Encode a string object using the codec registered forencoding and return theresult as Python object.encoding anderrors have the same meaning as theparameters of the same name in the stringencode() method. The codec to beused is looked up using the Python codec registry. ReturnNULL if an exceptionwas raised by the codec.

Note

This function is not available in 3.x and does not have a PyBytes alias.