← Back to branch summary

~ubuntu-branches/ubuntu/lucid/python2.6/lucid

« back to all changes in this revision

Viewing changes to Doc/c-api/unicode.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2010-03-11 13:30:19 UTC
  • mto: (10.1.13 sid)
  • mto: This revision was merged to the branch mainline in revision 44.
  • Revision ID: james.westby@ubuntu.com-20100311133019-sblbooa3uqrkoe70
Tags: upstream-2.6.5~rc2
Import upstream version 2.6.5~rc2

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/unicode.rst
98
98
   :ctype:`PyUnicodeObject` (not checked).
99
99
 
100
100
 
101
 
.. cfunction:: int PyUnicode_ClearFreeList(void)
 
101
.. cfunction:: int PyUnicode_ClearFreeList()
102
102
 
103
103
   Clear the free list. Return the total number of freed items.
104
104
 
105
105
   .. versionadded:: 2.6
106
106
 
 
107
 
107
108
Unicode provides many different character properties. The most often needed ones
108
109
are available through these macros which are mapped to C functions depending on
109
110
the Python configuration.
291
292
Built-in Codecs
292
293
^^^^^^^^^^^^^^^
293
294
 
294
 
Python provides a set of builtin codecs which are written in C for speed. All of
 
295
Python provides a set of built-in codecs which are written in C for speed. All of
295
296
these codecs are directly usable via the following functions.
296
297
 
297
298
Many of the following APIs take two arguments encoding and errors. These
298
299
parameters encoding and errors have the same semantics as the ones of the
299
 
builtin unicode() Unicode object constructor.
 
300
built-in :func:`unicode` Unicode object constructor.
300
301
 
301
302
Setting encoding to *NULL* causes the default encoding to be used which is
302
303
ASCII.  The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
306
307
 
307
308
Error handling is set by errors which may also be set to *NULL* meaning to use
308
309
the default handling defined for the codec.  Default error handling for all
309
 
builtin codecs is "strict" (:exc:`ValueError` is raised).
 
310
built-in codecs is "strict" (:exc:`ValueError` is raised).
310
311
 
311
312
The codecs all use a similar interface.  Only deviation from the following
312
313
generic ones are documented for simplicity.
320
321
 
321
322
   Create a Unicode object by decoding *size* bytes of the encoded string *s*.
322
323
   *encoding* and *errors* have the same meaning as the parameters of the same name
323
 
   in the :func:`unicode` builtin function.  The codec to be used is looked up
 
324
   in the :func:`unicode` built-in function.  The codec to be used is looked up
324
325
   using the Python codec registry.  Return *NULL* if an exception was raised by
325
326
   the codec.
326
327
 
413
414
      *byteorder == 0:  native order
414
415
      *byteorder == 1:  big endian
415
416
 
416
 
   and then switches if the first four bytes of the input data are a byte order mark
417
 
   (BOM) and the specified byte order is native order.  This BOM is not copied into
418
 
   the resulting Unicode string.  After completion, *\*byteorder* is set to the
419
 
   current byte order at the end of input data.
 
417
   If ``*byteorder`` is zero, and the first four bytes of the input data are a
 
418
   byte order mark (BOM), the decoder switches to this byte order and the BOM is
 
419
   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
 
420
   ``1``, any byte order mark is copied to the output.
 
421
 
 
422
   After completion, *\*byteorder* is set to the current byte order at the end
 
423
   of input data.
420
424
 
421
425
   In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
422
426
 
441
445
.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
442
446
 
443
447
   Return a Python bytes object holding the UTF-32 encoded value of the Unicode
444
 
   data in *s*.  If *byteorder* is not ``0``, output is written according to the
445
 
   following byte order::
 
448
   data in *s*.  Output is written according to the following byte order::
446
449
 
447
450
      byteorder == -1: little endian
448
451
      byteorder == 0:  native byte order (writes a BOM mark)
486
489
      *byteorder == 0:  native order
487
490
      *byteorder == 1:  big endian
488
491
 
489
 
   and then switches if the first two bytes of the input data are a byte order mark
490
 
   (BOM) and the specified byte order is native order.  This BOM is not copied into
491
 
   the resulting Unicode string.  After completion, *\*byteorder* is set to the
492
 
   current byte order at the.
 
492
   If ``*byteorder`` is zero, and the first two bytes of the input data are a
 
493
   byte order mark (BOM), the decoder switches to this byte order and the BOM is
 
494
   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
 
495
   ``1``, any byte order mark is copied to the output (where it will result in
 
496
   either a ``\ufeff`` or a ``\ufffe`` character).
 
497
 
 
498
   After completion, *\*byteorder* is set to the current byte order at the end
 
499
   of input data.
493
500
 
494
501
   If *byteorder* is *NULL*, the codec starts in native order mode.
495
502
 
519
526
.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
520
527
 
521
528
   Return a Python string object holding the UTF-16 encoded value of the Unicode
522
 
   data in *s*.  If *byteorder* is not ``0``, output is written according to the
523
 
   following byte order::
 
529
   data in *s*.  Output is written according to the following byte order::
524
530
 
525
531
      byteorder == -1: little endian
526
532
      byteorder == 0:  native byte order (writes a BOM mark)