List Methods and Built-in Functions

The list data type comes with a rich set of built-in methods and functions for everyday programming: measuring a list, building one, adding and removing elements, searching, rearranging, and summarising. The chapter collects them in Table 9.1; here each one is explained with its behaviour and an example.

len() — length of a list

Passed a list as argument, len() returns its length, i.e. the total number of elements:

>>> scores = [55, 60, 65, 70, 75]
>>> len(scores)
5

list() — creating a list

With no argument, list() creates an empty list:

>>> items = list()
>>> items
[]

With a sequence as argument, it builds a list out of that sequence's items — for example, a string becomes a list of its characters:

>>> word = 'stack'
>>> chars = list(word)
>>> chars
['s', 't', 'a', 'c', 'k']

append() — add a single element at the end

append() attaches the single element passed as argument to the end of the list:

>>> nums = [3, 6, 9, 12]
>>> nums.append(15)
>>> nums
[3, 6, 9, 12, 15]

That single element can itself be a list — in which case the whole inner list becomes one new element (a nested list), not several:

>>> nums = [3, 6, 9, 12]
>>> nums.append([15, 18])
>>> nums
[3, 6, 9, 12, [15, 18]]

extend() — add each element of another list

extend() takes a list as argument and appends each of its elements individually to the end of the given list. Compare this with append() above:

>>> nums = [3, 6, 9]
>>> more = [12, 15]
>>> nums.extend(more)
>>> nums
[3, 6, 9, 12, 15]

insert() — add an element at a chosen position

insert(index, element) places the element at the given index, shifting later elements right:

>>> nums = [10, 30, 40]
>>> nums.insert(1, 20)     # put 20 at index 1
>>> nums
[10, 20, 30, 40]
>>> nums.insert(0, 5)      # put 5 at the front
>>> nums
[5, 10, 20, 30, 40]

count() — occurrences of an element

count() returns the number of times the given element appears in the list; a value that never appears gives 0:

>>> vals = [7, 2, 7, 9, 7, 4]
>>> vals.count(7)
3
>>> vals.count(100)
0

index() — position of the first occurrence

index() returns the index of the first occurrence of the element. If the element is not present at all, a ValueError is generated:

>>> vals = [7, 2, 7, 9, 7, 4]
>>> vals.index(7)
0
>>> vals.index(50)

ValueError: 50 is not in list

remove() — delete by value

remove() deletes the given value from the list. If the value occurs several times, only the first occurrence is removed; if it is not present, a ValueError is generated:

>>> vals = [4, 8, 12, 8, 16]
>>> vals.remove(8)
>>> vals
[4, 12, 8, 16]
>>> vals.remove(99)

ValueError: list.remove(x): x not in list

pop() — return and delete by index

pop(index) returns the element at the given index and simultaneously removes it from the list:

>>> vals = [11, 22, 33, 44, 55]
>>> vals.pop(2)
33
>>> vals
[11, 22, 44, 55]

Called with no argument, pop() returns and removes the last element:

>>> vals = [11, 22, 44, 55]
>>> vals.pop()
55
>>> vals
[11, 22, 44]

Note the contrast: remove() works by value and returns nothing; pop() works by index and hands the deleted element back to you.

reverse() — flip the order in place

reverse() reverses the order of the elements of the list in place — the list itself is modified and nothing is returned:

>>> vals = [14, 3, 92, 27]
>>> vals.reverse()
>>> vals
[27, 92, 3, 14]

>>> pets = ['Dog', 'Cat', 'Parrot', 'Rabbit']
>>> pets.reverse()
>>> pets
['Rabbit', 'Parrot', 'Cat', 'Dog']

sort() — arrange in place

sort() arranges the elements of the list in ascending order, again in place (the original ordering is lost). Strings are sorted alphabetically, numbers numerically:

>>> pets = ['Dog', 'Cat', 'Parrot', 'Rabbit']
>>> pets.sort()
>>> pets
['Cat', 'Dog', 'Parrot', 'Rabbit']

Passing the keyword argument reverse = True sorts in descending order instead:

>>> vals = [14, 3, 92, 27]
>>> vals.sort(reverse = True)
>>> vals
[92, 27, 14, 3]

sorted() — a sorted copy

The built-in function sorted() takes a list as parameter and creates a new list with the same elements arranged in sorted order. The original list is left exactly as it was — this is the key difference from sort():

>>> vals = [31, 8, 57, 12]
>>> ordered = sorted(vals)
>>> vals            # unchanged
[31, 8, 57, 12] …