<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"api.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"api.html" title='Python/C API Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"builtinCodecs.html" />
<link rel=
"parent" href=
"unicodeObjects.html" />
<link rel=
"next" href=
"bufferObjects.html" />
<meta name='aesop' content='information'
/>
<title>7.3.2.2 Methods and Slot Functions
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.2.1 Built-in Codecs"
href=
"builtinCodecs.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3.2 Unicode Objects"
href=
"unicodeObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.3.3 Buffer Objects"
href=
"bufferObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"builtinCodecs.html">7.3.2.1 Built-in Codecs
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"unicodeObjects.html">7.3.2 Unicode Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"bufferObjects.html">7.3.3 Buffer Objects
</A>
<!--End of Navigation Panel-->
<H3><A NAME=
"SECTION009322000000000000000"></A><A NAME=
"unicodeMethodsAndSlots"></A>
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
<tt class=
"constant">NULL
</tt> or
<code>-
1</code> if an exception occurs.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
536' xml:id='l2h-
536'
class=
"cfunction">PyUnicode_Concat
</tt></b>(
</nobr></td><td>PyObject *
<var>left
</var>,
PyObject *
<var>right
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Concat two strings giving a new Unicode string.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
537' xml:id='l2h-
537'
class=
"cfunction">PyUnicode_Split
</tt></b>(
</nobr></td><td>PyObject *
<var>s
</var>,
PyObject *
<var>sep
</var>,
int
<var>maxsplit
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Split a string giving a list of Unicode strings. If sep is
<tt class=
"constant">NULL
</tt>,
splitting will be done at all whitespace substrings. Otherwise,
splits occur at the given separator. At most
<var>maxsplit
</var> splits
will be done. If negative, no limit is set. Separators are not
included in the resulting list.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
538' xml:id='l2h-
538'
class=
"cfunction">PyUnicode_Splitlines
</tt></b>(
</nobr></td><td>PyObject *
<var>s
</var>,
int
<var>keepend
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Split a Unicode string at line breaks, returning a list of Unicode
strings. CRLF is considered to be one line break. If
<var>keepend
</var>
is
0, the Line break characters are not included in the resulting
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
539' xml:id='l2h-
539'
class=
"cfunction">PyUnicode_Translate
</tt></b>(
</nobr></td><td>PyObject *
<var>str
</var>,
PyObject *
<var>table
</var>,
const char *
<var>errors
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
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
<tt class=
"method">__getitem__()
</tt>
interface; dictionaries and sequences work well. Unmapped character
ordinals (ones which cause a
<tt class=
"exception">LookupError
</tt>) are left
untouched and are copied as-is.
<var>errors
</var> has the usual meaning for codecs. It may be
<tt class=
"constant">NULL
</tt>
which indicates to use the default error handling.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
540' xml:id='l2h-
540'
class=
"cfunction">PyUnicode_Join
</tt></b>(
</nobr></td><td>PyObject *
<var>separator
</var>,
PyObject *
<var>seq
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Join a sequence of strings using the given separator and return the
resulting Unicode string.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
541' xml:id='l2h-
541'
class=
"cfunction">PyUnicode_Tailmatch
</tt></b>(
</nobr></td><td>PyObject *
<var>str
</var>,
PyObject *
<var>substr
</var>,
int
<var>direction
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return
1 if
<var>substr
</var> matches
<var>str
</var>[
<var>start
</var>:
<var>end
</var>] at
the given tail end (
<var>direction
</var> == -
1 means to do a prefix
match,
<var>direction
</var> ==
1 a suffix match),
0 otherwise.
Return
<code>-
1</code> if an error occurred.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
542' xml:id='l2h-
542'
class=
"cfunction">PyUnicode_Find
</tt></b>(
</nobr></td><td>PyObject *
<var>str
</var>,
PyObject *
<var>substr
</var>,
int
<var>direction
</var>)
</td></tr></table></dt>
Return the first position of
<var>substr
</var> in
<var>str
</var>[
<var>start
</var>:
<var>end
</var>] using the given
<var>direction
</var>
(
<var>direction
</var> ==
1 means to do a forward search,
<var>direction
</var> == -
1 a backward search). The return value is the
index of the first match; a value of
<code>-
1</code> indicates that no
match was found, and
<code>-
2</code> indicates that an error occurred and
an exception has been set.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
543' xml:id='l2h-
543'
class=
"cfunction">PyUnicode_Count
</tt></b>(
</nobr></td><td>PyObject *
<var>str
</var>,
PyObject *
<var>substr
</var>,
int
<var>end
</var>)
</td></tr></table></dt>
Return the number of non-overlapping occurrences of
<var>substr
</var> in
<code><var>str
</var>[
<var>start
</var>:
<var>end
</var>]
</code>. Return
<code>-
1</code> if an
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
544' xml:id='l2h-
544'
class=
"cfunction">PyUnicode_Replace
</tt></b>(
</nobr></td><td>PyObject *
<var>str
</var>,
PyObject *
<var>substr
</var>,
PyObject *
<var>replstr
</var>,
int
<var>maxcount
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Replace at most
<var>maxcount
</var> occurrences of
<var>substr
</var> in
<var>str
</var> with
<var>replstr
</var> and return the resulting Unicode object.
<var>maxcount
</var> == -
1 means replace all occurrences.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
545' xml:id='l2h-
545'
class=
"cfunction">PyUnicode_Compare
</tt></b>(
</nobr></td><td>PyObject *
<var>left
</var>, PyObject *
<var>right
</var>)
</td></tr></table></dt>
Compare two strings and return -
1,
0,
1 for less than, equal, and
greater than, respectively.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
546' xml:id='l2h-
546'
class=
"cfunction">PyUnicode_Format
</tt></b>(
</nobr></td><td>PyObject *
<var>format
</var>,
PyObject *
<var>args
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new string object from
<var>format
</var> and
<var>args
</var>; this
is analogous to
<code><var>format
</var> %
<var>args
</var></code>. The
<var>args
</var> argument must be a tuple.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
547' xml:id='l2h-
547'
class=
"cfunction">PyUnicode_Contains
</tt></b>(
</nobr></td><td>PyObject *
<var>container
</var>,
PyObject *
<var>element
</var>)
</td></tr></table></dt>
Check whether
<var>element
</var> is contained in
<var>container
</var> and
return true or false accordingly.
<var>element
</var> has to coerce to a one element Unicode
string.
<code>-
1</code> is returned if there was an error.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.2.1 Built-in Codecs"
href=
"builtinCodecs.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3.2 Unicode Objects"
href=
"unicodeObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.3.3 Buffer Objects"
href=
"bufferObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"builtinCodecs.html">7.3.2.1 Built-in Codecs
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"unicodeObjects.html">7.3.2 Unicode Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"bufferObjects.html">7.3.3 Buffer Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.