| 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="bufferObjects.html" /> |
| 13 | <link rel="prev" href="stringObjects.html" /> |
| 14 | <link rel="parent" href="sequenceObjects.html" /> |
| 15 | <link rel="next" href="builtinCodecs.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>7.3.2 Unicode 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.1 String Objects" |
| 25 | href="stringObjects.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.1 Built-in Codecs" |
| 31 | href="builtinCodecs.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="stringObjects.html">7.3.1 String 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="builtinCodecs.html">7.3.2.1 Built-in Codecs</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION009320000000000000000"></A><A NAME="unicodeObjects"></A> |
| 56 | <BR> |
| 57 | 7.3.2 Unicode Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | These are the basic Unicode object types used for the Unicode |
| 62 | implementation in Python: |
| 63 | |
| 64 | <P> |
| 65 | <dl><dt><b><tt class="ctype"><a id='l2h-474' xml:id='l2h-474'>Py_UNICODE</a></tt></b></dt> |
| 66 | <dd> |
| 67 | This type represents a 16-bit unsigned storage type which is used by |
| 68 | Python internally as basis for holding Unicode ordinals. On |
| 69 | platforms where <tt class="ctype">wchar_t</tt> is available and also has 16-bits, |
| 70 | <tt class="ctype">Py_UNICODE</tt> is a typedef alias for <tt class="ctype">wchar_t</tt> to enhance |
| 71 | native platform compatibility. On all other platforms, |
| 72 | <tt class="ctype">Py_UNICODE</tt> is a typedef alias for <tt class="ctype">unsigned short</tt>. |
| 73 | </dl> |
| 74 | |
| 75 | <P> |
| 76 | <dl><dt><b><tt class="ctype"><a id='l2h-475' xml:id='l2h-475'>PyUnicodeObject</a></tt></b></dt> |
| 77 | <dd> |
| 78 | This subtype of <tt class="ctype">PyObject</tt> represents a Python Unicode object. |
| 79 | </dl> |
| 80 | |
| 81 | <P> |
| 82 | <dl><dt>PyTypeObject <b><tt id='l2h-476' xml:id='l2h-476' class="cdata">PyUnicode_Type</tt></b></dt> |
| 83 | <dd> |
| 84 | This instance of <tt class="ctype">PyTypeObject</tt> represents the Python Unicode |
| 85 | type. |
| 86 | </dd></dl> |
| 87 | |
| 88 | <P> |
| 89 | The following APIs are really C macros and can be used to do fast |
| 90 | checks and to access internal read-only data of Unicode objects: |
| 91 | |
| 92 | <P> |
| 93 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-477' xml:id='l2h-477' class="cfunction">PyUnicode_Check</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 94 | <dd> |
| 95 | Return true if the object <var>o</var> is a Unicode object or an |
| 96 | instance of a Unicode subtype. |
| 97 | |
| 98 | <span class="versionnote">Changed in version 2.2: |
| 99 | Allowed subtypes to be accepted.</span> |
| 100 | |
| 101 | </dd></dl> |
| 102 | |
| 103 | <P> |
| 104 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-478' xml:id='l2h-478' class="cfunction">PyUnicode_CheckExact</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 105 | <dd> |
| 106 | Return true if the object <var>o</var> is a Unicode object, but not an |
| 107 | instance of a subtype. |
| 108 | |
| 109 | <span class="versionnote">New in version 2.2.</span> |
| 110 | |
| 111 | </dd></dl> |
| 112 | |
| 113 | <P> |
| 114 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-479' xml:id='l2h-479' class="cfunction">PyUnicode_GET_SIZE</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 115 | <dd> |
| 116 | Return the size of the object. <var>o</var> has to be a |
| 117 | <tt class="ctype">PyUnicodeObject</tt> (not checked). |
| 118 | </dd></dl> |
| 119 | |
| 120 | <P> |
| 121 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-480' xml:id='l2h-480' class="cfunction">PyUnicode_GET_DATA_SIZE</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 122 | <dd> |
| 123 | Return the size of the object's internal buffer in bytes. <var>o</var> |
| 124 | has to be a <tt class="ctype">PyUnicodeObject</tt> (not checked). |
| 125 | </dd></dl> |
| 126 | |
| 127 | <P> |
| 128 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>Py_UNICODE* <b><tt id='l2h-481' xml:id='l2h-481' class="cfunction">PyUnicode_AS_UNICODE</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 129 | <dd> |
| 130 | Return a pointer to the internal <tt class="ctype">Py_UNICODE</tt> buffer of the |
| 131 | object. <var>o</var> has to be a <tt class="ctype">PyUnicodeObject</tt> (not checked). |
| 132 | </dd></dl> |
| 133 | |
| 134 | <P> |
| 135 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>const char* <b><tt id='l2h-482' xml:id='l2h-482' class="cfunction">PyUnicode_AS_DATA</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 136 | <dd> |
| 137 | Return a pointer to the internal buffer of the object. |
| 138 | <var>o</var> has to be a <tt class="ctype">PyUnicodeObject</tt> (not checked). |
| 139 | </dd></dl> |
| 140 | |
| 141 | <P> |
| 142 | Unicode provides many different character properties. The most often |
| 143 | needed ones are available through these macros which are mapped to C |
| 144 | functions depending on the Python configuration. |
| 145 | |
| 146 | <P> |
| 147 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-483' xml:id='l2h-483' class="cfunction">Py_UNICODE_ISSPACE</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 148 | <dd> |
| 149 | Return 1 or 0 depending on whether <var>ch</var> is a whitespace |
| 150 | character. |
| 151 | </dd></dl> |
| 152 | |
| 153 | <P> |
| 154 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-484' xml:id='l2h-484' class="cfunction">Py_UNICODE_ISLOWER</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 155 | <dd> |
| 156 | Return 1 or 0 depending on whether <var>ch</var> is a lowercase character. |
| 157 | </dd></dl> |
| 158 | |
| 159 | <P> |
| 160 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-485' xml:id='l2h-485' class="cfunction">Py_UNICODE_ISUPPER</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 161 | <dd> |
| 162 | Return 1 or 0 depending on whether <var>ch</var> is an uppercase |
| 163 | character. |
| 164 | </dd></dl> |
| 165 | |
| 166 | <P> |
| 167 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-486' xml:id='l2h-486' class="cfunction">Py_UNICODE_ISTITLE</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 168 | <dd> |
| 169 | Return 1 or 0 depending on whether <var>ch</var> is a titlecase character. |
| 170 | </dd></dl> |
| 171 | |
| 172 | <P> |
| 173 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-487' xml:id='l2h-487' class="cfunction">Py_UNICODE_ISLINEBREAK</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 174 | <dd> |
| 175 | Return 1 or 0 depending on whether <var>ch</var> is a linebreak character. |
| 176 | </dd></dl> |
| 177 | |
| 178 | <P> |
| 179 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-488' xml:id='l2h-488' class="cfunction">Py_UNICODE_ISDECIMAL</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 180 | <dd> |
| 181 | Return 1 or 0 depending on whether <var>ch</var> is a decimal character. |
| 182 | </dd></dl> |
| 183 | |
| 184 | <P> |
| 185 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-489' xml:id='l2h-489' class="cfunction">Py_UNICODE_ISDIGIT</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 186 | <dd> |
| 187 | Return 1 or 0 depending on whether <var>ch</var> is a digit character. |
| 188 | </dd></dl> |
| 189 | |
| 190 | <P> |
| 191 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-490' xml:id='l2h-490' class="cfunction">Py_UNICODE_ISNUMERIC</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 192 | <dd> |
| 193 | Return 1 or 0 depending on whether <var>ch</var> is a numeric character. |
| 194 | </dd></dl> |
| 195 | |
| 196 | <P> |
| 197 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-491' xml:id='l2h-491' class="cfunction">Py_UNICODE_ISALPHA</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 198 | <dd> |
| 199 | Return 1 or 0 depending on whether <var>ch</var> is an alphabetic |
| 200 | character. |
| 201 | </dd></dl> |
| 202 | |
| 203 | <P> |
| 204 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-492' xml:id='l2h-492' class="cfunction">Py_UNICODE_ISALNUM</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 205 | <dd> |
| 206 | Return 1 or 0 depending on whether <var>ch</var> is an alphanumeric |
| 207 | character. |
| 208 | </dd></dl> |
| 209 | |
| 210 | <P> |
| 211 | These APIs can be used for fast direct character conversions: |
| 212 | |
| 213 | <P> |
| 214 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>Py_UNICODE <b><tt id='l2h-493' xml:id='l2h-493' class="cfunction">Py_UNICODE_TOLOWER</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 215 | <dd> |
| 216 | Return the character <var>ch</var> converted to lower case. |
| 217 | </dd></dl> |
| 218 | |
| 219 | <P> |
| 220 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>Py_UNICODE <b><tt id='l2h-494' xml:id='l2h-494' class="cfunction">Py_UNICODE_TOUPPER</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 221 | <dd> |
| 222 | Return the character <var>ch</var> converted to upper case. |
| 223 | </dd></dl> |
| 224 | |
| 225 | <P> |
| 226 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>Py_UNICODE <b><tt id='l2h-495' xml:id='l2h-495' class="cfunction">Py_UNICODE_TOTITLE</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 227 | <dd> |
| 228 | Return the character <var>ch</var> converted to title case. |
| 229 | </dd></dl> |
| 230 | |
| 231 | <P> |
| 232 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-496' xml:id='l2h-496' class="cfunction">Py_UNICODE_TODECIMAL</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 233 | <dd> |
| 234 | Return the character <var>ch</var> converted to a decimal positive |
| 235 | integer. Return <code>-1</code> if this is not possible. This macro |
| 236 | does not raise exceptions. |
| 237 | </dd></dl> |
| 238 | |
| 239 | <P> |
| 240 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-497' xml:id='l2h-497' class="cfunction">Py_UNICODE_TODIGIT</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 241 | <dd> |
| 242 | Return the character <var>ch</var> converted to a single digit integer. |
| 243 | Return <code>-1</code> if this is not possible. This macro does not raise |
| 244 | exceptions. |
| 245 | </dd></dl> |
| 246 | |
| 247 | <P> |
| 248 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>double <b><tt id='l2h-498' xml:id='l2h-498' class="cfunction">Py_UNICODE_TONUMERIC</tt></b>(</nobr></td><td>Py_UNICODE <var>ch</var>)</td></tr></table></dt> |
| 249 | <dd> |
| 250 | Return the character <var>ch</var> converted to a (positive) double. |
| 251 | Return <code>-1.0</code> if this is not possible. This macro does not raise |
| 252 | exceptions. |
| 253 | </dd></dl> |
| 254 | |
| 255 | <P> |
| 256 | To create Unicode objects and access their basic sequence properties, |
| 257 | use these APIs: |
| 258 | |
| 259 | <P> |
| 260 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-499' xml:id='l2h-499' class="cfunction">PyUnicode_FromUnicode</tt></b>(</nobr></td><td>const Py_UNICODE *<var>u</var>, |
| 261 | int <var>size</var>)</td></tr></table></dt> |
| 262 | <dd> |
| 263 | <div class="refcount-info"> |
| 264 | <span class="label">Return value:</span> |
| 265 | <span class="value">New reference.</span> |
| 266 | </div> |
| 267 | Create a Unicode Object from the Py_UNICODE buffer <var>u</var> of the |
| 268 | given size. <var>u</var> may be <tt class="constant">NULL</tt> which causes the contents to be |
| 269 | undefined. It is the user's responsibility to fill in the needed |
| 270 | data. The buffer is copied into the new object. If the buffer is |
| 271 | not <tt class="constant">NULL</tt>, the return value might be a shared object. Therefore, |
| 272 | modification of the resulting Unicode object is only allowed when |
| 273 | <var>u</var> is <tt class="constant">NULL</tt>. |
| 274 | </dd></dl> |
| 275 | |
| 276 | <P> |
| 277 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>Py_UNICODE* <b><tt id='l2h-500' xml:id='l2h-500' class="cfunction">PyUnicode_AsUnicode</tt></b>(</nobr></td><td>PyObject *<var>unicode</var>)</td></tr></table></dt> |
| 278 | <dd> |
| 279 | Return a read-only pointer to the Unicode object's internal |
| 280 | <tt class="ctype">Py_UNICODE</tt> buffer, <tt class="constant">NULL</tt> if <var>unicode</var> is not a Unicode |
| 281 | object. |
| 282 | </dd></dl> |
| 283 | |
| 284 | <P> |
| 285 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-501' xml:id='l2h-501' class="cfunction">PyUnicode_GetSize</tt></b>(</nobr></td><td>PyObject *<var>unicode</var>)</td></tr></table></dt> |
| 286 | <dd> |
| 287 | Return the length of the Unicode object. |
| 288 | </dd></dl> |
| 289 | |
| 290 | <P> |
| 291 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-502' xml:id='l2h-502' class="cfunction">PyUnicode_FromEncodedObject</tt></b>(</nobr></td><td>PyObject *<var>obj</var>, |
| 292 | const char *<var>encoding</var>, |
| 293 | const char *<var>errors</var>)</td></tr></table></dt> |
| 294 | <dd> |
| 295 | <div class="refcount-info"> |
| 296 | <span class="label">Return value:</span> |
| 297 | <span class="value">New reference.</span> |
| 298 | </div> |
| 299 | Coerce an encoded object <var>obj</var> to an Unicode object and return a |
| 300 | reference with incremented refcount. |
| 301 | |
| 302 | <P> |
| 303 | Coercion is done in the following way: |
| 304 | |
| 305 | <P> |
| 306 | |
| 307 | <OL> |
| 308 | <LI>Unicode objects are passed back as-is with incremented |
| 309 | refcount. <span class="note"><b class="label">Note:</b> |
| 310 | These cannot be decoded; passing a non-<tt class="constant">NULL</tt> |
| 311 | value for encoding will result in a <tt class="exception">TypeError</tt>.</span> |
| 312 | |
| 313 | <P> |
| 314 | </LI> |
| 315 | <LI>String and other char buffer compatible objects are decoded |
| 316 | according to the given encoding and using the error handling |
| 317 | defined by errors. Both can be <tt class="constant">NULL</tt> to have the interface |
| 318 | use the default values (see the next section for details). |
| 319 | |
| 320 | <P> |
| 321 | </LI> |
| 322 | <LI>All other objects cause an exception. |
| 323 | </LI> |
| 324 | </OL> |
| 325 | |
| 326 | <P> |
| 327 | The API returns <tt class="constant">NULL</tt> if there was an error. The caller is |
| 328 | responsible for decref'ing the returned objects. |
| 329 | </dd></dl> |
| 330 | |
| 331 | <P> |
| 332 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-503' xml:id='l2h-503' class="cfunction">PyUnicode_FromObject</tt></b>(</nobr></td><td>PyObject *<var>obj</var>)</td></tr></table></dt> |
| 333 | <dd> |
| 334 | <div class="refcount-info"> |
| 335 | <span class="label">Return value:</span> |
| 336 | <span class="value">New reference.</span> |
| 337 | </div> |
| 338 | Shortcut for <code>PyUnicode_FromEncodedObject(obj, NULL, "strict")</code> |
| 339 | which is used throughout the interpreter whenever coercion to |
| 340 | Unicode is needed. |
| 341 | </dd></dl> |
| 342 | |
| 343 | <P> |
| 344 | If the platform supports <tt class="ctype">wchar_t</tt> and provides a header file |
| 345 | wchar.h, Python can interface directly to this type using the |
| 346 | following functions. Support is optimized if Python's own |
| 347 | <tt class="ctype">Py_UNICODE</tt> type is identical to the system's <tt class="ctype">wchar_t</tt>. |
| 348 | |
| 349 | <P> |
| 350 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-504' xml:id='l2h-504' class="cfunction">PyUnicode_FromWideChar</tt></b>(</nobr></td><td>const wchar_t *<var>w</var>, |
| 351 | int <var>size</var>)</td></tr></table></dt> |
| 352 | <dd> |
| 353 | <div class="refcount-info"> |
| 354 | <span class="label">Return value:</span> |
| 355 | <span class="value">New reference.</span> |
| 356 | </div> |
| 357 | Create a Unicode object from the <tt class="ctype">wchar_t</tt> buffer <var>w</var> of |
| 358 | the given size. Return <tt class="constant">NULL</tt> on failure. |
| 359 | </dd></dl> |
| 360 | |
| 361 | <P> |
| 362 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-505' xml:id='l2h-505' class="cfunction">PyUnicode_AsWideChar</tt></b>(</nobr></td><td>PyUnicodeObject *<var>unicode</var>, |
| 363 | wchar_t *<var>w</var>, |
| 364 | int <var>size</var>)</td></tr></table></dt> |
| 365 | <dd> |
| 366 | Copy the Unicode object contents into the <tt class="ctype">wchar_t</tt> buffer |
| 367 | <var>w</var>. At most <var>size</var> <tt class="ctype">wchar_t</tt> characters are copied |
| 368 | (excluding a possibly trailing 0-termination character). Return |
| 369 | the number of <tt class="ctype">wchar_t</tt> characters copied or -1 in case of an |
| 370 | error. Note that the resulting <tt class="ctype">wchar_t</tt> string may or may |
| 371 | not be 0-terminated. It is the responsibility of the caller to make |
| 372 | sure that the <tt class="ctype">wchar_t</tt> string is 0-terminated in case this is |
| 373 | required by the application. |
| 374 | </dd></dl> |
| 375 | |
| 376 | <P> |
| 377 | |
| 378 | <p><br /></p><hr class='online-navigation' /> |
| 379 | <div class='online-navigation'> |
| 380 | <!--Table of Child-Links--> |
| 381 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 382 | |
| 383 | <UL CLASS="ChildLinks"> |
| 384 | <LI><A href="builtinCodecs.html">7.3.2.1 Built-in Codecs</a> |
| 385 | <LI><A href="unicodeMethodsAndSlots.html">7.3.2.2 Methods and Slot Functions</a> |
| 386 | </ul> |
| 387 | <!--End of Table of Child-Links--> |
| 388 | </div> |
| 389 | |
| 390 | <DIV CLASS="navigation"> |
| 391 | <div class='online-navigation'> |
| 392 | <p></p><hr /> |
| 393 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 394 | <tr> |
| 395 | <td class='online-navigation'><a rel="prev" title="7.3.1 String Objects" |
| 396 | href="stringObjects.html"><img src='../icons/previous.png' |
| 397 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 398 | <td class='online-navigation'><a rel="parent" title="7.3 Sequence Objects" |
| 399 | href="sequenceObjects.html"><img src='../icons/up.png' |
| 400 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 401 | <td class='online-navigation'><a rel="next" title="7.3.2.1 Built-in Codecs" |
| 402 | href="builtinCodecs.html"><img src='../icons/next.png' |
| 403 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 404 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 405 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 406 | href="contents.html"><img src='../icons/contents.png' |
| 407 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 408 | <td class='online-navigation'><img src='../icons/blank.png' |
| 409 | border='0' height='32' alt='' width='32' /></td> |
| 410 | <td class='online-navigation'><a rel="index" title="Index" |
| 411 | href="genindex.html"><img src='../icons/index.png' |
| 412 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 413 | </tr></table> |
| 414 | <div class='online-navigation'> |
| 415 | <b class="navlabel">Previous:</b> |
| 416 | <a class="sectref" rel="prev" href="stringObjects.html">7.3.1 String Objects</A> |
| 417 | <b class="navlabel">Up:</b> |
| 418 | <a class="sectref" rel="parent" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 419 | <b class="navlabel">Next:</b> |
| 420 | <a class="sectref" rel="next" href="builtinCodecs.html">7.3.2.1 Built-in Codecs</A> |
| 421 | </div> |
| 422 | </div> |
| 423 | <hr /> |
| 424 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 425 | </DIV> |
| 426 | <!--End of Navigation Panel--> |
| 427 | <ADDRESS> |
| 428 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 429 | </ADDRESS> |
| 430 | </BODY> |
| 431 | </HTML> |