| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="api.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="api.html" title='Python/C API Reference Manual' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="unicodeObjects.html" /> |
| 13 | <link rel="prev" href="sequenceObjects.html" /> |
| 14 | <link rel="parent" href="sequenceObjects.html" /> |
| 15 | <link rel="next" href="unicodeObjects.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>7.3.1 String Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="7.3 Sequence Objects" |
| 25 | href="sequenceObjects.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="7.3 Sequence Objects" |
| 28 | href="sequenceObjects.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="7.3.2 Unicode Objects" |
| 31 | href="unicodeObjects.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><img src='../icons/blank.png' |
| 38 | border='0' height='32' alt='' width='32' /></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="unicodeObjects.html">7.3.2 Unicode Objects</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION009310000000000000000"></A><A NAME="stringObjects"></A> |
| 56 | <BR> |
| 57 | 7.3.1 String Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | These functions raise <tt class="exception">TypeError</tt> when expecting a string |
| 62 | parameter and are called with a non-string parameter. |
| 63 | |
| 64 | <P> |
| 65 | <a id='l2h-448' xml:id='l2h-448'></a><dl><dt><b><tt class="ctype"><a id='l2h-449' xml:id='l2h-449'>PyStringObject</a></tt></b></dt> |
| 66 | <dd> |
| 67 | This subtype of <tt class="ctype">PyObject</tt> represents a Python string object. |
| 68 | </dl> |
| 69 | |
| 70 | <P> |
| 71 | <dl><dt>PyTypeObject <b><tt id='l2h-450' xml:id='l2h-450' class="cdata">PyString_Type</tt></b></dt> |
| 72 | <dd> |
| 73 | This instance of <tt class="ctype">PyTypeObject</tt> represents the Python string |
| 74 | type; it is the same object as <code>types.TypeType</code> in the Python |
| 75 | layer. |
| 76 | <a id='l2h-452' xml:id='l2h-452'></a>. |
| 77 | </dd></dl> |
| 78 | |
| 79 | <P> |
| 80 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-453' xml:id='l2h-453' class="cfunction">PyString_Check</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 81 | <dd> |
| 82 | Return true if the object <var>o</var> is a string object or an instance |
| 83 | of a subtype of the string type. |
| 84 | |
| 85 | <span class="versionnote">Changed in version 2.2: |
| 86 | Allowed subtypes to be accepted.</span> |
| 87 | |
| 88 | </dd></dl> |
| 89 | |
| 90 | <P> |
| 91 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-454' xml:id='l2h-454' class="cfunction">PyString_CheckExact</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 92 | <dd> |
| 93 | Return true if the object <var>o</var> is a string object, but not an |
| 94 | instance of a subtype of the string type. |
| 95 | |
| 96 | <span class="versionnote">New in version 2.2.</span> |
| 97 | |
| 98 | </dd></dl> |
| 99 | |
| 100 | <P> |
| 101 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-455' xml:id='l2h-455' class="cfunction">PyString_FromString</tt></b>(</nobr></td><td>const char *<var>v</var>)</td></tr></table></dt> |
| 102 | <dd> |
| 103 | <div class="refcount-info"> |
| 104 | <span class="label">Return value:</span> |
| 105 | <span class="value">New reference.</span> |
| 106 | </div> |
| 107 | Return a new string object with the value <var>v</var> on success, and |
| 108 | <tt class="constant">NULL</tt> on failure. The parameter <var>v</var> must not be <tt class="constant">NULL</tt>; it |
| 109 | will not be checked. |
| 110 | </dd></dl> |
| 111 | |
| 112 | <P> |
| 113 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-456' xml:id='l2h-456' class="cfunction">PyString_FromStringAndSize</tt></b>(</nobr></td><td>const char *<var>v</var>, |
| 114 | int <var>len</var>)</td></tr></table></dt> |
| 115 | <dd> |
| 116 | <div class="refcount-info"> |
| 117 | <span class="label">Return value:</span> |
| 118 | <span class="value">New reference.</span> |
| 119 | </div> |
| 120 | Return a new string object with the value <var>v</var> and length |
| 121 | <var>len</var> on success, and <tt class="constant">NULL</tt> on failure. If <var>v</var> is |
| 122 | <tt class="constant">NULL</tt>, the contents of the string are uninitialized. |
| 123 | </dd></dl> |
| 124 | |
| 125 | <P> |
| 126 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-457' xml:id='l2h-457' class="cfunction">PyString_FromFormat</tt></b>(</nobr></td><td>const char *<var>format</var>, ...)</td></tr></table></dt> |
| 127 | <dd> |
| 128 | <div class="refcount-info"> |
| 129 | <span class="label">Return value:</span> |
| 130 | <span class="value">New reference.</span> |
| 131 | </div> |
| 132 | Take a C <tt class="cfunction">printf()</tt>-style <var>format</var> string and a |
| 133 | variable number of arguments, calculate the size of the resulting |
| 134 | Python string and return a string with the values formatted into |
| 135 | it. The variable arguments must be C types and must correspond |
| 136 | exactly to the format characters in the <var>format</var> string. The |
| 137 | following format characters are allowed: |
| 138 | |
| 139 | <P> |
| 140 | <div class="center"><table class="realtable"> |
| 141 | <thead> |
| 142 | <tr> |
| 143 | <th class="left" >Format Characters</th> |
| 144 | <th class="left" >Type</th> |
| 145 | <th class="left" >Comment</th> |
| 146 | </tr> |
| 147 | </thead> |
| 148 | <tbody> |
| 149 | <tr><td class="left" valign="baseline"><tt class="member">%%</tt></td> |
| 150 | <td class="left" ><em>n/a</em></td> |
| 151 | <td class="left" >The literal % character.</td></tr> |
| 152 | <tr><td class="left" valign="baseline"><tt class="member">%c</tt></td> |
| 153 | <td class="left" >int</td> |
| 154 | <td class="left" >A single character, represented as an C int.</td></tr> |
| 155 | <tr><td class="left" valign="baseline"><tt class="member">%d</tt></td> |
| 156 | <td class="left" >int</td> |
| 157 | <td class="left" >Exactly equivalent to <code>printf("%d")</code>.</td></tr> |
| 158 | <tr><td class="left" valign="baseline"><tt class="member">%ld</tt></td> |
| 159 | <td class="left" >long</td> |
| 160 | <td class="left" >Exactly equivalent to <code>printf("%ld")</code>.</td></tr> |
| 161 | <tr><td class="left" valign="baseline"><tt class="member">%i</tt></td> |
| 162 | <td class="left" >int</td> |
| 163 | <td class="left" >Exactly equivalent to <code>printf("%i")</code>.</td></tr> |
| 164 | <tr><td class="left" valign="baseline"><tt class="member">%x</tt></td> |
| 165 | <td class="left" >int</td> |
| 166 | <td class="left" >Exactly equivalent to <code>printf("%x")</code>.</td></tr> |
| 167 | <tr><td class="left" valign="baseline"><tt class="member">%s</tt></td> |
| 168 | <td class="left" >char*</td> |
| 169 | <td class="left" >A null-terminated C character array.</td></tr> |
| 170 | <tr><td class="left" valign="baseline"><tt class="member">%p</tt></td> |
| 171 | <td class="left" >void*</td> |
| 172 | <td class="left" >The hex representation of a C pointer. |
| 173 | Mostly equivalent to <code>printf("%p")</code> except that it is |
| 174 | guaranteed to start with the literal <code>0x</code> regardless of |
| 175 | what the platform's <code>printf</code> yields.</td></tr></tbody> |
| 176 | </table></div> |
| 177 | </dd></dl> |
| 178 | |
| 179 | <P> |
| 180 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-458' xml:id='l2h-458' class="cfunction">PyString_FromFormatV</tt></b>(</nobr></td><td>const char *<var>format</var>, |
| 181 | va_list <var>vargs</var>)</td></tr></table></dt> |
| 182 | <dd> |
| 183 | <div class="refcount-info"> |
| 184 | <span class="label">Return value:</span> |
| 185 | <span class="value">New reference.</span> |
| 186 | </div> |
| 187 | Identical to <tt class="function">PyString_FromFormat()</tt> except that it takes |
| 188 | exactly two arguments. |
| 189 | </dd></dl> |
| 190 | |
| 191 | <P> |
| 192 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-459' xml:id='l2h-459' class="cfunction">PyString_Size</tt></b>(</nobr></td><td>PyObject *<var>string</var>)</td></tr></table></dt> |
| 193 | <dd> |
| 194 | Return the length of the string in string object <var>string</var>. |
| 195 | </dd></dl> |
| 196 | |
| 197 | <P> |
| 198 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-460' xml:id='l2h-460' class="cfunction">PyString_GET_SIZE</tt></b>(</nobr></td><td>PyObject *<var>string</var>)</td></tr></table></dt> |
| 199 | <dd> |
| 200 | Macro form of <tt class="cfunction">PyString_Size()</tt> but without error |
| 201 | checking. |
| 202 | </dd></dl> |
| 203 | |
| 204 | <P> |
| 205 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>char* <b><tt id='l2h-461' xml:id='l2h-461' class="cfunction">PyString_AsString</tt></b>(</nobr></td><td>PyObject *<var>string</var>)</td></tr></table></dt> |
| 206 | <dd> |
| 207 | Return a NUL-terminated representation of the contents of |
| 208 | <var>string</var>. The pointer refers to the internal buffer of |
| 209 | <var>string</var>, not a copy. The data must not be modified in any way, |
| 210 | unless the string was just created using |
| 211 | <code>PyString_FromStringAndSize(NULL, <var>size</var>)</code>. |
| 212 | It must not be deallocated. If <var>string</var> is a Unicode object, |
| 213 | this function computes the default encoding of <var>string</var> and |
| 214 | operates on that. If <var>string</var> is not a string object at all, |
| 215 | <tt class="cfunction">PyString_AsString()</tt> returns <tt class="constant">NULL</tt> and raises |
| 216 | <tt class="exception">TypeError</tt>. |
| 217 | </dd></dl> |
| 218 | |
| 219 | <P> |
| 220 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>char* <b><tt id='l2h-462' xml:id='l2h-462' class="cfunction">PyString_AS_STRING</tt></b>(</nobr></td><td>PyObject *<var>string</var>)</td></tr></table></dt> |
| 221 | <dd> |
| 222 | Macro form of <tt class="cfunction">PyString_AsString()</tt> but without error |
| 223 | checking. Only string objects are supported; no Unicode objects |
| 224 | should be passed. |
| 225 | </dd></dl> |
| 226 | |
| 227 | <P> |
| 228 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-463' xml:id='l2h-463' class="cfunction">PyString_AsStringAndSize</tt></b>(</nobr></td><td>PyObject *<var>obj</var>, |
| 229 | char **<var>buffer</var>, |
| 230 | int *<var>length</var>)</td></tr></table></dt> |
| 231 | <dd> |
| 232 | Return a NUL-terminated representation of the contents of the |
| 233 | object <var>obj</var> through the output variables <var>buffer</var> and |
| 234 | <var>length</var>. |
| 235 | |
| 236 | <P> |
| 237 | The function accepts both string and Unicode objects as input. For |
| 238 | Unicode objects it returns the default encoded version of the |
| 239 | object. If <var>length</var> is <tt class="constant">NULL</tt>, the resulting buffer may not |
| 240 | contain NUL characters; if it does, the function returns <code>-1</code> |
| 241 | and a <tt class="exception">TypeError</tt> is raised. |
| 242 | |
| 243 | <P> |
| 244 | The buffer refers to an internal string buffer of <var>obj</var>, not a |
| 245 | copy. The data must not be modified in any way, unless the string |
| 246 | was just created using <code>PyString_FromStringAndSize(NULL, |
| 247 | <var>size</var>)</code>. It must not be deallocated. If <var>string</var> is a |
| 248 | Unicode object, this function computes the default encoding of |
| 249 | <var>string</var> and operates on that. If <var>string</var> is not a string |
| 250 | object at all, <tt class="cfunction">PyString_AsString()</tt> returns <tt class="constant">NULL</tt> and |
| 251 | raises <tt class="exception">TypeError</tt>. |
| 252 | </dd></dl> |
| 253 | |
| 254 | <P> |
| 255 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-464' xml:id='l2h-464' class="cfunction">PyString_Concat</tt></b>(</nobr></td><td>PyObject **<var>string</var>, |
| 256 | PyObject *<var>newpart</var>)</td></tr></table></dt> |
| 257 | <dd> |
| 258 | Create a new string object in <var>*string</var> containing the contents |
| 259 | of <var>newpart</var> appended to <var>string</var>; the caller will own the |
| 260 | new reference. The reference to the old value of <var>string</var> will |
| 261 | be stolen. If the new string cannot be created, the old reference |
| 262 | to <var>string</var> will still be discarded and the value of |
| 263 | <var>*string</var> will be set to <tt class="constant">NULL</tt>; the appropriate exception will |
| 264 | be set. |
| 265 | </dd></dl> |
| 266 | |
| 267 | <P> |
| 268 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-465' xml:id='l2h-465' class="cfunction">PyString_ConcatAndDel</tt></b>(</nobr></td><td>PyObject **<var>string</var>, |
| 269 | PyObject *<var>newpart</var>)</td></tr></table></dt> |
| 270 | <dd> |
| 271 | Create a new string object in <var>*string</var> containing the contents |
| 272 | of <var>newpart</var> appended to <var>string</var>. This version decrements |
| 273 | the reference count of <var>newpart</var>. |
| 274 | </dd></dl> |
| 275 | |
| 276 | <P> |
| 277 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-466' xml:id='l2h-466' class="cfunction">_PyString_Resize</tt></b>(</nobr></td><td>PyObject **<var>string</var>, int <var>newsize</var>)</td></tr></table></dt> |
| 278 | <dd> |
| 279 | A way to resize a string object even though it is ``immutable''. |
| 280 | Only use this to build up a brand new string object; don't use this |
| 281 | if the string may already be known in other parts of the code. It |
| 282 | is an error to call this function if the refcount on the input string |
| 283 | object is not one. |
| 284 | Pass the address of an existing string object as an lvalue (it may |
| 285 | be written into), and the new size desired. On success, <var>*string</var> |
| 286 | holds the resized string object and <code>0</code> is returned; the address in |
| 287 | <var>*string</var> may differ from its input value. If the |
| 288 | reallocation fails, the original string object at <var>*string</var> is |
| 289 | deallocated, <var>*string</var> is set to <tt class="constant">NULL</tt>, a memory exception is set, |
| 290 | and <code>-1</code> is returned. |
| 291 | </dd></dl> |
| 292 | |
| 293 | <P> |
| 294 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-467' xml:id='l2h-467' class="cfunction">PyString_Format</tt></b>(</nobr></td><td>PyObject *<var>format</var>, |
| 295 | PyObject *<var>args</var>)</td></tr></table></dt> |
| 296 | <dd> |
| 297 | <div class="refcount-info"> |
| 298 | <span class="label">Return value:</span> |
| 299 | <span class="value">New reference.</span> |
| 300 | </div> |
| 301 | Return a new string object from <var>format</var> and <var>args</var>. |
| 302 | Analogous to <code><var>format</var> % <var>args</var></code>. The <var>args</var> |
| 303 | argument must be a tuple. |
| 304 | </dd></dl> |
| 305 | |
| 306 | <P> |
| 307 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-468' xml:id='l2h-468' class="cfunction">PyString_InternInPlace</tt></b>(</nobr></td><td>PyObject **<var>string</var>)</td></tr></table></dt> |
| 308 | <dd> |
| 309 | Intern the argument <var>*string</var> in place. The argument must be |
| 310 | the address of a pointer variable pointing to a Python string |
| 311 | object. If there is an existing interned string that is the same as |
| 312 | <var>*string</var>, it sets <var>*string</var> to it (decrementing the |
| 313 | reference count of the old string object and incrementing the |
| 314 | reference count of the interned string object), otherwise it leaves |
| 315 | <var>*string</var> alone and interns it (incrementing its reference |
| 316 | count). (Clarification: even though there is a lot of talk about |
| 317 | reference counts, think of this function as reference-count-neutral; |
| 318 | you own the object after the call if and only if you owned it before |
| 319 | the call.) |
| 320 | </dd></dl> |
| 321 | |
| 322 | <P> |
| 323 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-469' xml:id='l2h-469' class="cfunction">PyString_InternFromString</tt></b>(</nobr></td><td>const char *<var>v</var>)</td></tr></table></dt> |
| 324 | <dd> |
| 325 | <div class="refcount-info"> |
| 326 | <span class="label">Return value:</span> |
| 327 | <span class="value">New reference.</span> |
| 328 | </div> |
| 329 | A combination of <tt class="cfunction">PyString_FromString()</tt> and |
| 330 | <tt class="cfunction">PyString_InternInPlace()</tt>, returning either a new string |
| 331 | object that has been interned, or a new (``owned'') reference to an |
| 332 | earlier interned string object with the same value. |
| 333 | </dd></dl> |
| 334 | |
| 335 | <P> |
| 336 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-470' xml:id='l2h-470' class="cfunction">PyString_Decode</tt></b>(</nobr></td><td>const char *<var>s</var>, |
| 337 | int <var>size</var>, |
| 338 | const char *<var>encoding</var>, |
| 339 | const char *<var>errors</var>)</td></tr></table></dt> |
| 340 | <dd> |
| 341 | <div class="refcount-info"> |
| 342 | <span class="label">Return value:</span> |
| 343 | <span class="value">New reference.</span> |
| 344 | </div> |
| 345 | Create an object by decoding <var>size</var> bytes of the encoded |
| 346 | buffer <var>s</var> using the codec registered for |
| 347 | <var>encoding</var>. <var>encoding</var> and <var>errors</var> have the same |
| 348 | meaning as the parameters of the same name in the |
| 349 | <tt class="function">unicode()</tt> built-in function. The codec to be used is |
| 350 | looked up using the Python codec registry. Return <tt class="constant">NULL</tt> if |
| 351 | an exception was raised by the codec. |
| 352 | </dd></dl> |
| 353 | |
| 354 | <P> |
| 355 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-471' xml:id='l2h-471' class="cfunction">PyString_AsDecodedObject</tt></b>(</nobr></td><td>PyObject *<var>str</var>, |
| 356 | const char *<var>encoding</var>, |
| 357 | const char *<var>errors</var>)</td></tr></table></dt> |
| 358 | <dd> |
| 359 | <div class="refcount-info"> |
| 360 | <span class="label">Return value:</span> |
| 361 | <span class="value">New reference.</span> |
| 362 | </div> |
| 363 | Decode a string object by passing it to the codec registered for |
| 364 | <var>encoding</var> and return the result as Python |
| 365 | object. <var>encoding</var> and <var>errors</var> have the same meaning as the |
| 366 | parameters of the same name in the string <tt class="method">encode()</tt> method. |
| 367 | The codec to be used is looked up using the Python codec registry. |
| 368 | Return <tt class="constant">NULL</tt> if an exception was raised by the codec. |
| 369 | </dd></dl> |
| 370 | |
| 371 | <P> |
| 372 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-472' xml:id='l2h-472' class="cfunction">PyString_Encode</tt></b>(</nobr></td><td>const char *<var>s</var>, |
| 373 | int <var>size</var>, |
| 374 | const char *<var>encoding</var>, |
| 375 | const char *<var>errors</var>)</td></tr></table></dt> |
| 376 | <dd> |
| 377 | <div class="refcount-info"> |
| 378 | <span class="label">Return value:</span> |
| 379 | <span class="value">New reference.</span> |
| 380 | </div> |
| 381 | Encode the <tt class="ctype">char</tt> buffer of the given size by passing it to |
| 382 | the codec registered for <var>encoding</var> and return a Python object. |
| 383 | <var>encoding</var> and <var>errors</var> have the same meaning as the |
| 384 | parameters of the same name in the string <tt class="method">encode()</tt> method. |
| 385 | The codec to be used is looked up using the Python codec |
| 386 | registry. Return <tt class="constant">NULL</tt> if an exception was raised by the |
| 387 | codec. |
| 388 | </dd></dl> |
| 389 | |
| 390 | <P> |
| 391 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-473' xml:id='l2h-473' class="cfunction">PyString_AsEncodedObject</tt></b>(</nobr></td><td>PyObject *<var>str</var>, |
| 392 | const char *<var>encoding</var>, |
| 393 | const char *<var>errors</var>)</td></tr></table></dt> |
| 394 | <dd> |
| 395 | <div class="refcount-info"> |
| 396 | <span class="label">Return value:</span> |
| 397 | <span class="value">New reference.</span> |
| 398 | </div> |
| 399 | Encode a string object using the codec registered for |
| 400 | <var>encoding</var> and return the result as Python object. |
| 401 | <var>encoding</var> and <var>errors</var> have the same meaning as the |
| 402 | parameters of the same name in the string <tt class="method">encode()</tt> method. |
| 403 | The codec to be used is looked up using the Python codec registry. |
| 404 | Return <tt class="constant">NULL</tt> if an exception was raised by the codec. |
| 405 | </dd></dl> |
| 406 | |
| 407 | <P> |
| 408 | |
| 409 | <DIV CLASS="navigation"> |
| 410 | <div class='online-navigation'> |
| 411 | <p></p><hr /> |
| 412 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 413 | <tr> |
| 414 | <td class='online-navigation'><a rel="prev" title="7.3 Sequence Objects" |
| 415 | href="sequenceObjects.html"><img src='../icons/previous.png' |
| 416 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 417 | <td class='online-navigation'><a rel="parent" title="7.3 Sequence Objects" |
| 418 | href="sequenceObjects.html"><img src='../icons/up.png' |
| 419 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 420 | <td class='online-navigation'><a rel="next" title="7.3.2 Unicode Objects" |
| 421 | href="unicodeObjects.html"><img src='../icons/next.png' |
| 422 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 423 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 424 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 425 | href="contents.html"><img src='../icons/contents.png' |
| 426 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 427 | <td class='online-navigation'><img src='../icons/blank.png' |
| 428 | border='0' height='32' alt='' width='32' /></td> |
| 429 | <td class='online-navigation'><a rel="index" title="Index" |
| 430 | href="genindex.html"><img src='../icons/index.png' |
| 431 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 432 | </tr></table> |
| 433 | <div class='online-navigation'> |
| 434 | <b class="navlabel">Previous:</b> |
| 435 | <a class="sectref" rel="prev" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 436 | <b class="navlabel">Up:</b> |
| 437 | <a class="sectref" rel="parent" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 438 | <b class="navlabel">Next:</b> |
| 439 | <a class="sectref" rel="next" href="unicodeObjects.html">7.3.2 Unicode Objects</A> |
| 440 | </div> |
| 441 | </div> |
| 442 | <hr /> |
| 443 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 444 | </DIV> |
| 445 | <!--End of Navigation Panel--> |
| 446 | <ADDRESS> |
| 447 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 448 | </ADDRESS> |
| 449 | </BODY> |
| 450 | </HTML> |