7.2.2.2 Methods and Slot Functions

The following APIs are capable of handling Unicode objects and strings on input (we refer to them as strings in the descriptions) and return Unicode objects or integers as apporpriate.

They all return NULL or -1 in case an exception occurrs.

PyObject* PyUnicode_Concat (PyObject *left, PyObject *right): Return value: New reference.

Concat two strings giving a new Unicode string.

PyObject* PyUnicode_Split (PyObject *s, PyObject *sep, int maxsplit)

Return value: New reference.

Split a string giving a list of Unicode strings.

If sep is NULL, splitting will be done at all whitespace substrings. Otherwise, splits occur at the given separator.

At most maxsplit splits will be done. If negative, no limit is set.

Separators are not included in the resulting list.

PyObject* PyUnicode_Splitlines (PyObject *s, int maxsplit)

Return value: New reference.

Dito, but split at line breaks.

CRLF is considered to be one line break. Line breaks are not included in the resulting list.

PyObject* PyUnicode_Translate (PyObject *str, PyObject *table, const char *errors)

Return value: New reference.

Translate a string by applying a character mapping table to it and return the resulting Unicode object.

The mapping table must map Unicode ordinal integers to Unicode ordinal integers or None (causing deletion of the character).

Mapping tables must only provide the __getitem__ interface, e.g. dictionaries or sequences. Unmapped character ordinals (ones which cause a LookupError) are left untouched and are copied as-is.

errors has the usual meaning for codecs. It may be NULL which indicates to use the default error handling.

PyObject* PyUnicode_Join (PyObject *separator, PyObject *seq): Return value: New reference.

Join a sequence of strings using the given separator and return the resulting Unicode string.

PyObject* PyUnicode_Tailmatch (PyObject *str, PyObject *substr, int start, int end, int direction): Return value: New reference.

Return 1 if substr matches str[start:end] at the given tail end (direction == -1 means to do a prefix match, direction == 1 a suffix match), 0 otherwise.

PyObject* PyUnicode_Find (PyObject *str, PyObject *substr, int start, int end, int direction): Return value: New reference.

Return the first position of substr in str[start:end] using the given direction (direction == 1 means to do a forward search, direction == -1 a backward search), 0 otherwise.

PyObject* PyUnicode_Count (PyObject *str, PyObject *substr, int start, int end): Return value: New reference.

Count the number of occurrences of substr in str[start:end]

PyObject* PyUnicode_Replace (PyObject *str, PyObject *substr, PyObject *replstr, int maxcount): Return value: New reference.

Replace at most maxcount occurrences of substr in str with replstr and return the resulting Unicode object. maxcount == -1 means: replace all occurrences.

int PyUnicode_Compare (PyObject *left, PyObject *right): Compare two strings and return -1, 0, 1 for less than, equal, greater than resp.

PyObject* PyUnicode_Format (PyObject *format, PyObject *args): Return value: New reference.
Returns a new string object from format and args. Analogous to format % args. The args argument must be a tuple.

int PyUnicode_Contains (PyObject *container, PyObject *element)

Checks whether element is contained in container and returns 1/0 accordingly.

element has to coerce to an one element Unicode string. -1 is returned in case of an error.

See About this document... for information on suggesting changes.