diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4b4c9b2024d..0b16327ea6d 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -78,6 +78,32 @@ available. They are listed here in alphabetical order. 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, diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 72938223ebe..daceddc446b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -659,11 +659,11 @@ yield expression `. .. _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 @@ and the :mod:`collections` module. object: Unicode object: tuple object: list + object: bytearray object: buffer object: xrange @@ -690,6 +691,8 @@ brackets), with or without enclosing parentheses, but an empty tuple 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 @@ String Methods .. 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 @@ Mutable Sequence Types 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