Next / Previous / Contents / TCC Help System / NM Tech homepage

11.1. Methods on lists

For any list value L, these methods are available.

L.append(x)

Append a new element x to the end of list L. Does not return a value.

>>> colors = ['red', 'green', 'blue']
>>> colors.append('indigo')
>>> colors
['red', 'green', 'blue', 'indigo']

L.count(x)

Return the number of elements of L that compare equal to x.

>>> [59, 0, 0, 0, 63, 0, 0].count(0)
5
>>> ['x', 'y'].count('Fomalhaut')
0

L.extend(S)

Append another sequence S to L.

>>> colors
['red', 'green', 'blue', 'indigo']
>>> colors.extend(['violet', 'pale puce'])
>>> colors
['red', 'green', 'blue', 'indigo', 'violet', 'pale puce']

L.index(x[, start[, end]])

If L contains any elements that equal x, return the index of the first such element, otherwise raise a ValueError exception.

The optional start and end arguments can be used to search only positions within the slice L[start:end].

>>> colors
['red', 'green', 'blue', 'indigo', 'violet', 'pale puce']
>>> colors.index('blue')
2
>>> colors.index('taupe')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.index(x): x not in list
>>> M=[0, 0, 3, 0, 0, 3, 3, 0, 0, 3]
>>> M.index(3)
2
>>> M.index(3, 4, 8)
5
>>> M.index(3, 0, 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.index(x): x not in list

L.insert(i,x)

Insert a new element x into list L just before the ith element, shifting all higher-number elements to the right. No value is returned.

>>> colors
['red', 'green', 'blue', 'indigo', 'violet', 'pale puce']
>>> colors[1]
'green'
>>> colors.insert(1, "yellow")
>>> colors
['red', 'yellow', 'green', 'blue', 'indigo', 'violet', 'pale puce']

L.pop([i])

Remove and return the element with index i from L. The default value for i is -1, so if you pass no argument, the last element is removed.

>>> colors
['red', 'yellow', 'green', 'blue', 'indigo', 'violet', 'pale puce']
>>> tos = colors.pop()
>>> tos
'pale puce'
>>> colors
['red', 'yellow', 'green', 'blue', 'indigo', 'violet']
>>> colors[4]
'indigo'
>>> dye = colors.pop(4)
>>> dye
'indigo'
>>> colors
['red', 'yellow', 'green', 'blue', 'violet']

L.remove(x)

Remove the first element of L that is equal to x. If there aren't any such elements, raises ValueError.

>>> colors
['red', 'yellow', 'green', 'blue', 'violet']
>>> colors.remove('yellow')
>>> colors
['red', 'green', 'blue', 'violet']
>>> colors.remove('cornflower')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list
>>> notMuch = [0, 0, 3, 0]
>>> notMuch.remove(0)
>>> notMuch
[0, 3, 0]
>>> notMuch.remove(0)
>>> notMuch
[3, 0]
>>> notMuch.remove(0)
>>> notMuch
[3]
>>> notMuch.remove(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

L.reverse()

Reverses the elements of L in place. Does not return a result. Compare Section 20.36, “reversed(): Produce a reverse iterator”.

>>> colors
['red', 'green', 'blue', 'violet']
>>> colors.reverse()
>>> colors
['violet', 'blue', 'green', 'red']

L.sort(cmp[,key[,reverse]]])

Sort list L in place. Does not return a result. Compare Section 20.39, “sorted(): Sort a sequence”.

The reordering is guaranteed to be stable—that is, if two elements are considered equal, their order after sorting will not change.

While sorting, Python will use the built-in cmp() function to compare elements; see Section 20.8, “cmp(): Compare two values”. You may provide, as the first argument to the .sort() method, your own comparator function to compare elements. This function must have the same calling sequence and return value convention as the built-in cmp() function: it must take two arguments, and return a negative number of the first argument precedes the second, a positive number if the second argument precedes the first, or zero if they are considered equal.

You may also provide a “key extractor function” that is applied to each element to determine its key. This function must take one argument and return the value to be used as the sort key. If you want to provide a key extractor function but not a comparator function, pass None as the first argument to the method.

Additionally, you may provide a third argument of True to sort the sequence in descending order; the default behavior is to sort into ascending order.

>>> temps=[67, 73, 85, 93, 92, 78, 95, 100, 104]
>>> temps.sort()
>>> temps
[67, 73, 78, 85, 92, 93, 95, 100, 104]
>>> def reverser(n1, n2):
...     '''Comparison function to use reverse order.
...     '''
...     return cmp(n2, n1)
... 
>>> temps.sort(reverser)
>>> temps
[104, 100, 95, 93, 92, 85, 78, 73, 67]
>>> def unitsDigit(n):
...     '''Returns only the units digit of n.
...     '''
...     return n % 10
... 
>>> temps.sort(None, unitsDigit)
>>> temps
[100, 92, 93, 73, 104, 95, 85, 67, 78]
>>> temps.sort(None, None, True)
>>> temps
[104, 100, 95, 93, 92, 85, 78, 73, 67]