List Methods and Built-in Functions

Lists come with a rich set of ready-made tools: methods that belong to the list type itself (called as list1.append(...), list1.sort(), and so on) and built-in functions that take a list as an argument (such as len(), min(), max(), sum(), sorted()). Knowing what each one does — and, just as importantly, whether it changes the original list or leaves it untouched — is essential for writing list-handling programs.

The table below summarises the tools covered here; detailed behaviour and examples follow.

Finding the size — len()

len() takes the list as its argument and returns its length, the total number of elements:

>>> list1 = [10, 20, 30, 40, 50]
>>> len(list1)
5

Creating lists — list()

Called with no argument, list() creates an empty list. Called with a sequence as the argument, it builds a list out of that sequence's items — passing a string, for instance, produces a list of its individual characters:

>>> list1 = list()
>>> list1
[]
>>> str1 = 'aeiou'
>>> list1 = list(str1)
>>> list1
['a', 'e', 'i', 'o', 'u']

Growing a list — append(), extend(), insert()

append() attaches a single element at the end of the list. If you append a list, that whole list goes in as one element — a nested list — not as several separate elements:

>>> list1 = [10, 20, 30, 40]
>>> list1.append(50)
>>> list1
[10, 20, 30, 40, 50]
>>> list1 = [10, 20, 30, 40]
>>> list1.append([50, 60])
>>> list1
[10, 20, 30, 40, [50, 60]]

extend() is the tool for merging: it takes a list and adds each of its elements individually at the end of the given list:

>>> list1 = [10, 20, 30]
>>> list2 = [40, 50]
>>> list1.extend(list2)
>>> list1
[10, 20, 30, 40, 50]

insert() places an element at any chosen position rather than at the end. It takes two arguments — the index and the element — and the existing elements from that index onwards shift right:

>>> list1 = [10, 20, 30, 40, 50]
>>> list1.insert(2, 25)      # 25 goes to index 2
>>> list1
[10, 20, 25, 30, 40, 50]
>>> list1.insert(0, 100)     # 100 goes to the front
>>> list1
[100, 10, 20, 25, 30, 40, 50]

Searching a list — count() and index()

count() returns how many times a given element occurs in the list; if the element is absent it simply returns 0:

>>> list1 = [10, 20, 30, 10, 40, 10]
>>> list1.count(10)
3
>>> list1.count(90)
0

index() returns the index of the first occurrence of an element. Unlike count(), it does not tolerate a missing element — if the element is not present, a ValueError is raised:

>>> list1 = [10, 20, 30, 20, 40, 10]
>>> list1.index(20)
1
>>> list1.index(90)
ValueError: 90 is not in list

Deleting elements — remove() and pop()

remove() deletes by value: it removes the given element from the list, and if the value occurs several times, only the first occurrence goes. Asking it to remove a value that is not in the list raises a ValueError:

>>> list1 = [10, 20, 30, 40, 50, 30]
>>> list1.remove(30)
>>> list1
[10, 20, 40, 50, 30]
>>> list1.remove(90)
ValueError: list.remove(x): x not in list

pop() deletes by position — and it also hands the deleted element back to you as its return value. With an index argument it removes the element at that index; with no argument it returns and removes the last element:

>>> list1 = [10, 20, 30, 40, 50, 60]
>>> list1.pop(3)
40
>>> list1
[10, 20, 30, 50, 60]
>>> list1 = [10, 20, 30, 40, 50, 60]
>>> list1.pop()
60
>>> list1
[10, 20, 30, 40, 50]

Rearranging a list — reverse(), sort() and sorted()

reverse() flips the order of the elements in place — the last becomes first and the first becomes last. It works on numbers and strings alike, because it does not compare elements at all, it only reverses their positions:

>>> list1 = [34, 66, 12, 89, 28, 99]
>>> list1.reverse()
>>> list1
[99, 28, 89, 12, 66, 34]
>>> list1 = ['Tiger', 'Zebra', 'Lion', 'Cat', 'Elephant', 'Dog']
>>> list1.reverse()
>>> list1
['Dog', 'Elephant', 'Cat', 'Lion', 'Zebra', 'Tiger']

sort() arranges the elements of the list in order, in place — the original arrangement is lost. Strings sort alphabetically, numbers numerically. Passing reverse = True sorts in descending order:

>>> list1 = ['Tiger', 'Zebra', 'Lion', 'Cat', 'Elephant', 'Dog']
>>> list1.sort()
>>> list1
['Cat', 'Dog', 'Elephant', 'Lion', 'Tiger', 'Zebra'] …