[Python-checkins] r86602 - in python/branches/release27-maint/Doc/library: functions.rst stdtypes.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Sat Nov 20 20:35:42 2010
New Revision: 86602

Log:
Issue #8340: document bytearray in Python 2.7.



Modified:
   python/branches/release27-maint/Doc/library/functions.rst
   python/branches/release27-maint/Doc/library/stdtypes.rst

Modified: python/branches/release27-maint/Doc/library/functions.rst
==============================================================================
--- python/branches/release27-maint/Doc/library/functions.rst	(original)
+++ python/branches/release27-maint/Doc/library/functions.rst	Sat Nov 20 20:35:42 2010
@@ -78,6 +78,32 @@
       If no argument is given, this function returns :const:`False`.
 
 
+.. function:: bytearray([source[, encoding[, errors]]])
+
+   Return a new array of bytes.  The :class:`bytearray` type is a mutable
+   sequence of integers in the range 0 <= x < 256.  It has most of the usual
+   methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
+   as most methods that the :class:`str` type has, see :ref:`string-methods`.
+
+   The optional *source* parameter can be used to initialize the array in a few
+   different ways:
+
+   * If it is a *string*, you must also give the *encoding* (and optionally,
+     *errors*) parameters; :func:`bytearray` then converts the string to
+     bytes using :meth:`str.encode`.
+
+   * If it is an *integer*, the array will have that size and will be
+     initialized with null bytes.
+
+   * If it is an object conforming to the *buffer* interface, a read-only buffer
+     of the object will be used to initialize the bytes array.
+
+   * If it is an *iterable*, it must be an iterable of integers in the range
+     ``0 <= x < 256``, which are used as the initial contents of the array.
+
+   Without an argument, an array of size 0 is created.
+
+
 .. function:: callable(object)
 
    Return :const:`True` if the *object* argument appears callable,

Modified: python/branches/release27-maint/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/release27-maint/Doc/library/stdtypes.rst	(original)
+++ python/branches/release27-maint/Doc/library/stdtypes.rst	Sat Nov 20 20:35:42 2010
@@ -659,11 +659,11 @@
 
 .. _typesseq:
 
-Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`buffer`, :class:`xrange`
-==================================================================================================================
+Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`bytearray`, :class:`buffer`, :class:`xrange`
+======================================================================================================================================
 
-There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
-and xrange objects.
+There are seven sequence types: strings, Unicode strings, lists, tuples,
+bytearrays, buffers, and xrange objects.
 
 For other containers see the built in :class:`dict` and :class:`set` classes,
 and the :mod:`collections` module.
@@ -675,6 +675,7 @@
    object: Unicode
    object: tuple
    object: list
+   object: bytearray
    object: buffer
    object: xrange
 
@@ -690,6 +691,8 @@
 must have the enclosing parentheses, such as ``a, b, c`` or ``()``.  A
 single item tuple must have a trailing comma, such as ``(d,)``.
 
+Bytearray objects are created with the built-in function :func:`bytearray`.
+
 Buffer objects are not directly supported by Python syntax, but can be created
 by calling the built-in function :func:`buffer`.  They don't support
 concatenation or repetition.
@@ -834,7 +837,8 @@
 .. index:: pair: string; methods
 
 Below are listed the string methods which both 8-bit strings and
-Unicode objects support.
+Unicode objects support.  Some of them are also available on :class:`bytearray`
+objects.
 
 In addition, Python's strings support the sequence type methods
 described in the :ref:`typesseq` section. To output formatted strings
@@ -1505,11 +1509,12 @@
    triple: mutable; sequence; types
    object: list
 
-List objects support additional operations that allow in-place modification of
-the object. Other mutable sequence types (when added to the language) should
-also support these operations. Strings and tuples are immutable sequence types:
-such objects cannot be modified once created. The following operations are
-defined on mutable sequence types (where *x* is an arbitrary object):
+List and :class:`bytearray` objects support additional operations that allow
+in-place modification of the object. Other mutable sequence types (when added
+to the language) should also support these operations. Strings and tuples
+are immutable sequence types: such objects cannot be modified once created.
+The following operations are defined on mutable sequence types (where *x* is
+an arbitrary object):
 
 .. index::
    triple: operations on; sequence; types