\chapter{Lists part 1}
A \myidx{list} is an ordered set of values, where each value is
identified by an index. The values that make up a list are called its
\myidx{elements} . Lists are similar to strings, which are ordered
sets of characters, except that the elements of a list can have any
type. Lists and strings---and other things that behave like ordered
sets---are called \myidx{sequences} .

\section{List values}
There are several ways to create a new list; the simplest is to
enclose the elements in square brackets (\pythoninline{[}~and~\pythoninline{]}):

\begin{minipage}{\textwidth}
\begin{python}
[10, 20, 30, 40]
["spam", "bungee", "swallow"]
\end{python}
\end{minipage}
The first example is a list of four integers. The second is a list of
three strings. The elements of a list don't have to be the same
type. The following list contains a string, a float, an integer, and
another list:

\begin{minipage}{\textwidth}
\begin{python}
["hello", 2.0, 5, [10, 20]]
\end{python}
\end{minipage}
A list within another list is said to be \myidx{nested} .
Finally, there is a special list that contains no elements. It is
called the empty list, and is denoted \pythoninline{[]}.
Like numeric 0 values and the empty string, the empty list is false
in a boolean expression:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> if []:
...    print 'This is true."
... else:
...    print 'This is false."
...
This is false.
>>>
\end{pythonInteractive}
\end{minipage}
With all these ways to create lists, it would be disappointing if we
couldn't assign list values to variables or pass lists as parameters
to functions. We can:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> vocabulary = ["ameliorate", "castigate", "defenestrate"]
>>> numbers = [17, 123]
>>> empty = []
>>> print vocabulary, numbers, empty
['ameliorate', 'castigate', 'defenestrate'] [17, 123] []
\end{pythonInteractive}
\end{minipage}

\section{Accessing elements}
The syntax for accessing the elements of a list is the same as the
syntax for accessing the characters of a string---the bracket
operator (\pythoninline{[]} -- not to be confused with an empty list). The
expression inside the brackets specifies the index. Remember that the
indices start at \pythoninline{0}:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> print numbers[0]
17
\end{pythonInteractive}
\end{minipage}
Any integer expression can be used as an index:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> numbers[9-8]
5
>>> numbers[1.0]
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
TypeError: list indices must be integers
\end{pythonInteractive}
\end{minipage}
If you try to read or write an element that does not exist, you get a
runtime error:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> numbers[2]
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
IndexError: list index out of range
\end{pythonInteractive}
\end{minipage}
If an index has a negative value, it counts backward from the end of
the list:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> numbers[-1]
5
>>> numbers[-2]
17
>>> numbers[-3]
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
IndexError: list index out of range
\end{pythonInteractive}
\end{minipage}
\pythoninline{numbers[-1]} is the last element of the list,
\pythoninline{numbers[-2]} is the
second to last, and \pythoninline{numbers[-3]} doesn't exist.
It is common to use a loop variable as a list index.

\begin{minipage}{\textwidth}
\begin{python}
horsemen = ["war", "famine", "pestilence", "death"]
  
i = 0
while i < 4:
   print horsemen[i]
   i += 1
\end{python}
\end{minipage}
This while loop counts from 0 to 4. When the loop variable
\pythoninline{i} is 4, the condition fails and the loop terminates. So
the body of the loop is only executed when \pythoninline{i} is 0, 1,
2, and 3. Each time through the loop, the variable \pythoninline{i} is
used as an index into the list, printing the i\textsuperscript{th} element. This
pattern of computation is called a \myidx{list traversal}.

\section{List length}
The function \pythoninline{len} returns the length of a list, which is
equal to the number of its elements. It is a good idea to use this
value as the upper bound of a loop instead of a constant. That way, if
the size of the list changes, you won't have to go through the program
changing all the loops; they will work correctly for any size list:

\begin{minipage}{\textwidth}
\begin{python}
horsemen = ["war", "famine", "pestilence", "death"]
  
i = 0
num = len(horsemen)
while i < num:
   print horsemen[i]
   i += 1
\end{python}
\end{minipage}
The last time the body of the loop is executed, \pythoninline{i} is
\pythoninline{len(horsemen)~-~1}, which is the index of the last
element. When \pythoninline{i} is equal to
\pythoninline{len(horsemen)}, the condition fails and the body is not
executed, which is a good thing, because \pythoninline{len(horsemen)}
is not a legal index.

Although a list can contain another list, the nested list still
counts as a single element. The length of this list is 4:

\begin{minipage}{\textwidth}
\begin{python}
['spam!', 1, ['Brie', 'Roquefort', 'Pol le Veq'], [1, 2, 3]]
\end{python}
\end{minipage}

\section{List membership}
\pythoninline{in} is a boolean operator that tests membership in a
sequence. We used 
it previously with strings, but it also works with lists and other
sequences:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> horsemen = ['war', 'famine', 'pestilence', 'death']
>>> 'pestilence' in horsemen
True
>>> 'debauchery' in horsemen
False
\end{pythonInteractive}
\end{minipage}
Since \pythoninline{pestilence} is a member of the
\pythoninline{horsemen} list, the \pythoninline{in} operator returns
\pythoninline{True}. Since \pythoninline{debauchery} is not in the
list, \pythoninline{in} returns \pythoninline{False}. 
We can use \pythoninline{not} in combination with \pythoninline{in} to
test whether an element is not a member of a list:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> 'debauchery' not in horsemen
True
\end{pythonInteractive}
\end{minipage}

\section{List operations}
The \pythoninline{+} operator concatenates lists:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a = [1, 2, 3]
>>> b = [4, 5, 6]
>>> c = a + b
>>> print c
[1, 2, 3, 4, 5, 6]
\end{pythonInteractive}
\end{minipage}
Similarly, the \pythoninline{*} operator repeats a list a given number
of times: 

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> [0] * 4
[0, 0, 0, 0]
>>> [1, 2, 3] * 3
[1, 2, 3, 1, 2, 3, 1, 2, 3]
\end{pythonInteractive}
\end{minipage}
The first example repeats \pythoninline{[0]} four times. The second
example repeats the list \pythoninline{[1, 2, 3]} three times. 

\section{List slices}
The slice operations we saw with strings also work on lists:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a_list = ['a', 'b', 'c', 'd', 'e', 'f']
>>> a_list[1:3]
['b', 'c']
>>> a_list[:4]
['a', 'b', 'c', 'd']
>>> a_list[3:]
['d', 'e', 'f']
>>> a_list[:]
['a', 'b', 'c', 'd', 'e', 'f']
\end{pythonInteractive}
\end{minipage}

\section{The range function}
Lists that contain consecutive integers are common, so Python
provides a simple way to create them:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(1, 5)
[1, 2, 3, 4]
\end{pythonInteractive}
\end{minipage}
The range function takes two arguments and returns a list that
contains all the integers from the first to the second, including the
first but \emph{not the second}.
There are two other forms of range. With a single argument, it
creates a list that starts at 0:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
\end{pythonInteractive}
\end{minipage}
If there is a third argument, it specifies the space between
successive values, which is called the \myidx{step size} . This
example counts from 1 to 10 by steps of 2:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(1, 10, 2)
[1, 3, 5, 7, 9]
\end{pythonInteractive}
\end{minipage}
If the step size is negative, then start must be greater than stop

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(20, 4, -5)
[20, 15, 10, 5]
\end{pythonInteractive}
\end{minipage}
or the result will be an empty list.

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(10, 20, -5)
[]
\end{pythonInteractive}
\end{minipage}

\section{Lists are mutable}
Unlike strings, lists are \myidx{mutable} , which means we can
change their elements. Using the bracket operator on the left side of
an assignment, we can update one of the elements:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> fruit = ["banana", "apple", "quince"]
>>> fruit[0] = "pear"
>>> fruit[-1] = "orange"
>>> print fruit
['pear', 'apple', 'orange']
\end{pythonInteractive}
\end{minipage}
The bracket operator applied to a list can appear anywhere in an
expression. When it appears on the left side of an assignment, it
changes one of the elements in the list, so the first element of
\pythoninline{fruit} has been changed from \pythoninline{'banana'} to
\pythoninline{'pear'}, and the last from \pythoninline{'quince'} to
\pythoninline{'orange'}. An assignment to an element of a list is
called \myidx{item assignment} . Item assignment does not work for
strings:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> my_string = 'TEST'
>>> my_string[2] = 'X'
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
\end{pythonInteractive}
\end{minipage}
but it does for lists:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> my_list = ['T', 'E', 'S', 'T']
>>> my_list[2] = 'X'
>>> my_list
['T', 'E', 'X', 'T']
\end{pythonInteractive}
\end{minipage}
With the slice operator we can update several elements at once:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a_list = ['a', 'b', 'c', 'd', 'e', 'f']
>>> a_list[1:3] = ['x', 'y']
>>> print a_list
['a', 'x', 'y', 'd', 'e', 'f']
\end{pythonInteractive}
\end{minipage}
We can also remove elements from a list by assigning the empty list
to them:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a_list = ['a', 'b', 'c', 'd', 'e', 'f']
>>> a_list[1:3] = []
>>> print a_list
['a', 'd', 'e', 'f']
\end{pythonInteractive}
\end{minipage}
And we can add elements to a list by squeezing them into an empty
slice at the desired location:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a_list = ['a', 'd', 'f']
>>> a_list[1:1] = ['b', 'c']
>>> print a_list
['a', 'b', 'c', 'd', 'f']
>>> a_list[4:4] = ['e']
>>> print a_list
['a', 'b', 'c', 'd', 'e', 'f']
\end{pythonInteractive}
\end{minipage}

\section{List deletion}
Using slices to delete list elements can be awkward, and therefore
error-prone. Python provides an alternative that is more readable.
\pythoninline{del} removes an element from a list:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a = ['one', 'two', 'three']
>>> del a[1]
>>> a
['one', 'three']
\end{pythonInteractive}
\end{minipage}
As you might expect, \pythoninline{del} handles negative indices and causes a
runtime error if the index is out of range.
You can use a slice as an index for del:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a_list = ['a', 'b', 'c', 'd', 'e', 'f']
>>> del a_list[1:5]
>>> print a_list
['a', 'f']
\end{pythonInteractive}
\end{minipage}
As usual, slices select all the elements up to, but not including,
the second index.

\section{Objects and values}
If we execute these assignment statements,

\begin{minipage}{\textwidth}
\begin{python}
a = "banana"
b = "banana"
\end{python}
\end{minipage}
we know that \pythoninline{a} and \pythoninline{b} will refer to a
string with the letters \pythoninline{``banana''}. But we can't tell
whether they point to the \emph{same} string. 
There are two possible states:

\includegraphics[scale=1]{figures/list1-fig}

In one case, \pythoninline{a} and \pythoninline{b} refer to two
different things that have the same value. In the second case, they
refer to the same thing. These things have names---they are called
\myidx{objects} . An object is something a variable can refer to.
Every object has a unique \myidx{identifier} , which we can obtain
with the id function. By printing the identifier of \pythoninline{a}
and \pythoninline{b}, we can tell whether they refer to the same object.

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> id(a)
135044008
>>> id(b)
135044008
\end{pythonInteractive}
\end{minipage}
In fact, we get the same identifier twice, which means that Python
only created one string, and both \pythoninline{a} and
\pythoninline{b} refer to it. Your actual \pythoninline{id} value will
be probably be different. 

Interestingly, lists behave differently. When we create two lists, we
get two objects:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a = [1, 2, 3]
>>> b = [1, 2, 3]
>>> id(a)
135045528
>>> id(b)
135041704
\end{pythonInteractive}
\end{minipage}
So the state diagram looks like this:

\includegraphics[scale=1]{figures/list2-fig}

\pythoninline{a} and \pythoninline{b} have the same value but do not
refer to the same object. 

\section{Aliasing}
Since variables refer to objects, if we assign one variable to
another, both variables refer to the same object:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a = [1, 2, 3]
>>> b = a
>>> id(a) == id(b)
True
\end{pythonInteractive}
\end{minipage}
In this case, the state diagram looks like this:

\includegraphics[scale=1]{figures/list3-fig}

Because the same list has two different names, \pythoninline{a} and
\pythoninline{b}, we say that 
it is \myidx{aliased} . Changes made with one alias affect the
other:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> b[0] = 5
>>> print a
[5, 2, 3]
\end{pythonInteractive}
\end{minipage}
Although this behaviour can be useful, it is sometimes unexpected or
undesirable. In general, it is safer to avoid aliasing when you are
working with mutable objects. Of course, for immutable objects,
there's no problem. That's why Python is free to alias strings when
it sees an opportunity to economize.

\section{Cloning lists}
If we want to modify a list and also keep a copy of the original, we
need to be able to make a copy of the list itself, not just the
reference. This process is sometimes called \myidx{cloning} , to
avoid the ambiguity of the word copy.
The easiest way to clone a list is to use the slice operator:

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> a = [1, 2, 3]
>>> b = a[:]
>>> print b
[1, 2, 3]
\end{pythonInteractive}
\end{minipage}
Taking any slice of \pythoninline{a} creates a new list. In this case the slice
happens to consist of the whole list.
Now we are free to make changes to \pythoninline{b} without worrying
about \pythoninline{a}: 

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> b[0] = 5
>>> print a
[1, 2, 3]
\end{pythonInteractive}
\end{minipage}

\section{Glossary}
\begin{description}
\item[list:]A named collection of objects, where each object is
  identified by an index.
\item[index:]An integer variable or value that indicates an element
  of a list.
\item[element:]One of the values in a list (or other sequence). The
  bracket operator selects elements of a list.
\item[sequence:]Any of the data types that consist of an ordered set
  of elements, with each element identified by an index.
\item[nested list:]A list that is an element of another list.
\item[step size:]The interval between successive elements of a linear
  sequence. The third (and optional argument) to the range function
  is called the step size. If not specified, it defaults to 1.
\item[list traversal:]The sequential accessing of each element in a
  list.
\item[mutable type:]A data type in which the elements can be
  modified. All mutable types are compound types. Lists are mutable
  data types; strings are not.
\item[object:]A thing to which a variable can refer.
\item[aliases:]Multiple variables that contain references to the same
  object.
\item[clone:]To create a new object that has the same value as an
  existing object. Copying a reference to an object creates an alias
  but doesn't clone the object.

\end{description}

\newpage
\section{Laboratory exercises}

\begin{enumerate}
\item Write a loop that traverses:

\begin{minipage}{\textwidth}
\begin{python}
['spam!', 1, ['Brie', 'Roquefort', 'Pol le Veq'], [1, 2, 3]]
\end{python}
\end{minipage}
and prints the length of each element. What happens if you send an
integer to \pythoninline{len}? Change \pythoninline{1} to
\pythoninline{'one'} and run your solution again. 

\item What is the Python interpreter's response to the following?

\begin{minipage}{\textwidth}
\begin{pythonInteractive}
>>> range(10, 0, -2) 
\end{pythonInteractive}
\end{minipage}
The three arguments to the \pythoninline{range} function are
\pythoninline{start}, 
\pythoninline{stop}, and \pythoninline{step}, respectively. In this example,
\pythoninline{start} is greater than \pythoninline{stop}. What happens
if \pythoninline{start~$<$~stop} and \pythoninline{step~$<$~0}? Write
a rule for the relationships among \pythoninline{start},
\pythoninline{stop}, and \pythoninline{step}. 
\begin{answerspace}

zend
\end{answerspace}

\item Consider the following code:

\begin{minipage}{\textwidth}
\begin{python}
a = [1, 2, 3]
b = a[:]
b[0] = 5
\end{python}
\end{minipage}
Draw a state diagram for \pythoninline{a} and \pythoninline{b} before
and after the third line is executed.

\begin{answerspace}



zend
\end{answerspace}

\item What will be the output of the following program?

\begin{minipage}{\textwidth}
\begin{python}
this = ['I', 'am', 'not', 'a', 'crook']
that = ['I', 'am', 'not', 'a', 'crook']
print "Test 1: %s" % (id(this) == id(that))
that = this
print "Test 2: %s" % (id(this) == id(that))
\end{python}
\end{minipage}
Provide a \emph{detailed} explanation of the results.

\begin{answerspace}



zend
\end{answerspace}

\item Write a function \pythoninline{add\_lists(a, b)} that takes two lists of
  numbers of the same length, and returns a new list containing the
  sums of the corresponding elements of each.

\begin{minipage}{\textwidth}
\begin{python}
def add_lists(a, b):
   """
     >>> add_lists([1, 1], [1, 1])
     [2, 2]
     >>> add_lists([1, 2], [1, 4])
     [2, 6]
     >>> add_lists([1, 2, 1], [1, 4, 3])
     [2, 6, 4]
   """
\end{python}
\end{minipage}
\pythoninline{add\_lists} should pass the doctests above.
\item Write a function \pythoninline{mult\_lists(a, b)} that takes two
lists of numbers of the same length, and returns the sum of the
products of the corresponding elements of each. 

\begin{minipage}{\textwidth}
\begin{python}
def mult_lists(a, b):
   """
     >>> mult_lists([1, 1], [1, 1])
     2
     >>> mult_lists([1, 2], [1, 4])
     9
     >>> mult_lists([1, 2, 1], [1, 4, 3])
     12
   """
\end{python}
\end{minipage}
Verify that \pythoninline{mult\_lists} passes the doctests above.

\item \emph{Extension Exercise:} Write a function called
  \pythoninline{flatten\_list} that takes as input a list which may be
  nested, and returns a non-nested list with all the elements of the
  input list.

\begin{minipage}{\textwidth}
\begin{python}
def flatten_list(alist):
    '''
       >>> flatten_list([1,2,3])
       [1, 2, 3]
       >>> flatten_list([1, [2,3], [4, 5], 6])
       [1, 2, 3, 4, 5, 6]
    '''
\end{python}
\end{minipage}
Is your solution general enough to allow any level of nesting? If not,
can you make it so?
\end{enumerate}


