Python Library Reference

Previous: 2.2.6.3 XRange Type Up: 2.2.6 Sequence Types Next: 2.2.7 Mapping Types

---

 
2.2.6.4 Mutable Sequence Types

List objects support additional operations that allow in-place modification of the object. These operations would be supported by other mutable sequence types (when added to the language) as well. Strings and tuples are immutable sequence types and such objects cannot be modified once created. The following operations are defined on mutable sequence types (where x is an arbitrary object):  

Operation	Result	Notes
s[i] = x	item i of s is replaced by x
s[i:j] = t	slice of s from i to j is replaced by t
del s[i:j]	same as s[i:j] = []
s.append(x)	same as s[len(s):len(s)] = [x]	(1)
s.extend(x)	same as s[len(s):len(s)] = x	(2)
s.count(x)	return number of i's for which s[i] == x
s.index(x)	return smallest i such that s[i] == x	(3)
s.insert(i, x)	same as s[i:i] = [x] if i >= 0	(4)
s.pop([i])	same as x = s[i]; del s[i]; return x	(5)
s.remove(x)	same as del s[s.index(x)]	(3)
s.reverse()	reverses the items of s in place	(6)
s.sort([cmpfunc])	sort the items of s in place	(6), (7), (8), (9)

   Notes:

(1)

The C implementation of Python has historically accepted multiple parameters and implicitly joined them into a tuple; this no longer works in Python 2.0. Use of this misfeature has been deprecated since Python 1.4.

(2)

Raises an exception when x is not an iterable object.

(3)

Raises ValueError when x is not found in s.

(4)

When a negative index is passed as the first parameter to the insert() method, the new element is prepended to the sequence.

(5)

The pop() method is only supported by the list and array types. The optional argument i defaults to -1, so that by default the last item is removed and returned.

(6)

The sort() and reverse() methods modify the list in place for economy of space when sorting or reversing a large list. To remind you that they operate by side effect, they don't return the sorted or reversed list.

(7)

The sort() method takes an optional argument specifying a comparison function of two arguments (list items) which should return a negative, zero or positive number depending on whether the first argument is considered smaller than, equal to, or larger than the second argument. Note that this slows the sorting process down considerably; for example, to sort a list in reverse order it is much faster to call sort() followed by reverse() than to use sort() with a comparison function that reverses the ordering of the elements.

As an example of using the cmpfunc argument to the sort() method, consider sorting a list of sequences by the second element of that list:

def mycmp(a, b):
    return cmp(a[1], b[1])

mylist.sort(mycmp)

A more time-efficient approach for reasonably-sized data structures can often be used:

tmplist = [(x[1], x) for x in mylist]
tmplist.sort()
mylist = [x for (key, x) in tmplist]

(8)

Whether the sort() method is stable is not defined by the language (a sort is stable if it guarantees not to change the relative order of elements that compare equal). In the C implementation of Python, sorts were stable only by accident through Python 2.2. Code that intends to be portable across implementations and versions must not rely on stability.

(9)

While a list is being sorted, the effect of attempting to mutate, or even inspect, the list is undefined.

---

Python Library Reference

Previous: 2.2.6.3 XRange Type Up: 2.2.6 Sequence Types Next: 2.2.7 Mapping Types

---

Release 2.2.3, documentation updated on 30 May 2003.