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 appropriate.
They all return NULL or -1 if an exception occurs.
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,
Py_ssize_t 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 keepend)
Return value:New reference.
Split a Unicode string at line breaks, returning a list of Unicode
strings. CRLF is considered to be one line break. If keepend
is 0, the Line break characters are not included in the resulting
strings.
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 need only provide the __getitem__()
interface; dictionaries and sequences work well. 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.
int PyUnicode_Tailmatch(
PyObject *str,
PyObject *substr,
Py_ssize_t start,
Py_ssize_t 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.
Return -1 if an error occurred.
Py_ssize_t PyUnicode_Find(
PyObject *str,
PyObject *substr,
Py_ssize_t start,
Py_ssize_t end,
int direction)
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). The return value is the
index of the first match; a value of -1 indicates that no
match was found, and -2 indicates that an error occurred and
an exception has been set.
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, and
greater than, respectively.
int PyUnicode_RichCompare(
PyObject *left,
PyObject *right,
int op)
Rich compare two unicode strings and return one of the following:
NULL in case an exception was raised
Py_True or Py_False for successful comparisons
Py_NotImplemented in case the type combination is unknown
Note that Py_EQ and Py_NE comparisons can cause a
UnicodeWarning in case the conversion of the arguments to
Unicode fails with a UnicodeDecodeError.
Possible values for op are
Py_GT, Py_GE, Py_EQ,
Py_NE, Py_LT, and Py_LE.
PyObject* PyUnicode_Format(
PyObject *format,
PyObject *args)
Return value:New reference.
Return a new string object from format and args; this
is analogous to format % args. The
args argument must be a tuple.
int PyUnicode_Contains(
PyObject *container,
PyObject *element)
Check whether element is contained in container and
return true or false accordingly.
element has to coerce to a one element Unicode
string. -1 is returned if there was an error.
