###
7.3.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 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.

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 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.

Py_ssize_t `PyUnicode_Count`( | PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

  Return the number of non-overlapping occurrences of substr in `str[start:end]`. Return `-1` if an error occurred.

PyObject* `PyUnicode_Replace`( | PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t 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, 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.