\documentclass[11pt]{article}
\usepackage[backref, colorlinks=true, citecolor=red, urlcolor=blue]{hyperref}

\newcommand{\handout}[5]{
  \noindent
  \begin{center}
  \framebox{
    \vbox{
      \hbox to 5.0in { {\bf } \hfill #2 }
      \vspace{4mm}
      \hbox to 5.0in { {\Large \hfill #5  \hfill} }
      \vspace{2mm}
      \hbox to 5.0in { {\em #3 \hfill #4} }
    }
  }
  \end{center}
  \vspace*{4mm}
}

\newcommand{\lecture}[4]{\handout{#1}{#2}{#3}{#4}{#1}}

\parindent 0in
\parskip 1.5ex

\begin{document}

\lecture{Midterm Exam Report}{Fall 2017}{SRIVATS BHARADWAJ}{Advance Algorithm Programming}

\section{Summary of the two methods}

\subsection{Hedcutter method}
Algorithms for computing Voronoi diagram:
An ordinary Voronoi diagram is formed by a set of points in the plane called the generators or generating points. Every point in the plane is identified with the generator which is closest to it by some metric. The common choice is to use the Euclidean L2 distance metric.

The algorithm draws a set of right cones with their apexes at each generator. The cones all have the same height and are viewed from above the apexes with an orthogonal projection. In addition, each cone is given a unique colour which acts as the generator’s identity. Since the cones must intersect if there is more than one generator, the z-buffer determines for each pixel which cone is closer to the viewer and assigns that pixel the appropriate colour value. We can then scan the resulting image and determine which generator is closest to each pixel by using the unique colours. This technique allows us to compute discrete Voronoi diagrams extremely quickly and perform computations on the resulting regions.

\subsection{Voronoi method}
A centroidal Voronoi diagram has the interesting property that each generating point lies exactly on the centroid of its Voronoi region. The centroid of a region is defined as

where A is the region, x is the position and r (x) is the density function. For a region of constant density r , the centroid can be considered as the centre of mass.
A centroidal Voronoi diagram is a minimum-energy configuration in the sense that it minimizes.

Stippling with Weighted CVDs
The centroidal Voronoi diagrams incorporate the idea of a density function r (x; y) which weights the centroid calculation. Regions with higher values of r will pack generating points closer than regions with lower values. During the iteration of Algorithm 1, the darker regions of the image appear to “attract” more points. We can use Algorithm 1 directly to generate high-quality stippling images by treating a grayscale image as a discrete two dimensional function f (x; y) where x; y ϵ [0; 1] and 0 ≤ f (x; y) ≤ 1
is the range from a black pixel to a white pixel. Define a density function ρ(x, y) = 1- f (x, y).

\section{Comparison of the two methods}

Q1. Do you get the same results by running the same program on the same image multiple times?\\
A1. No. I got  slightly different results even though the command arguments were the same.
Because the starting points in the calcu\-lation of the Voronoi regions randomly selected.

Q2. If you vary the number of the disks in the output images,  do these implementations produce
the same distribution in the final image? If not, why?\\
A2. Both implementations produce different distribution in the final image because theys use
various convergence criteria.

Q3. If you vary the number of the disks in the output images,  is a method faster than the other? \\
A3. {\it voronoi} method is faster.

Q4. Does the size (number of pixels), image brightness or contrast of image increase or decrease their difference? \\
A4. The number of pixels, image brightness and contrast of image increase the difference between methods.

Q5. Does the type of image (human vs. machine,  natural vs. urban landscapes, photo vs. painting, etc) increase or
decrease their difference? \\
A5. I did not notice the difference between methods depending on the type of image.

Q6. Are the outputs of these stippling methods different  the hedcut images created by artists (e.g. those from the
\href{http://www.wsj.com/articles/SB10001424052748704207504575129961786135180}{Wall Street Journal})? \\
A6. In the images generated by the program, the regular structure of Voronoi regions is clearly visible.

\section{Improvement of hedcuter method}

\end{document}


\clearpage
\subsection{Small DB 2, the linked version in C} % (fold)
\label{sub:small_db_2_the_linked_version}

% subsection small_db_2_the_linked_version (end)
\sref{sec:using_dynamic_memory_allocation}, \nameref{sec:using_dynamic_memory_allocation}, introduced a version of the Small DB program with a linked structure, as opposed to the array structure used to manage the rows in \cref{cha:more_data_types}. The C code for the altered functions and procedures is shown in \lref{clst:linked-db}, the original version can be found in \lref{lst:c-small-db}.

\straightcode{\ccode{clst:linked-db}{C code for the linked version of Small DB, see \lref{lst:c-small-db} for the array version of this program}{code/c/dynamic-memory/linked-db-for-chap.c}}

\mynote{
\begin{itemize}
  \item \texttt{print\_all}, \texttt{delete\_a\_row}, and \texttt{add\_a\_row} are the only procedures that have changed significantly.
  \item Each of these is explained in more detail in \sref{sec:using_dynamic_memory_allocation}.
  \item Each row has a pointer to the next row in the database, this will point to nothing in the last row.
\end{itemize}
}


\chapter{Arrays and lists}
\label{arrays}

This chapter presents some of Perl's most useful built-in types,
arrays and lists.

\section{Lists and arrays are sequences}
\label{sequence}

Like strings, {\bf lists} and {\bf arrays} are sequences of
values.  In a string, the values are characters; in a list or
in an array, they can be any type.  The values in a list or
in an array are called {\bf elements} or sometimes {\bf items}.
\index{list}
\index{array}
\index{type!list}
\index{type!array}
\index{element}
\index{sequence}
\index{item}

There are several important differences between lists and arrays. The main ones
are that lists are ordered and immutable collections of items:
you can't change the number of items in a list and you can't
change the individual items either. Arrays, by contrast, are
variables and are generally mutable: you can add elements
to an array, or remove elements from it. And you can access
the individual elements of an array and modify them. For this
to be possible, arrays usually have a name (as do other variables),
although some arrays are anonymous, which means that they
have no name, but have some other ways or accessing them.

A list is also ephemeral (unless it is assigned
to a variable or some other thing): it ceases to exist as
soon as it has been used, usually as soon as the program
control flow goes to the next code line. An array, on the
other hand, has some form of persistence: you may be able to
use it somewhere else in the program if the variable
containing it is still within scope.

There are several ways to create a new list; the simplest is
to enumerate its values, separated by commas:
\index{comma operator}
\index{operator!comma}

\begin{verbatim}
> 3, 4, 5
(3 4 5)
> say (3, 4, 5).WHAT;
(List)
say $_ for 1, 2, 3;
1
2
3
\end{verbatim}
%

You don't need the parentheses to create a list, but they are
often useful to delimit it, i.e. to stipulate where
it starts and where it ends, and, in some cases, to override
precedence.

We have been using lists earlier in this book. If we write:

\begin{verbatim}
> print "$_ " for 1, 3, 5, 9, "\n";
1 3 5 9
 >
> print "$_ " for 1..10;
1 2 3 4 5 6 7 8 9 10 >
\end{verbatim}

we are basically creating and using a list of integers (from
the standpoint of the type hierarchy of Perl; this observation is
not entirely accurate technically for the second example, since
\verb'1..10' has a \emph{Range} type, and it gets
transformed into a \emph{Seq} type, but this approximation is
good enough for our purpose here).
\index{range!type}
\index{range!operator}

Arrays are variables whose names start with the sigil \verb'@'.
Named arrays  need to be declared before they are used, just
as any other variable we've seen so far (except the topical
variable, \verb'$_'). One of the easiest
ways to create an array is to assign a list to it:
\index{topical variable}
\index{sigil}

\begin{verbatim}
> my @odd_digits = 1, 3, 5, 7, 9;
[1 3 5 7 9]
> say @odd_digits.WHAT;
(Array)
> my @single_digit_numbers = 0..9;
[0 1 2 3 4 5 6 7 8 9]
\end{verbatim}

Under the Perl REPL, an array is displayed between square
brackets (\verb"[" and \verb"]"), while lists are displayed
between round parentheses.
\index{REPL}
\index{square bracket operator}
\index{operator!square bracket}
\index{bracket!square}

If the items don't contain any space characters, it is quite handy
to construct a list (and assign it to an array if needed) using
the \verb'<...>' quote-word operator:
\index{quote-word operator}

\begin{verbatim}
> my @weekdays = <mon tue wed thu fri>;
[mon tue wed thu fri]
> my @weekend = <sat sun>;
[sat sun]
\end{verbatim}

The advantage of this construction is that there is no need to
separate the items with commas and no need to insert them between
quotes when the items are strings. Basically,
the quote-word operator breaks up its content on whitespace
and returns a list of words, which can then be
used in a loop or assigned to an array as in the example
above.

Most of the rest of this chapter will be devoted to arrays
rather than lists, but keep in mind that many of the array
functions and operators we will study here also work on lists
(at least most of those that would not violate the
immutability property of lists).

The items of an array (or a list) don't need to be of the
same type:

\begin{verbatim}
> my @heterogeneous-array = 1, 2.3, pi, "str", (1, 2, 4);
[1 2.3 3.14159265358979 str (1 2 4)]
\end{verbatim}

Here, the array is composed of an integer, a rational, a
float ({\tt Num} type), a string and a list of three integers.
It may not be advisable for the sake of the developer's
mental sanity to use an array with such wildly heterogeneous
items, but Perl will not complain about that: it is up
to you to make sense of your data.

The array above contains even a list of items. If you iterate
over the elements of this array for example with a {\tt for}
loop statement, this list will come as one distinct element,
it will not get ``flattened'' as three elements
of the array. Similarly, {\tt elems} is a method to
count the number of items of an array (or of a list).
Using it on the above array produces the following result:

\begin{verbatim}
> say @heterogeneous-array.elems;
5
\end{verbatim}
%

As you can see, the \verb'(1, 2, 4)' list ``counts''
as one single array element.

A list within another list is {\bf nested}.
\index{nested list}
\index{list!nested}

An array that contains no elements is
called an empty array; you can create one with empty
parentheses, \verb"()":
\begin{verbatim}
> my @empty = ();
[]
\end{verbatim}
\index{empty list}
\index{list!empty}

But this is rarely useful, since just declaring an array
without defining it has the same effect:

\begin{verbatim}
> my @empty;
[]
\end{verbatim}

So using the empty brackets would be needed essentially for
resetting an existing array to an empty array.

\section{Arrays are mutable}
\label{mutable}
\index{list!element}
\index{access}
\index{index}
\index{subscript}
\index{bracket operator}
\index{operator!bracket}
\index{bracket!square}

\index{index!starting at zero}
\index{coercion}
The syntax for accessing the elements of an array or a list
uses the square brackets operator.  The expression inside the
brackets specifies the index or subscript, which can be a
literal integer (or some value that can be coerced into
an integer), a variable containing a numerical value, a list
or a range of numerical values, an expression or a piece
of code returning a numerical value, etc.  Indices are offsets
compared to the beginning of the array
or the list (much in the same way as the values returned
by the {\tt index} function on strings), so that they start
at 0. Thus, the first item of an array has the index 0, the
second item the index 1, and so on:
\index{zero, index starting at}

\begin{verbatim}
say <sat sun>[1];             # -> sun  (accessing a list item)
my @weekdays = <mon tue wed thu fri>;     # assigning an array
say "The third day is @weekdays[2]";      # -> The third day is wed
\end{verbatim}
%

You may also use ranges or lists of indices to access
\emph{slices} of an array or a list:
\index{slice}
\index{slice!operator}
\index{operator!slice}
\index{index!slice}
\index{list!slice}
\index{slice!list}
\index{range}

\begin{verbatim}
> my @even-digits = 0, 2, 4, 6, 8;
[0 2 4 6 8]
> my @small-even_digits = @even-digits[0..2];
[0 2 4]
> my @min-max-even-digits = @even-digits[0, 4]
[0 8]
\end{verbatim}

If you need a slice in the opposite order, you can use the
{\tt reverse} function to reverse the range:

\begin{verbatim}
> my @reverse-small-even_digits = @even-digits[reverse 0..2];
[4 2 0]
\end{verbatim}

or reverse the data returned by the slice expression:

\begin{verbatim}
> my @reverse-small-even_digits = reverse @even-digits[0..2];
[4 2 0]
\end{verbatim}

Unlike lists, arrays are mutable.  When the bracket operator
appears after an array on the left side of an assignment,
it identifies the element of the array that will be assigned.
\index{mutability}

\begin{verbatim}
> my @even-digits = 0, 2, 2, 6, 8;   # Oops, error on the second 2
[0 2 2 6 8]
> @even-digits[2] = 4; # fixing the faulty third digit
4
> say @even-digits
[0 2 4 6 8]
\end{verbatim}
%

The third element of {\tt \@even-digits}, which was
(presumably by mistake) 2, is now 4. If the index corresponds
to an item which does not exist yet in the array, the array
will be expanded to include the new element:

\begin{verbatim}
> my @odds = 1, 3, 5;
[1 3 5]
> @odds[3] = 7;
7
> say @odds;
[1 3 5 7]
\end{verbatim}

\index{index!starting at zero}
\index{item assignment}
\index{assignment!item}
\index{reassignment}

\index{elems function or method}
\index{end method}
The {\tt elems} function or method returns the number of
elements of an array. The {\tt end} function or method
returns the index of the last elements of an array:

\begin{verbatim}
my @nums = 1..5;      # -> [1 2 3 4 5]
say @nums.elems;      # -> 5
say elems @nums;      # -> 5
say @nums.end;        # -> 4
\end{verbatim}

The {\tt end} method returns the result of the {\tt elems}
method minus one because, since indices start at 0, the
index of the last element is one less than the number
of elements.
\index{zero, index starting at}

The {\tt unique} function or method returns a sequence
of unique elements of the input list or array (i.e.
it returns the original list without any duplicate
values):
\index{unique function}
\index{function!unique}

\begin{verbatim}
> say < a b d c a f d g>.unique;
(a b d c f g)
\end{verbatim}

If you know that the input is sorted (and that, therefore,
duplicates are adjacent), use the {\tt squish} function
instead of {\tt unique}, as this is likely to be more
efficient. The {\tt squish} function removes adjacent
duplicates.
\index{squish function}
\index{function!squish}

To know whether two arrays are identical (structurally the
same, same type and same values), use the {\tt eqv} equivalence
operator. To know whether they just contain the same elements, use
the \verb'~~' smart match operator. Between two arrays or lists, the
\verb'==' numeric equality operator will return {\tt True} if the
arrays have the same number of elements and {\tt False} otherwise,
because \verb'==' coerces its arguments to Numeric type, so that
it compares the number of elements.
\index{eqv operator}
\index{coercion}
\index{equivalence operator}4\index{operator!eqv}
\index{smart match operator}
\index{operator!smart match}
\index{numeric equality operator}
\index{operator!numeric equality}

\begin{verbatim}
> my @even1 = 0, 2, 4, 6, 8;
[0 2 4 6 8]
> my @even2 = reverse 8, 6, 4, 2, 0;
[0 2 4 6 8]
> say @even1 eqv @even2           # same items, structurally the same
True
> say <1 2 3 4 5> eqv 1..5;       # same items, structurally different
False
> say <1 2 3 4 5> ~~ 1..5;        # same items, True
True
> my @array = 1..5;
[1 2 3 4 5]
>  say <1 2 3 4 5> ~~ @array;     # same elements, True
True
>  say <1 2 3 4 6> ~~ @array;     # not the same elements
False
> say <1 2 3 4 5> == <5 6 7 8 9>; # compares the numbers of items
True
\end{verbatim}

The \verb'<1 2 3 4 5> eqv 1..5' statement returns False because,
although they have the same items, the arguments are structurally
different entities (one is a list and the other one a range).

\section{Adding new elements to an array or removing some}

We've just seen that assigning an item to an index that does
not exists yet will expand the array. There are other
ways of expanding an array.

Perl has operators to add elements to, or remove one element
from, an array:
\index{pop function}
\index{push function}
\index{shift function}
\index{unshift function}

\begin{itemize}
\item {\tt shift}: removes the first item of an array and returns it;
\item {\tt pop}: removes the last item of an array and returns it;
\item {\tt unshift}: adds an item or a list of items to the
beginning of an array;
\item {\tt push}: adds an item or a list of items to the
end of an array;
\end{itemize}

These are a few examples for each:

\begin{verbatim}
> my @numbers = <2 4 6 7>;
[2 4 6 7]
> push @numbers, 8, 9;
[2 4 6 7 8 9]
> unshift @numbers, 0, 1;
[0 1 2 4 6 7 8 9]
> my $num = shift @numbers
0
> $num = pop @numbers
9
> say @numbers
[1 2 4 6 7 8]
\end{verbatim}

As you might expect by now, these routines also come with a
method invocation syntax. For example:
\index{invocation!method}
\index{method invocation}

\begin{verbatim}
> my @numbers = <2 4 6 7>;
[2 4 6 7]
> @numbers.push(8, 9)
[2 4 6 7 8 9]
\end{verbatim}

Note, however, that if you {\tt push} or {\tt unshift} an
array onto another array, you'll get something different
than what you might expect:

\begin{verbatim}
> my @numbers = <2 4 6 7>;
[2 4 6 7]
> my @add-array = 8, 10;
[8 10]
> @numbers.push(@add-array);
[2 4 6 7 [8 10]]
\end{verbatim}

As you can see, when \verb'@add-array' is added as an entity
to the \verb'@numbers' array, \verb'@add-array' becomes
the new last item of the original array. If you want to
add the items of \verb'@add-array' to the original array,
you may use the {\tt append} method instead of {\tt push}:

\begin{verbatim}
> my @numbers = <2 4 6 7>;
[2 4 6 7]
> @numbers.append(@add-array);
[2 4 6 7 8 10]
\end{verbatim}

Or you can use the ``|'' prefix operator to flatten the
added array into a list of arguments:

\begin{verbatim}
> my @numbers = <2 4 6 7>;
[2 4 6 7]
> @numbers.push(|@add-array);
[2 4 6 7 8 10]
\end{verbatim}

There is also a {\tt prepend} method which can replace
{\tt unshift} to add individual items of an array at the
beginning of an existing array (instead of adding the array
as a single entity).

\section{Stacks and queues}
\label{stacks_queues}

\index{stack}
\index{queue}
Stack and queues are very commonly used data structures in
computer science.

\index{LIFO (last in / first out)}
\index{last in / first out (LIFO)}
A stack is a \emph{last in / first out (LIFO)} data structure. Think of
piled-up plates. When you put a clean plate onto the stack,
you usually put it on top; when you take out one, you also
take it from the top. So the first plate that you take
is the last one that you added. A CS stack implements the same
idea: you use it when the first piece of data you need from a
data structure is the last one you added.

\index{FIFO (first in / first out)}
\index{first in / first out (FIFO)}
A queue, by contrast, is a \emph{first in / first out (FIFO)} data
structure. This is the idea of persons standing in a
line waiting to pay at the supermarket. The first
person that will be served is the first person who entered
the queue.

A stack may be implemented with an array and the {\tt push}
and {\tt pop} functions, which respectively add an item (or
several) at the end of an array and take one from the end of
the array. This is a somewhat simplistic implementation of
a stack:
\index{pop function}
\index{push function}
\index{function!pop}
\index{function!push}
\label{stack_code}

\begin{verbatim}
sub put-in-stack (@stack, $new_item) {
    push @stack, $new_item;
}
sub take-from-stack (@stack) {
    my $item = pop @stack;
    return $item;
}
my @a-stack = 1, 2, 3, 4, 5;
put-in-stack @a-stack, 6;
say @a-stack;
say take-from-stack @a-stack for 1..3;
\end{verbatim}

This example will print this:

\begin{verbatim}
[1 2 3 4 5 6]
6
5
4
\end{verbatim}

\index{stack}
This stack is simplistic because, at the very least, a more
robust implementation should do something sensible when you
try to {\tt take-from-stack} from an empty stack. It would
also be wise to add signatures to the subroutines. In
addition, you might want to {\tt put-in-stack} more than
one element in one go. Take a look at the solution to the
exercise on queues below (Subsection~\ref{sol_exercise_queue})
to figure out on how this stack may be improved.
\index{signature}
\index{subroutine signature}

You could obtain the same stack features using the
{\tt unshift} and {\tt shift} functions instead of {\tt push}
and {\tt pop}. The items will be added at the beginning of
the array and taken from the beginning, but you will still
have the LIFO behavior.
\index{shift function}
\index{unshift function}
\index{push function}
\index{LIFO}

\label{exercise_queue}
As an exercise, try to implement a FIFO queue on the same model.
Hint: you probably want to use an array and the {\tt unshift}
and {\tt pop} functions (or the {\tt push} and {\tt shift} functions). Solution: \ref{sol_exercise_queue}.
\index{queue}
\index{shift function}
\index{unshift function}
\index{push function}
\index{pop function}
\index{FIFO}

\section{Other ways to modify an array}
\label{modify_array}

The {\tt shift} and {\tt pop} functions remove respectively
the first and the last item of an array and return that
item. It is possible to do almost the same operation on any item
of an array, using the {\tt delete} \emph{adverb}:

\begin{verbatim}
my @fruit = <apple banana pear cherry pineapple orange>;
my $removed = @fruit[2]:delete;
say $removed;  # -> pear
say @fruit;    # -> [apple banana (Any) cherry pineapple orange]
\end{verbatim}

Notice that the third element (``pear'') is removed and
returned, but the array is not reorganized, the operation leaves
a sort of ``empty slot'', an undefined item, in the
middle of the array. The colon ``:'' syntax used here is the
operator for an adverb (we discussed adverbs in
Section~\ref{regex} about regexes);
for the time being, you may think of it as a kind of special
method operating on one element of an item collection.

We have seen how to use array slices to retrieve several
items of an array or a list at a time. The same slice syntax
can also be used on the left side of an assignment to modify
some elements of an array:
\index{slice!assignment}

\begin{verbatim}
my @digits = <1 2 3 6 5 4 7 8 9>
@digits[2..4] = 4, 5, 6
say @digits;   # -> [1 2 4 5 6 4 7 8 9]
\end{verbatim}

Of course, you can't do that with lists, since, as you
remember, they are immutable.

The {\tt splice} function may be regarded as the Swiss Army
knife of arrays. It can add, remove and return one or
several items to or from an array. The general syntax is
as follows:

\begin{verbatim}
my @out_array = splice @array, $start, $num_elems, @replacement;
\end{verbatim}
%
The arguments for {\tt splice} are the input array, the index
of the first element on which to make changes, the number of
elements to be affected by the operation, and a list of
replacements for the elements to be removed. For example,
to perform the slice assignment shown just above, it is
possible to do this:

\begin{verbatim}
my @digits = <1 2 3 6 5 4 7 8 9>
my @removed_digits = splice @digits, 3, 3, 4, 5, 6;
say @removed_digits;     # -> [6 5 4]
say @digits;             # -> [1 2 4 5 6 7 8 9]
\end{verbatim}
%
Here, the {\tt splice} statement removed 3 elements (6, 5, 4)
and replaced them with the replacement arguments (4, 5, 6).
And it returned the removed items into \verb'@removed_digits'.
The number of replacements needs not be the same as the number
of removed items, in which case the array size will grow or
shrink. For example, if no replacement is provided, then
{\tt splice} will just remove and return the required number
of elements and the array size will be reduced by the same number:

\begin{verbatim}
my @digits = 1..9;
my @removed_digits = splice @digits, 3, 2;
say @removed_digits;     # -> [4 5]
say @digits;             # -> [1 2 3 6 7 8 9]
\end{verbatim}
%

Conversely, if the number of elements to be removed is zero,
no element will be removed, an empty array will be returned,
and the elements in the replacement list will be added in
the right place:

\begin{verbatim}
my @digits = <1 2 3 6 4 7 8 9>;
my @removed_digits = splice @digits, 3, 0, 42;
say @removed_digits;     # -> []
say @digits;             # -> [1 2 3 42 6 4 7 8 9]
\end{verbatim}
%

Assuming the {\tt shift} function did not exist in Perl,
you could write a {\tt my-shift} subroutine to simulate it:

\begin{verbatim}
sub my-shift (@array) {
    my @result = splice @array, 0, 1;
    return @result[0];
}
my @letters = 'a'..'j';
my $letter = my-shift @letters;
say $letter;             # -> a
say @letters;            # -> [b c d e f g h i j]
\end{verbatim}

We might raise an exception if the array passed to
{\tt my-shift} is empty. This could be done by modifying
the subroutine as follows:

\begin{verbatim}
sub my-shift (@array) {
    die "Cannot my-shift from an empty array" unless @array;
    my @result = splice @array, 0, 1;
    return @result[0];
}
\end{verbatim}
%

or by adding a non-empty constraint on the array in the
subroutine signature:
\index{signature}
\index{subroutine signature}

\begin{verbatim}
sub my-shift (@array where @array > 0) {
    my @result = splice @array, 0, 1;
    return @result[0];
}
\end{verbatim}
%

The \verb'@array > 0' expression evaluates to {\tt True} if
the number of elements of the array is more than 0, i.e. if the
array is not empty. It is equivalent to \verb'@array.elems > 0'.

\label{splice_exercise}
As an exercise, write subroutines to simulate the {\tt pop},
{\tt unshift}, {\tt push} and {\tt delete} built-ins. Solution: \ref{sol_splice_exercise}.

\section{Traversing a list}
\index{list!traversal}
\index{traversal!list}
\index{for loop}
\index{loop!for}
\index{statement!for}

The most common way to traverse the elements of a list or an
array is with a {\tt for} loop.  The syntax for an array is
the same as what we have already seen in earlier chapters
for lists:

\begin{verbatim}
my @colors = <red orange yellow green blue indigo violet>;
for @colors -> $color {
    say $color;
}
\end{verbatim}
%
This works well if you only need to read the elements of the
list.  But if you want to write or update the elements of an array, you
need a doubly-pointed block. For example, you might use the
{\tt tc} (title case) function to capitalize the first letter
of each word of the array:
\index{tc function}

\begin{verbatim}
my @colors = <red orange yellow green blue indigo violet>;
for @colors <-> $color {$color = tc $color};
say @colors;   # -> [Red Orange Yellow Green Blue Indigo Violet]
\end{verbatim}
%
Here the \verb'$color' loop variable is a read-and-write alias
on the array's items, so that changes made to this alias will
be reflected in the array. This works well with arrays, but
would not work with lists, which are immutable. You would
get an error with a list:

\begin{verbatim}
> for <red orange yellow> <-> $color { $color = tc $color}
Parameter '$color' expected a writable container, but got Str value...
\end{verbatim}

You may also use the syntax of a {\tt for} loop with the
\verb'$_' topical variable. For example, this uses the
{\tt uc} (upper case) function to capitalize each word of
the previous array:
\index{topical variable}
\index{uc function or method}

\begin{verbatim}
for @colors {
    $_ = $_.uc
}
say @colors; # -> [RED ORANGE YELLOW GREEN BLUE INDIGO VIOLET]
\end{verbatim}
%

Sometimes, you want to traverse an array and need to know the
index of the elements you are visiting. A common way to do
that is to use the \verb'..' range operator to iterate on
the indices. For instance, to print the index and the value of each element of an array:

\begin{verbatim}
for 0..@colors.end -> $idx {
    say "$idx  @colors[$idx]";
}
\end{verbatim}

This is useful, for example, for traversing two (or more) arrays
in parallel:

\begin{verbatim}
my @letters = 'a'..'e';
my @numbers = 1..5;
for 0..@letters.end -> $idx {
    say "@letters[$idx] -> @numbers[$idx]";
}
\end{verbatim}
%

which will print:
\begin{verbatim}
a -> 1
b -> 2
c -> 3
d -> 4
e -> 5
\end{verbatim}

You don't really need to specify the index range yourself, as
the {\tt keys} function will return a list of indices for
the array or the list:
\index{keys function or method}

\begin{verbatim}
for keys @colors -> $idx {
    say "$idx  @colors[$idx]";
}
\end{verbatim}

Another way to iterate over the indices and values of an
array is the {\tt kv} (``keys values'') function or method,
which returns the index and value of each array item:
\index{kv function or method}

\begin{verbatim}
for @letters.kv -> $idx, $val {
    say "$idx $val";
}
\end{verbatim}

In list context, the \verb'@letters.kv' simply returns an
interleaved sequence of indexes and values:

\begin{verbatim}
my @letters = 'a'..'e';
say @letters.kv;    # -> (0 a 1 b 2 c 3 d 4 e)
\end{verbatim}

It is the pointy block with two iteration variables
which makes it possible to process both an index and a value at each step of the loop. You can of course have more than two iteration variables if needed.

\section{New looping constructs}
\index{loop}

Since the subject of this chapter is arrays and lists,
it is probably the right time to briefly study two
looping constructs that I had left aside so far.

The first one uses the same {\tt for} keyword as above,
but with a different syntax for the iteration variable(s).
\index{for loop}

\begin{verbatim}
my @letters = 'a'..'e';
for @letters {
    say $^a-letter;
}
\end{verbatim}

\index{placeholder}
\index{placeholder!parameter}
\index{twigil}
\index{sigil}
\index{self-declared parameter}
The \verb'^' in the \verb'$^a-letter' variable is called
a \emph{twigil}, i.e. sort of a secondary sigil. When there is
a twigil, the first symbol (here, the \verb'$' sign) has the
same meaning as usual sigils (here, it denotes a scalar variable),
and the second one (here, \verb'^') extends the variable
description and usually modifies its scope. In this specific
case, the second character states that the \verb'$^a-letter'
variable is a  \emph{placeholder parameter} or a
\emph{self-declared positional parameter}. This is a positional
parameter of the current block that needs not be declared in
the signature.
\index{signature}

If the block uses more than one placeholder, they are
associated to the input according to their lexicographic
(alphabetic) order:

\begin{verbatim}
my @letters = 'a'..'e';
for @letters.kv {
    say $^a ~ " -> " ~ $^b;
}
\end{verbatim}
%
which will print:
\begin{verbatim}
0 -> a
1 -> b
2 -> c
3 -> d
4 -> e
\end{verbatim}
%

As seen just above, the {\tt kv} function returns an
interleaved sequence of indexes and values. Since
\verb'$^a' comes before \verb'$^b' in the alphabetic
order, \verb'$^a' will be bound to the index and
\verb'$^b' with the value for each pair of the input.

Placeholders can also be used for subroutines:

\begin{verbatim}
> sub divide { $^first / $^second }
sub divide ($first, $second) { #`(Sub|230787048) ... }
> divide 6, 4
1.5
\end{verbatim}
%

These placeholders aren't used very often for
simply traversing arrays, but we will see later how
they are very useful in cases where is would be quite
unpractical to have to declare the parameters.
\index{placeholder}

\index{loop!keyword}
\index{loop!statement}
\index{C-style loop}
\label{C-style loop}
The second new looping construct I want to introduce
here uses the {\tt loop} keyword and is similar to
the C-style {\tt for} loop (i.e. the loop of the
C programming language). In this type of loop, you
declare between a pair of parentheses three expressions
separated by semi-colons: the iteration variable's
initial value, the condition on which the loop should
terminate and the change made to the iteration variable on
each iteration:

\begin{verbatim}
loop (my $i = 0; $i < 5; $i++) {
    say $i, " -> " ~ @letters[$i];
}
\end{verbatim}
%
For most common loops, the {\tt for} loops seen earlier
are easier to write and usually more efficient than this
construct. This special {\tt loop} construct should probably
be used only when the exit condition or the change made to
the iteration variable is quite unusual and would
be difficult to express in a regular {\tt for} loop. As
an exception, the {\tt loop} construct with no
three-part specification is quite common and even
idiomatic for making an infinite loop:
\index{infinite loop}
\index{loop!infinite}
\index{idiomatic}

\begin{verbatim}
loop {
    # do something
    # last if ...
}
\end{verbatim}
%

\section{Map, filter and reduce}
\label{map_filter}

When traversing the elements of an array (or a list), we have
processed so far one item at a time with a loop. We will
now study ways to process all the elements in one go.

\subsection{Reducing a list to a value}

To add up all the numbers in a list, you can use a {\tt for}
loop like this:

\begin{verbatim}
sub add_all (@numbers) {
    my $total = 0;
    for @numbers -> $x {
        $total += $x;
    }
    return $total;
\end{verbatim}
%
{\tt \$total} is initialized to 0.  Each time through the loop,
{\tt \$x} gets one element from the list and is added to
{\tt \$total}. As the loop runs, {\tt total} accumulates the
sum of the elements; a variable used this way is sometimes
called an {\bf accumulator}.
\index{accumulator!sum}

An operation like this that combines a sequence of elements into
a single value is often called a reduction operation because
its effect is to {\bf reduce} all the items to one element (this
is also sometimes called ``folding'' in some other programming
languages). These ideas are derived from some functional
programming languages such as LISP (whose name stands for ``list
processing'').
\index{reduce pattern}
\index{pattern!reduce}
\index{traversal}

Perl~6 has a {\tt reduce} function, which generates a single
"combined" value from a list of values, by iteratively applying
to each item of a list a function which knows how to combine two values.
Using the {\tt reduce} function to compute the sum of the
first ten numbers might look like this:

\begin{verbatim}
> my $sum = reduce { $^a + $^b }, 1..10;
55
\end{verbatim}

Remember the \emph{factorial} function of Section~\ref{for_loops}?
It used a {\tt for} loop to compute the product of the \emph{n} first
integers up to a limit. It could be rewritten as follows using the
{\tt reduce} function:
\index{factorial}
\index{factorial!using the reduce function}

\begin{verbatim}
sub factorial (Int $num) {
    return reduce { $^a * $^b }, 1..$num;
}
say factorial 10;   # -> 3628800
\end{verbatim}
%
In fact, the code to compute the factorial is so short with
the {\tt reduce} function that it may be argued that it has
become unnecessary to write a subroutine for that. You could
just ``inline'' the code:

\begin{verbatim}
my $fact10 = reduce { $^a * $^b }, 1..10;     # -> 3628800
\end{verbatim}
%

We can do many more powerful things with that, but we'll come
back to that later, as it requires a few syntactic features that
we haven't seen yet.

\subsection{The reduction metaoperator}

Perl~6 also has a reduction operator,
or rather a reduction \emph{metaoperator}. An operator
usually works on variables or values; a metaoperator acts
on other operators. Given a list and an operator, the
\verb'[...]' meta-operator iteratively applies the operator
to all the values of the list to produce a single value.
\index{reduction operator}
\index{metaoperator}

For example, the following also prints the sum of all the
elements of a list:

\begin{verbatim}
say [+] 1, 2, 3, 4;           # ->  10
\end{verbatim}

This basically takes the first two values, adds them up,
and adds the result to the next value, and so on. Actually,
there is a form of this operator, with a backslash before
the operator, which also returns the intermediate results:

\begin{verbatim}
say [\+] 1, 2, 3, 4;          # -> (1 3 6 10)
\end{verbatim}

This meta-operator can be used to transform basically any
associative infix operator into a list operator returning
a single value.

The factorial function can now be rewritten as:
\index{factorial}
\index{factorial!using the reduction meta-operator}

\begin{verbatim}
sub fact(Int $x){
    [*] 1..$x;
}
my $factorial = fact(10);     # -> 3628800
\end{verbatim}

The reduction metaoperator can also be used with relational
operators to check whether the elements of an array or a list
are in the correct numerical or alphabetical order:

\begin{verbatim}
say [<] 3, 5, 7;              # -> True
say [<] 3, 5, 7, 6;           # -> False
say [lt] <a c d f r t y>;     # -> True
\end{verbatim}

\subsection{Mapping a list to another list}
\index{map}

Sometimes you want to traverse one list while building
another.  For example, the following function takes a list
of strings and returns a new list that contains capitalized
strings:

\begin{verbatim}
sub capitalize_all(@words):
    my @result;
    push @result, $_.uc for @words;
    return @result;
}
my @lc_words = <one two three>;
my @all_caps = capitalize_all(@lc_words); # -> [ONE TWO THREE]
\end{verbatim}
%
\verb'@result' is declared as an empty array; each time through
the loop, we add the next element.  So \verb'@result' is
another kind of accumulator.
\index{accumulator!list}

An operation like \verb"capitalize_all" is sometimes called a {\bf map} because it ``maps'' a function (in this case the {\tt uc} method) onto each of the elements in a sequence.
\index{map pattern}
\index{pattern!map}
\index{filter pattern}
\index{pattern!filter}

Perl has a {\tt map} function which makes it possible to
do that in just one statement:

\begin{verbatim}
my @lc_words = <one two three>;
my @all_caps = map { .uc }, @lc_words;      # -> [ONE TWO THREE]
\end{verbatim}
%

Here, the {\tt map} function applies the {\tt uc} method to
each item of the \verb'@lc_words' array and returns them
into the \verb'@all_caps' array. More precisely, the {\tt map}
function iteratively assigns each item of the \verb'@lc_words'
array to the \verb'$_' topical variable, applies the
code block following the {\tt map} keyword to \verb'$_' in
order to create new values and returns a list of these new
values.
\index{map function}
\index{topical variable}
\index{map}

To generate a list of even numbers between 1 and 10, we
might use the range operator to generate numbers
between 1 and 5 and use {\tt map} to multiply them by two:

\begin{verbatim}
my @evens = map { $_ * 2 }, 1..5;  # -> [2 4 6 8 10]
\end{verbatim}
%

Instead of using the \verb'$_' topical variable, we might
also use a pointy block syntax with an explicit iteration
variable:

\begin{verbatim}
my @evens = map -> $num { $num * 2 }, 1..5;  # -> [2 4 6 8 10]
\end{verbatim}
%

or an anonymous block with a placeholder variable:

\begin{verbatim}
my @evens = map { $^num * 2 }, 1..5;  # -> [2 4 6 8 10]
\end{verbatim}
%

Instead of a code block, the first argument to {\tt map} can
be a code reference (a subroutine reference):

\begin{verbatim}
sub double-sq-root-plus-one (Numeric $x) {
    1 + 2 * sqrt $x;
}
my @results = map &double-sq-root-plus-one, 4, 16, 42;
say @results;     # -> [5 9 13.9614813968157]
\end{verbatim}
%
\index{map}

The subroutine name needs to be prefixed with the ampersand
sigil to make clear that it is a parameter to {\tt map} and
not a direct call of the subroutine.
\index{sigil}
\index{ampersand sigil}

If the name of the array on the left side and on the right
side of the assignment is the same, then the modification
seems to be made ``in place'', i.e. it appears as if the
original array is modified in the process.

This is an immensely
powerful and expressive function, we will come back to it
later.

\subsection{Filtering the elements of a list}

Another common list operation is to select some elements from
a list and return a sublist.  For example, the following
function takes a list of strings and returns a list that
contains only the strings containing a vowel:

\begin{verbatim}
sub contains-vowel(Str $string) {
    return True if $string ~~ /<[aeiouy]>/;
}
sub filter_words_with_vowels (@strings) {
    my @kept-string;
    for @string -> $st {
        push @kept-string, $st if contains-vowel $st;
    }
    return @kept-string;
}
\end{verbatim}
%

{\tt contains-vowel} is a subroutine that returns
{\tt True} if the string contains at least one vowel
(we consider ``y'' to be a vowel for our purpose).

The \verb"filter_words_with_vowels" subroutine will return
a list of strings containing at least one vowel.

An operation like \verb"filter_words_with_vowels" is called
a {\bf filter} because it selects some of the elements and
filters out the others.
\index{filter}

Perl has a function called {\tt grep} to do that in just
one statement:
\index{grep}

\begin{verbatim}
my @filtered = grep { /<[aeiouy]>/ }, @input;
\end{verbatim}
%

The name of the {\tt grep} built-in function used to
filter some input comes from the Unix world, where it
is a utility that filters from an input file the lines that
match a given pattern.

In the code example above, all of \verb'@input' strings
will be tested against the
{\tt grep} block, and those matching the regex will go into the
{\tt \@filtered} array. Just like {\tt map}, the {\tt grep}
function iteratively assigns each item of the \verb"@input"
array to the \verb'$_' topical variable, applies the
code block following the {\tt grep} keyword to \verb'$_'
returns a list of the values for which the code block
evaluates to true. Here, the code block is a simple regex
applied to the \verb'$_' variable.

Just as for {\tt map}, we could have used a function
reference as the first argument to  {\tt grep}:

\begin{verbatim}
my @filtered = grep &contains-vowel, @input;
\end{verbatim}
%

To generate a list of even numbers between 1 and 10, we might
use the range operator to generate numbers between 1 and 10
and use {\tt grep} to filter out odd numbers:

\begin{verbatim}
my @evens = grep { $_ %% 2 }, 1..10;  # -> [2 4 6 8 10]
\end{verbatim}
%

\label{exercise_squares}
As an exercise, write a program using {\tt map} to
produce an array containing the square of the numbers
of the input list and a program using {\tt grep} to keep
only the numbers of an input list that are perfect squares. Solution: \ref{sol_exercise_squares}.

Most common list operations can be expressed as a combination
of {\tt map}, {\tt grep} and {\tt reduce}.
\index{map}
\index{grep}
\index{reduce}

\subsection{Higher order functions and functional programming}
\label{array_functional_programming}
\index{higher-order function}
\index{functional programming}

Besides their immediate usefulness, the {\tt reduce}, {\tt map}
and {\tt grep} functions we have been using here do something
qualitatively new. The arguments to these functions are not
just data: their first argument is a code block or a function.
We are not only passing to them the data that they will have
to use or transform, we are also passing to them the code
that will process the data.

\index{reduce function}
\index{map function}
\index{grep function}

The {\tt reduce}, {\tt map} and {\tt grep} functions are
what is often called higher order functions, functions that
manipulate not only data, but also other functions. These
functions can be thought of as generic abstract functions---
they perform a purely technical operation: process the
elements of a list and apply to each of them a behavior
defined in the code block or the function of the first
parameter.

These ideas are to a large extent rooted in functional
programming, a programming paradigm which is very different
from what we had seen so far and which has been implemented
historically in languages such as Lisp, Caml, Ocaml, Scheme,
Erlang or Haskell. Perl~6 is not a functional
programming language in the same sense as these languages,
because it can also use other programming paradigms,
but it has incorporated most of their useful features, so
that you can use the expressive power and inherent safety
of this programming model, without being forced to do so
if and when you would prefer a different model, and
without having to learn a totally new syntax that may
sometimes look somewhat abstruse or even clunky.

This is immensely useful and can give you an incredible
expressive power for solving certain types of problems. But
other types of problems might be better solved with the more ``traditional'' procedural or imperative programming model,
while others may benefit of an object-oriented approach. Perl~6
lets you choose the programming model you want to use, and even
makes it possible to combine seamlessly several of them in the
same program.

Functional programming is so important in my opinion that a full chapter
of this book will be devoted to the functional programming
features of Perl (see Chapter~\ref{functional programming}).
Before that, make sure to read the Subsection~\ref{functional_queue}
in the array and list section of the exercise solution chapter.

\section{Fixed-size, typed and shaped arrays}
\index{shaped array}
\index{fixed-size array}
\index{typed array}

By default, arrays can contain items of any type, including
items of different types, and can auto-extend as you need.
Perl will take care of the underlying gory details for you,
so that you don't have to worry about them. This is very
practical but this also comes with a cost: some array
operations might be unexpectedly slow, because Perl may
have to perform quite a bit of house-cleaning behind the
scene, such as memory allocation or reallocation, copying
a full array within memory, etc.

In some cases, however, it is possible to know beforehand
the size of an array and the data type of its items. If
Perl knows about these, it might be able to be faster and
to use much less memory. It might also helps you
to prevent subtle bugs.

To declare the type of the elements of an array, just
specify it when declaring the array. For example, to
declare an array of integers:

\begin{verbatim}
> my Int @numbers = 1..20;
[1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20]
> @numbers[7] = 3.5;     # ERROR
Type check failed in assignment to @numbers; expected Int but got Rat
  in block <unit> at <unknown file> line 1
\end{verbatim}
%

Similarly, you can declare the size of an array. Such arrays
are sometimes called \emph{shaped arrays}. There are
twelve months in a year, so you might tell Perl that your
\verb'@months' array will never contain more that twelve
items:
\index{shaped array}
\begin{verbatim}
> my @months[12] = 1..7;
[1 2 3 4 5 6 7 (Any) (Any) (Any) (Any) (Any)]
> say @months.elems
12
> say @months[3];
4
> say @months[12];
Index 12 for dimension 1 out of range (must be 0..11)
\end{verbatim}
%

Here, Perl has allocated 12 ``slots'' to the array, even though
the last five are currently undefined. Perl may not need
to reallocate memory when you define the tenth item of
the array. And Perl tells you about your mistake if you
accidentally try to access an out-of-range item.
\index{out-of-range error}

Defining both the type of the elements and the maximal size
of the array may lead to a noticeable performance gain
in terms of execution speed (at least for some operations)
and reduce significantly the memory usage of the program,
especially when handling large arrays.

\section{Multidimensional arrays}
\label{multidimensional array}
\index{multidimensional array}
\index{array!multidimensional}
\label{multidimensional_array}

The arrays we have seen so far are one-dimensional. In some
languages, such arrays are called vectors. But arrays can
also be multidimensional (you may then call them matrices).

For example, you might use a two-dimensional array to
store a list of employees with their respective salary:

\begin{verbatim}
> my @employees;
[]
> @employees[0;0] = "Liz";
Liz
> @employees[0;1] = 3000;
3000
> @employees[1] = ["Bob"; 2500];
[Bob 2500]
> @employees[2] = ["Jack"; 2000];
[Jack 2000]
> @employees[3] = ["Betty"; 1800];
[Betty 1800]
> say @employees[1;1];
2500
> say @employees[2];
[Jack 2000]
> say @employees;
[[Liz 3000] [Bob 2500] [Jack 2000] [Betty 1800]]
\end{verbatim}

It is possible to have more than two dimensions. For example,
we may have a \verb'@pixels' array in which the first two
dimensions are the ``x'' and ``y'' coordinates of a dot in
a picture and the third dimension the RGB colors:

\begin{verbatim}
> my @pixels;
[]
> @pixels[0; 0] = [ <0 78 255> ];
[0 78 255]
> @pixels[1; 0] = [ <7 74 246> ];
[7 74 246]
> @pixels[0; 1] = [ 9, 55, 232 ];
[9 55 232]
> say @pixels[0;1];
[9 55 232]
> say @pixels[0;1;1]
55
> say @pixels;
[[[0 78 255] [9 55 232]] [[7 74 246]]]
\end{verbatim}

Multidimensional arrays can also have a fixed size. For
example, this may be a declaration for two-dimensional array
where the first dimension is the month in the year and
the second the day in the month:

\begin{verbatim}
my @date[12, 31];
\end{verbatim}

\section{Sorting arrays or lists}
\label{sorting}
\index{sorting!data}

Sorting data is a very common operation in computer
science. Perl has a {\tt sort} function that can sort
an array or a list and return the sorted result:
\index{sort}
\index{sort!function or method}
\index{function!sort}

\begin{verbatim}
say sort <4 6 2 9 1 5 11>;  # -> (1 2 4 5 6 9 11)
\end{verbatim}

There are several types of sorts. The most common are numeric
sort and lexicographic (or alphabetic) sort. They differ
in the way they compare individual items to be sorted.
\index{numeric sort}
\index{alphabetic sort}
\index{lexicographic sort}
\index{sort!numeric}
\index{sort!alphabetic}
\index{sort!lexicographic}

In alphabetic sort, you first compare the first letter of
the words to be compared; a word starting with an ``a''
will always come before a word starting with a ``b''
(or any other letter) in an ascending sort, irrespective
of the value or number of the other characters. You need to
compare the second character of two words only if
the first character of these words is the same.

Numeric sorting is very different: it is the overall
value of the number which is of interest. For example,
if we are sorting integers, 11 is larger than 9 because
it has more digits. But alphabetic sorting of 9 and 11
would consider 11 to be smaller than 9, because the
first digit is smaller.

So an alphabetic or lexicographic sort of the list of
integers above would return:

\begin{verbatim}
(1 11 2 4 5 6 9)
\end{verbatim}

The consequence is that, with many programming languages,
when you want to sort data, you need to specify which
type of sort you want. With consistent data (every item
of the same type), Perl~6 is usually clever enough to
find out which type of sort is best suited to your
needs. So, for example, this code this will also perform
the type of sort that you probably expect:

\begin{verbatim}
say sort <a ab abc ac bc cb ca>; # ->(a ab abc ac bc ca cb)
\end{verbatim}

Even with mixed data types, {\tt sort} can do a pretty good
job at providing a result that may very well be what
you are looking for:

\begin{verbatim}
say sort <1 11 5 4 12 a ab abc ac bc ca cb>;
         # -> (1 4 5 11 12 a ab abc ac bc ca cb)
\end{verbatim}

There are cases, however, where this simple use of the
{\tt sort} function will fail to return what you
probably want:

\begin{verbatim}
say sort <a ab abc A bc BAC AC>; # -> (A AC BAC a ab abc bc)
\end{verbatim}
%

Here, {\tt sort} puts all strings starting with an
upper-case letter before any string starting with a
lower case letter, probably not what you want. It
looks even worse if the strings use extended
ASCII characters:
\index{case!lower}
\index{case!upper}

\begin{verbatim}
say sort <a ab àb abc Ñ A bc BAC AC>;
        # -> (A AC BAC a ab abc bc Ñ àb)
\end{verbatim}
%

\index{sort!ASCIIbetical}
The reason is that, when sorting strings, {\tt sort}
uses the internal numeric encoding of letters. This
was sometimes called "ASCIIbetical" order (by contrast
with alphabetical order), but the term is now too limited
and somewhat obsolete, because in Perl~6 is using Unicode
rather than ASCII.

Clearly, these are cases where more advanced sorting
techniques are needed.

\section{More advanced sorting techniques}
\label{advanced_sort}
\index{sorting!advanced}

\index{sort}
\index{sort!code object}
\index{cmp operator}
\index{operator!cmp}
The {\tt sort} routine typically takes two arguments,
a code object and a list of items to be sorted, and returns
a new sorted list. If no code object is specified, as in the
examples we have seen above, the {\tt cmp} built-in comparison
operator is used to compare the elements. If
a code object is provided (and if it accepts two
arguments), then it is used to perform the comparison,
which tells {\tt sort} which of the two elements should
come first in the final order.

There are three built-in comparison operators that can be used
for sorting. They are sometimes called three-way comparators
because they compare their operands and return a value meaning
that the first operand should be considered less than, equal to
or more than the second operand for the purpose of determining
in which order these operands should be sorted. The {\tt leg}
operator coerces its arguments to strings and performs a
lexicographic comparison. The \verb'<=>' operator coerces
its arguments to numbers (Real) and does a numeric comparison.
The afore-mentioned {\tt cmp} operator is the ``smart''
three-way comparator, which compares strings with string
semantics and numbers with number semantics.
\index{coercion}

Most of our simple examples above worked well with
strings and numbers because they implicitly used the
default {\tt cmp} operator, which ``guesses'' quite
well which type of comparison to perform.

\index{three-way comparator}
\index{leg operator}
\index{cmp operator}
\index{operator!cmp}
\index{operator!leg}
% TODO: get these entries working in plastex
\ifplastex \else
\index{<=> operator@\texttt{<=>} operator}
\index{operator!<=> (numeric comparison)@\texttt{<=>} (numeric comparison)}
\fi

In other words, this:

\begin{verbatim}
say sort <4 6 2 9 1 5 11>;  # -> (1 2 4 5 6 9 11)
\end{verbatim}

is equivalent to this:

\begin{verbatim}
say sort { $^a cmp $^b }, <4 6 2 9 1 5 11>;
     # -> (1 2 4 5 6 9 11)
\end{verbatim}

\index{placeholder}
The code block used here as the first argument to the
{\tt sort} routine uses again the placeholder
parameters (or self-declared parameters) seen earlier
in this chapter. The {\tt cmp} routine receives two
arguments which are bound to \verb'$^a' and \verb'$^b'
and returns to the sort function information about which
of the two items should come first in the resulting order.
\index{cmp operator}
\index{operator!cmp}

\index{sort!reverse order}
If you wanted to sort in reverse order, you could just
swap the order of the two placeholder parameters:

\begin{verbatim}
say sort { $^b cmp $^a }, <4 6 2 9 1 5 11>;
     # -> (11 9 6 5 4 2 1)
\end{verbatim}

Note that this example is given only for the purpose of
explaining some features of the placeholder parameters.
To sort the array we've presented here in descending order,
it might just be easier to obtain the same result with the
following code:

\begin{verbatim}
say reverse sort <4 6 2 9 1 5 11>;  # -> (11 9 6 5 4 2 1)
\end{verbatim}
\index{reverse}

The reason {\tt sort} does a good job even with mixed
strings and integers is because the default comparison
function, {\tt cmp}, is pretty clever and guesses by
looking at its arguments whether it should perform
a lexicographic order or numeric order comparison.

If sorting gets too complicated for {\tt cmp}, or, more
generally, when a specific or custom order is required,
then you have to write your own ad-hoc comparison
subroutine.
\index{cmp operator}
\index{operator!cmp}

For example, if we take again the example of strings
with mixed case letters, we may achieve a case-insensitive
alphabetical order this way:
\index{sort!case insensitive}

\begin{verbatim}
say sort { $^a.lc cmp $^b.lc}, <a ab abc A bc BAC AC>;
     # -> (a A ab abc AC BAC bc)
\end{verbatim}

or this way:
\begin{verbatim}
say sort { $^a.lc leg $^b.lc}, <a ab abc A bc BAC AC>;
     # -> (a A ab abc AC BAC bc)
\end{verbatim}

\index{lc function or method}
\index{function!lc}
\index{method!lc}
\index{lower case!lc function}
Here, when the comparison code block receives its two
arguments, the {\tt lc} method casts them to lower-case
before performing the comparison. Notice that this has
no impact on the case of the output, since the lower-case
transformation is local to the comparison code block and
has no impact on the data handled by {\tt sort}. We will
see shortly that there is a simpler and more efficient
way of doing such a transformation before comparing the
arguments.

If the comparison specification is more complicated, we
may need to write it in a separated subroutine and let
{\tt sort} call that subroutine. Suppose we have a list
of strings which are all formed of leading digits
followed by a group of letters and possibly followed by other
irrelevant characters, and that we want to sort the
strings according to the group of letters that follows
the digits.

Let's start by writing the comparison subroutine:
\index{comparison subroutine}
\index{sort!comparison subroutine}

\begin{verbatim}
sub my_comp ($str1, $str2) {
    my $cmp1 = $0 if $str1 ~~ /\d+(\w+)/;
    my $cmp2 = $0 if $str2 ~~ /\d+(\w+)/;
    return $cmp1 cmp $cmp2;
}
\end{verbatim}

Nothing complicated: it takes two arguments, uses a regex
for extracting the group of letters in each of the
arguments, and returns the result of the {\tt cmp}
function on the extracted strings. In the real world, something
might need to be done if either of the extractions fails, but
we will assume for our purpose here that this will not happen.
\index{regex}
\index{cmp operator}

The sorting is now quite straight forward, we just need to pass the above subroutine to the {\tt sort} function:

\begin{verbatim}
say sort &my_comp, < 22ac 34bd 56aa3 12c; 4abc( 1ca 45bc >;
     # -> (56aa3 4abc( 22ac 45bc 34bd 12c; 1ca)
\end{verbatim}

We only need to prefix the comparison subroutine with the
``\&'' ampersand sigil and it works fine: the strings are sorted
in accordance to the letter groups that follow the leading digits.
\index{sigil}
\index{ampersand sigil}

In all the examples above, the comparison subroutine
accepted two parameters, the two items to be compared.
The {\tt sort} function may also work with a code object
taking only one parameter. In that case, the code object
is not a comparison code block or subroutine, but is a
code object implementing the transformation to be
applied to the items before using the default {\tt cmp}
comparison routine.
\index{sort!transformation subroutine}
\index{cmp operator}
\index{operator!cmp}

For example, if we take once more the example of strings
with mixed case letters, we may achieve a case-insensitive
alphabetical order yet in a new way:
\index{sort!case insensitive}

\begin{verbatim}
say sort { $_.lc }, <a ab abc A bc BAC AC>;
     # -> (a A ab abc AC BAC bc)
\end{verbatim}

This could also be written with a placeholder parameter:
\index{placeholder}

\begin{verbatim}
say sort { $^a.lc }, <a ab abc A bc BAC AC>;
     # -> (a A ab abc AC BAC bc)
\end{verbatim}

Here, since the comparison code block takes only one
argument, it is meant to transform each of the items
to be compared before performing the standard {\tt cmp} routine on
the arguments. This does not only make things simpler,
but this is also probably more efficient, especially if
the number of items to be sorted is large and if the
transformation subroutine is relatively costly: the
transformed values are actually \emph{cached} (i.e.
stored in memory for repeated use), so that the
transformation is done only once for each item, despite
the fact that the comparison routine is called many times
for each item in a sort.
\index{cache}

Similarly, we could sort numbers according to their
absolute values:
\index{abs function or method}
\index{function!abs}
\index{method!abs}

\begin{verbatim}
say sort {$_.abs}, <4 -2 5 3 -12 42 8 -7>; # -> (-2 3 4 5 -7 8 -12 42)
\end{verbatim}

If you think about it, the ``more complicated'' example
with digits and letters requiring a separate subroutine
is also applying the same transformation to both its
arguments. As an exercise, write a (simpler) sorting
program using a transformation subroutine and the default
{\tt cmp} operator on transformed items. Solution: \ref{sol_sort_exercise}.
\label{sort_exercise}
\index{cmp operator}
\index{sort}

Needless to say, the (so-called) advanced uses of the
{\tt sort} function presented in this section are yet
more examples of the functional programming style. The
comparison subroutines and the transformation subroutines
are passed around as arguments to the {\tt sort}
function, and, more broadly, all of the functions,
subroutines and code blocks used here are higher-order
functions or first-class functions.
\index{functional programming}

\section{Debugging}
\index{debugging}

Careless use of arrays (and other mutable objects)
can lead to long hours of debugging.  Here are some common
pitfalls and ways to avoid them:

\begin{enumerate}

\item Some array built-in functions and methods modify
their argument(s) and others don't.

It may be tempting to write code like this:

\begin{verbatim}
@array = splice @array, 1, 2, $new_item;   # WRONG!
\end{verbatim}
\index{splice function}

The {\tt splice} function returns the elements it has
deleted from the array, not the array itself, which
is modified ``in place''.

Before using array methods and operators, you should
read the documentation carefully and perhaps test them
in interactive mode.

When traversing an array, for example with {\tt for}
or {\tt map}, the \verb'$_' topical variable is an
\emph{alias} for the successive items of the array, and
not a copy of them. This means that if you change
\verb'$_', the change will be reflected in the array.
There may be some cases where this is what you want,
and others where you don't care (if you no longer need the
original array), but this technique is error-prone and
should perhaps be avoided (or at least used only with
great care).

\begin{verbatim}
my @numbers = <1 2 3>;
push @doubles, $_*=2 for @numbers;  # WRONG (probably)
say @numbers; # -> [2 4 6]
\end{verbatim}

The error here is that the \verb'$_*=2' statement is
modifying \verb'$_', so that the \verb'@numbers' array is
also modified, whereas the intent was certainly to
populate the new numbers into \verb'@doubles', not
to modify \verb'@numbers'.

The same code applied to a literal list instead of an
array leads to a run time error because a list is
immutable:

\begin{verbatim}
> push @doubles, $_*=2 for <1 2 3>; # WRONG (definitely)
Cannot assign to an immutable value
\end{verbatim}

The fix is quite easy in this case and consists in
using an expression which does not modify \verb'$_'
but returns the new desired value:

\begin{verbatim}
push @doubles, $_ * 2 for @numbers; # OK
\end{verbatim}

The same goes for {\tt map}:

\begin{verbatim}
my @numbers = <1 2 3>;
say map { ++$_}, @numbers;          # WRONG (probably)
say @numbers; # -> [2 3 4]
\end{verbatim}
%

Here again, using an expression that does not modify \verb'$_'
but instead returns the new desired value will fix the problem:

\begin{verbatim}
my @numbers = <1 2 3>;
say map { $_ + 1}, @numbers;        # -> (2 3 4)
say @numbers; # -> [1 2 3]
\end{verbatim}
%

\end{enumerate}

\section{Glossary}

\begin{description}

\item[list:] An immutable sequence of values.
\index{list}

\item[array:] A variable containing a mutable sequence
of values.
\index{list}

\item[element:] One of the values in a list or an
array (or some other sequence), also called items.
\index{element}
\index{item}

\item[nested array:] An array that is an element of another array.
\index{nested list}

\item[accumulator:] A variable used in a loop to add up or
accumulate a result.
\index{accumulator}

\item[augmented assignment:] A statement that updates the value
of a variable using an operator like \verb"+=".
\index{assignment!augmented}
\index{augmented assignment}
\index{traversal}

\item[reduce:] A processing pattern that traverses a sequence
and accumulates the elements into a single result.
\index{reduce pattern}
\index{pattern!reduce}

\item[map:] A processing pattern that traverses a
sequence and performs an operation on each element.
Also the name of a Perl built-in function that performs
such a processing pattern.
\index{map pattern}
\index{pattern!map}

\item[filter:] A processing pattern that traverses a
list and selects the elements that satisfy some criterion.
{\tt grep} is a Perl implementation of a filter.
\index{filter pattern}
\index{pattern!filter}

\item[alias:] A circumstance where an identifier refers
directly some variable or value, so that
a change to it would lead to a change of
the variable or value. It essentially means having
two names for the same value, container or object.
\index{alias}

\end{description}

\section{Exercises}
\label{array_exercises}

\begin{exercise}

Write a subroutine called \verb"nested-sum" that takes an
array of arrays of integers and adds up the elements from all of the nested arrays. For example:
\label{nested_sum}

\begin{verbatim}[fontshape=up]
my @AoA = [[1, 2], [3], [4, 5, 6]];
say nested-sum(@AoA);        # -> 21
\end{verbatim}

Solution: \ref{sol_nested_sum}.

\end{exercise}

\begin{exercise}
\label{cumulative}
\index{cumulative sum}

Write a subroutine called {\tt cumul-sum} that takes a list of numbers
and returns the cumulative sum; that is, a new list where the
$i$th element is the sum of the first $i+1$ elements from
the original list. For example:
\label{cumsum}

\begin{verbatim}[fontshape=up]
my @nums = [1, 2, 3, 4];
say cumul-sum(@nums);           # -> [1, 3, 6, 10]
\end{verbatim}

Solution: \ref{sol_cumsum}.

\end{exercise}

\begin{exercise}

Write a subroutine called \verb"middle" that takes a list and
returns a new list that contains all but the first and last
elements.  For example:
\label{middle}

\begin{verbatim}[fontshape=up]
say middle(1, 2, 3, 4);      # -> (2, 3)
\end{verbatim}

Solution: \ref{sol_middle}.

\end{exercise}

\begin{exercise}

Write a subroutine called \verb"chop-it" that takes
an array, modifies it by removing the first and last
elements, and returns nothing useful. For example:
\label{chop}

\begin{verbatim}[fontshape=up]
my @nums = 1, 2, 3, 4;
chop-it(@nums);
say @nums;                   # -> [2, 3]
\end{verbatim}

Solution: \ref{sol_chop}.

\end{exercise}

\begin{exercise}
Write a subroutine called \verb"is-sorted" that takes
a list (or array) of numbers as a parameter and returns
{\tt True} if the list is sorted in ascending order and
{\tt False} otherwise.  For example:
\label{is_sorted}
\index{is-sorted}

\begin{verbatim}[fontshape=up]
> is-sorted (1, 2, 2);
True
> is-sorted (1, 2, 1);
False
\end{verbatim}

Solution: \ref{sol_is_sorted}.

\end{exercise}

\begin{exercise}

\label{is_anagram}
\index{anagram}
\index{is-anagram}
Two words are anagrams if you can rearrange the letters
from one to spell the other.  Write a subroutine called
\verb"is-anagram" that takes two strings and returns
{\tt True} if they are anagrams.

Solution: \ref{sol_is_anagram}.

\end{exercise}

\begin{exercise}
\label{has_duplicates}
\index{duplicate}
\index{has-duplicates}
\index{uniqueness}

Write a subroutine called \verb"has-duplicates" that takes
a list or an array and returns {\tt True} if there is
any element that appears more than once.  It should
not modify the original input.

Solution: \ref{sol_has_duplicates}.

\end{exercise}

\begin{exercise}

This exercise pertains to the so-called Birthday Paradox,
which you can read about at
\url{http://en.wikipedia.org/wiki/Birthday_paradox}.
\index{birthday paradox}
\label{birthdays}

If there are 23 students in your class, what are the
chances that two of you have the same birthday?  You
can estimate this probability by generating random
samples of 23 birthdays and checking for duplicates.
Hint: you can generate random birthdays
with the {\tt rand} and the {\tt int} functions.
\index{rand function}
\index{function!rand}

Solution: \ref{sol_birthdays}.

\end{exercise}

\begin{exercise}

\label{push_unshift}
Write a subroutine that reads the file {\tt words.txt} and builds
a list with one element per word.  Write two versions of
this function, one using the {\tt push} method and the
other using the idiom {\tt unshift}.  Which one takes
longer to run?  Why?
\index{push function}
\index{unshift function}

Solution: \ref{sol_push_unshift}.

\end{exercise}

\begin{exercise}
\label{bisection}
\index{membership!bisection search}
\index{bisection search}
\index{search!bisection}
\index{membership!binary search}
\index{binary search}
\index{search!binary}
\index{half-interval search}

To check whether a word is in our standard word list,
you could check each element in turn, but it would be
slow because it searches through the words in order.

If the words are in alphabetical order (which is the
case of our word list), we can speed
things up considerably with a \emph{bisection search} (also
known as binary search), which is similar to what you
do when you look a word up in the dictionary.  You
start somewhere in the middle and check to see whether
the word you are looking for comes before the word in
the middle of the list.  If so, you search the first
half of the list the same way.  Otherwise, you search
the second half.

Either way, you cut the remaining search space in half.
If the word list has 113,809 words, it will take at
most about 17 steps to find the word or conclude that
it's not there.

Write a function called \verb"bisect" that takes a
sorted list and a target value and returns information
about whether the target value is in the list or not.
\index{bisect}

Solution: \ref{sol_bisection}

\end{exercise}

\begin{exercise}
\index{reverse word pair}
\label{reverse_pair}

Two words are a ``reverse pair'' if each is the reverse
of the other.  For example, ``depot'' and ``toped'' form
a reverse pair; other examples include ``reward'' and
``drawer'', or ``desserts'' and ``stressed''. Write a
program that finds all the reverse pairs in the {\tt word.txt}
file.

Solution: \ref{sol_reverse_pair}.

\end{exercise}

\begin{exercise}
\index{interlocking words}
\label{interlock}

Two words ``interlock'' if taking alternating letters from
each forms a new word.  For example, ``shoe'' and ``cold''
interlock to form ``schooled''.

Write a program that finds in {\tt word.txt} all pairs of
words that interlock. Hint: don't enumerate all pairs, there
are many of them!

Solution: \ref{sol_interlock}

Credit: This exercise is inspired by an example at \url{http://puzzlers.org}.

\end{exercise}


%
% Cox_Ideals_notes.tex
%
\documentclass[twoside]{amsart}
\usepackage{amssymb,latexsym}
\usepackage{MnSymbol}
\usepackage{times}
\usepackage{graphics}
\usepackage{tikz}
\usepackage{hyperref}
\hypersetup{colorlinks=true, urlcolor=blue}
%\usepackage{simpsons}
%\usepackage{epsdice}
\usepackage{staves}

\usetikzlibrary{matrix,arrows}
%\usepackage{graphics}

\oddsidemargin-0.85cm
\evensidemargin-0.65cm
\topmargin-2.05cm     %I recommend adding these three lines to increase the
\textwidth19.05cm   %amount of usable space on the page (and save trees)
\textheight25.05cm
\parindent0.0em

%This next line (when uncommented) allow you to use encapsulated
%postscript files for figures in your document
%\usepackage{epsfig}

%plain makes sure that we have page numbers
\pagestyle{plain}

\theoremstyle{plain}
\newtheorem{theorem}{Theorem}
\newtheorem{axiom}{Axiom}
\newtheorem{lemma}{Lemma}
\newtheorem{proposition}{Proposition}
\newtheorem{corollary}{Corollary}

\theoremstyle{definition}
\newtheorem{definition}{Definition}

\title{Notes and Solutions to \emph{Ideals, Varieties, and Algorithms} by David A. Cox, John Little, Donal O'Shea  }

\author{
  Ernest Yeung - M\"{u}nchen
       }
\date{Marz 2014, jaro, primavera}

%This defines a new command \questionhead which takes one argument and
%prints out Question #. with some space.
\newcommand{\questionhead}[1]
  {\bigskip\bigskip
   \noindent{\small\bf Question #1.}
   \bigskip}

\newcommand{\problemhead}[1]
  {
   \noindent{\small\bf Problem #1.}
   }

\newcommand{\exercisehead}[1]
  { \smallskip
   \noindent{\small\bf Exercise #1.}
  }

\newcommand{\solutionhead}[1]
  {
   \noindent{\small\bf Solution #1.}
   }

%-----------------------------------
\begin{document}
%-----------------------------------

\maketitle

From the beginning of 2016, I decided to cease all explicit crowdfunding for any of my materials on physics, math.  I failed to raise \emph{any} funds from previous crowdfunding efforts.  I decided that if I was going to live in \emph{abundance}, I must lose a scarcity attitude.  I am committed to keeping all of my material \textbf{open-sourced}.  I give all my stuff \emph{for free}.

In the beginning of 2017, I received a very generous donation from a reader from Norway who found these notes useful, through \emph{PayPal}.  If you find these notes useful, feel free to donate directly and easily through \href{https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=ernestsaveschristmas%2bpaypal%40gmail%2ecom&lc=US&item_name=ernestyalumni&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted}{PayPal}, which won't go through a 3rd. party such as indiegogo, kickstarter, patreon.  Otherwise, under the \emph{open-source MIT license}, feel free to copy, edit, paste, make your own versions, share, use as you wish.

\noindent gmail        : ernestyalumni \\
linkedin     : ernestyalumni \\
tumblr       : ernestyalumni \\
twitter      : ernestyalumni \\
youtube      : ernestyalumni \\

David Cox, John Little, Donal O'Shea. \textbf{Ideals, Varieties, and Algorithms: An Introduction to Computational Algebraic Geometry and Commutative Algebra}, Third Edition, Springer

\section{Geometry, Algebra, and Algorithms}

\subsection{Polynomials and Affine Space}

fields are important is that linear algebra works over \emph{any} field

\begin{definition}[2] set of all polynomials in $x_1 , \dots , x_n$ with coefficients in $k$, denoted $k[x_1, \dots , x_n]$

\end{definition}

polynomial $f$ \emph{divides} polynomial $g$ provided $g= fh$ for some $h \in k[x_1, \dots , x_n ]$

$k[x_1, \dots, x_n]$ satisfies all field axioms except for existence of multiplicative inverses; commutative ring, $k[x_1, \dots , x_n]$ \emph{polynomial ring}

\subsubsection*{Exercises for 1 }

\exercisehead{1}
$\mathbb{F}_2$ commutative ring since it's an abelian group under addition, commutative in multiplication, and multiplicative identity exists, namely $1$.  It is a field since for $1\neq 0$, the multiplicative identity is $1$.

\exercisehead{2}
\begin{enumerate}
\item[(a)]
\item[(b)]
\item[(c)]
\end{enumerate}

\subsection{Affine Varieties }

\subsection{Parametrizations of Affine Varieties}

\subsection{Ideals}

\subsection{Polynomials of One Variable}

\section{Groebner Bases}

\subsection{Introduction}

\subsection{Orderings on the Monomials in $k[x_1, \dots , x_n]$ }

\subsection{A Division Algorithm in $k[x_1, \dots , x_n ]$ }

\subsection{Monomial Ideals and Dickson's Lemma }

\subsection{The Hilbert Basis Theorem and Groebner Bases}

\subsection{Properties of Groebner Bases}

\subsection{Buchberger's Algorithm}

\section{Elimination Theory}

\subsection{The Elimination and Extension Theorems}

\subsection{The Geometry of Elimination}

\section{The Algebra-Geometry Dictionary}

\subsection{Hilbert's Nullstellensatz}

\subsection{Radical Ideals and the Ideal-Variety Correspondence}

\section{Polynomial and Rational Functions on a Variety}

\subsection{Polynomial Mappings }

\section{Robotics and Automatic Geometric Theorem Proving}

\subsection{Geometric Description of Robots }

\end{document}


% Percent signs are comments.

% We start with the preamble.  This is the section where you load packages
% (these are like python modules), styles, and define the document.

% Let's define a document.  Other built-in types are book, slide, letter,
% report, etc.
\documentclass[12pt, letterpaper]{article}
% Note the form of a latex command: a backslash, the command name,
% and two sets of arguments.  In curly braces, we see the actual argument.
% In the brackets, we see options relevant to that argument.  Here, we set
% the document class (article) and two options relevant to that argument
% (font size and paper type).

% Packages expand capabilities in the current document.  To include a package,
% place the package style file (*.sty) into the directory you are working in.
% Better yet, install the package along side your LaTeX installation.  There
% are several ways to do this, I find package managers to be the easiest.
% More info here: https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages
% Let's load some packages:
\usepackage{graphicx} %Allow graphics.
\usepackage{lineno}   %Latex will complain if the lineno.sty file is not in PWD.
\usepackage[authoryear]{natbib}   %More cite commands, author-year format.

% I found that pdflatex, my favorite weapon-of-choice, was goofing my
% margins.  These commands fix that:
% Force pdflatex to use correct paper size.
%\special{papersize=8.5in,11in}
%\setlength{\pdfpageheight}{\paperheight}
%\setlength{\pdfpagewidth}{\paperwidth}
%%%NOTE- COMMENTED OUT AS NEWER VERSIONS OF TEXLIVE DO NOT HAVE THIS PROBLEM.

% I want my own command to create the backslash character:
% The command's name is ``bslash''; it has zero arguments; when called, it
% simply performs the ``\textbackslash'' function.
\newcommand{\bslash}[0]{\textbackslash}

% I want another command to take two arguments and put them into mathematical
% function notation.  The function name is \func, it has two arguments, and it
% puts the arguments into a math-mode statement.  The #1 and #2 are where
% arguments one and two are placed.  Examples can be see in the section
% ``make yer own commands''.
\newcommand{\func}[2]{$f(#1)=#2$}

% Eventually, we want to get to work.  We do this by entering the document
% environment like so:
\begin{document}

% Set up title page.
\title{\LaTeX: Greatest Thing Evar}
\author{D. T. Welling\\PHYS 5391} % double-slash for new line.
\date{\today}  % the \today command inserts today's date.

% Create both title page and contents.
% Use page breaks.
\maketitle
\newpage
\tableofcontents
\newpage

% Everything in Latex is some sort of environment.  \begin is a big part
% of what you'll do.

% The lineno package gives us new commands that weren't available before.
% For example, let's turn on our line numbers.
\linenumbers

% Let's start a section.  Sectioning is easy!
\section{Basic Text}
% I can also do subsection, subsubsection, chapter, part, etc.

Here is our first text.  We just type away!
One carriage return will NOT start a new paragraph.  But...

...two will.  I can use \textbackslash noindent to prevent a new paragraph...

\noindent
...started here, from indenting.  There are a LOT of little commands like this.
If I need more space, I can insert a single line by using two slashes.
\\

Tadaa!  Or I can use the vspace command, like so:
\vspace{4mm}

Again, Tadaa!  Note that the vspace doesn't create another line, just space.

Simple special symbols can be created: \& \% \$ \_ and so on.  Escaping
characters is very useful.  If things go wrong, try escaping some characters
that \LaTeX may be confusing for command-like syntax.

Adding emphasis is also easy: \emph{This adds emphasis}, \textbf{this makes
things bold}, \textit{and this makes things italic.}  Note that the
\textit{emph} command works inside other blocks to add more emphasis:
\textit{we can make italics and then \emph{over emphasize} the text more.}

You can also change the font style mid-sentence:
\texttt{Typewriter script.  Makes for good code examples.}
\textsf{Sans serif.  Makes for... something.}
\textsc{I am so very angry.}

\LaTeX gives you minute control over spacing inside of a paragraph.  For
example, to get a normal space after a period, use a backslash:

etc. and so on. (No slash.)

etc.\ and so on. (Slash.  Slight, but important.)

Tildes (\~\ ) are similar, but prevent line breaks.  The space between Dr. and
Welling in Dr.~Welling will never break across a line.

Super-scripts are easy:  \textsuperscript{Up here}.
\

\section{Math Environment}
Doing math is easy in \LaTeX.  There are a few ways to do it, however.  The
first is with the full math environment:

\begin{math}
  % Note that \[ and \] would also work instead of \begin and \end (math only.)
  \nabla \cdot B
\end{math}

We can add an official equation:
\begin{equation}
  \label{eq:1}
  \nabla \cdot B
\end{equation}

Note that the ``official'' equation has a number and accepts a label.
We'll talk about labels soon.

There are so many equation functions and symbols that it is impossible to list
them all in an example file like this.  But let's make a mess for fun:

\[
\ddot{Q}\stackrel{\mathrm{def}}{=}\int_{0}^{2\pi}
\left( \frac{\sqrt[3]{x^2+y^2}}{\bar{A}\times\bar{B}} \right) dx
\]

Inline math text is done easily with dollar signs: $math=great$.

\section{Other cool environments}

\begin{quote}
  The \emph{quote} environment will push a whole block of text over by one tab.
  This is great for delimiting chunks of text that should stand out for some
  reason or another.
\end{quote}

\begin{center}
  \emph{center} will center a block of text.
\end{center}

\begin{verbatim}
Verbatim is very helpful when writing blocks of example code:
A lot of stuff is written here. 23@#%#$^WERGSERYE%^*$#^
\end{verbatim}

The tabular environment is super important!
% For tables, you must use a 2nd argument to define the columns.
% the l, c, and r define left, right, or center justification for each
% column.  The vertical bars turn on vertical lines.
\begin{tabular}{l|c|r}
  % For each row, separate the columns with ampersands.
  Col 1 & Col 2 & Col 3\\
  % The \hline command adds a horizontal line.
  \hline
  item 1 & item 2 & item 3\\  % ...don't forget to start a new column
  item 4 & item 5 & item 6\\  % with double-slashes.
\end{tabular}

There are several list environments, too.  For example,
\begin{itemize}
  \item Bulleted lists
  \item use bullets
  \item to delimit items.
\end{itemize}

% Note how each item begins with \item.
\begin{enumerate}
  \item To get numbered lists
  \item use the {\tt enumerate} environment
  \item it's great!
\end{enumerate}

Don't forget that you can combine environments to get the result you want.
I like to combine quote and verbatim for making source code examples:
\begin{quote}
\begin{verbatim}
>>> import spacepy.pybats as pb
>>> mhd=pb.Bats2d('example.dat')
>>> mhd.add_contour('x','y','rho',filled=False)
\end{verbatim}
\end{quote}

\section{Floats}

Note that our table created in the last section wound up in-line.
That's not very nice.  We need to enter the \emph{table} environment to add
an ``official'' table that can have a caption, a label, etc.  Let's also add
some complexity to that you can see how tables work more clearly.  Behold!
Table \ref{tab:ex1}!

% We'll see more of this syntax explained below (e.g., the !h).
\begin{table}[!h]
  \begin{center}
  \begin{tabular}{|l|c|l r|}
    \hline
    Col 1 & Col 2 & Col 3.1 & Col 3.2\\
    \hline
    \hline
    item 1 & item 2 & item 3.1 & item 3.2\\
    item 4 & item 5 & item 6.1 & item 6.2\\
    \hline
  \end{tabular}
  % Caption and label commands are key.
  \caption{An official table that we will use.}
  \label{tab:ex1}
  \end{center}
\end{table}

We did some little things: added a captions, used references and labels (
see Section \ref{sec:cross}), and changed our lines and the number of columns.
The result?  A numbered, caption table placed neatly where it fits.

But how do we know where \LaTeX will put it?  Tables, figures, and other
objects that should not be broken across a page break (unlike paragraphs) are
known as \emph{floats}, and \LaTeX has its own rules for where to put them.
We can give suggestions, as we did in the declaration of our table:
\begin{quote}
\begin{verbatim}
\begin{table}[!h]
\end{verbatim}
\end{quote}
The {\tt !h} option says to put the float ``here'', or as close as you can
without  making the document look like an idiot put it together.  Adding the
exclamation point tells \LaTeX to take this suggestion more strongly than
normal at the cost of making the document layout look crappier.  Other options
we could have used are {\tt t}, {\tt b}, or {\tt p} for top of page, bottom of
page, or on a special page at the end of the document.  There are advanced
float placement rules, including rules for wrapping text around it, etc.,
but we won't tackle that today.

\section{Figures}

Figures can be tricky.  First, you need to turn on the \emph{graphicx} package.
Next, you must know that latex interpreters have limitations.  The standard
\LaTeX interpreter, {\tt latex}, will accept PDF and PostScript (PS) type
pictures.  My favorite, {\tt pdflatex}, will take PDF or PNG.  Let's go ahead
and add a pic; see comments in the source file for details.  Behold!
Figure \ref{fig:dog}!

\begin{figure}[!b] % I want this picture at the bottom of a page.
\begin{center}
  % This command adds the picture.  The optional arguments can resize, rotate,
  % flip, and do other operations on the picture.  The required argument is the
  % figure itself.  You can list a figure in any folder so long as you list the
  % proper path.
  \includegraphics[width=8cm]{dogphone.png}
  \caption{Get off the phone, dog.}
  \label{fig:dog}
\end{center}
\end{figure}

\section{Cross-reference!}
\label{sec:cross}

Throughout this fake document, I've been able to reference certain sections,
figures, and tables.  I haven't done this in a hard-coded manner (e.g., in a
way such that if the order of the sections or figures changes, I would be
required to change every instance where I refer to that item).  Rather, I've
been using the \emph{label} environment.  This allows me to use the command
{\tt \bslash label} to label a figure or section, then use {\tt \bslash ref} to
reference it using the label.  See the source code for examples.

There are some catches, however.  If you don't put your label command in the
correct spot, especially for floats (figures, tables, etc.), \LaTeX won't use
the correct number.  The key is to put the label command \emph{after} the
caption and in the \emph{same environment} as the item you are trying to label.

A final note on references: often, you'll run \LaTeX on your source file only
to have it complain that it could not find certain labels used in your
references.  Typically, you just need to run the interpreter one more time and
you'll be fine.

\section{Source Compilation}
\label{comp}
So far, we have a nice way to make complicated source code with lots of
esoteric rules and slashes.  How do we turn that into a formatted PDF file?
Let's look at what happens at the \emph{terminal} via a set of manual commands.
From the directory that contains your source file, use this command:
\begin{quote}
\begin{verbatim}
latex example.tex
\end{verbatim}
\end{quote}
If everything has gone correctly, you see a whole bunch of new files in your
folder: {\tt example.log}, {\tt example.aux}, and {\tt example.dvi}.  The
last one, the {\tt dvi} file, is a \emph{Device Independent} output file.
This needs to be converted into a PDF or another format via a call to another
program (e.g., {\tt dvipdf}).  That's not very helpful!  Let's use a different
program, {\tt pdflatex}, to produce a PDF right away:
\begin{quote}
\begin{verbatim}
pdflatex example.tex
\end{verbatim}
\end{quote}
Now we see a real PDF file with our output!  Good.  If you have a lot of
cross-references in your file, you may notice that these don't work in
your PDF.  That's fine, just run {\tt pdflatex} again to fix all referencing.
\textbf{When making a final document, always run the compilation step more
  than once to make sure all references and cross references work.}  It takes
\LaTeX \ two passes to do it right: once to make a list of all of the labels
and references (saved in the {\tt .aux} file) and once to include them in the
final PDF.  Always look at the output from the compilation step to make sure
there are no warnings about references!

What's that?  You don't have a PDF?  Something probably went wrong.  That's
okay.  When something goes wrong with \LaTeX , it usually asks for more info
by first posting an error, then printing a question mark and waiting for the
user's response.  Here's an example that we get by purposely introducing a
typo:
\begin{quote}
\begin{verbatim}
! Undefined control sequence.
l.137 \en
         {quote}

?
\end{verbatim}
\end{quote}

When the dreaded ``{\tt ?}'' comes up, you can usually respond with {\tt q} then
pressing enter.  This tells \LaTeX \ to give up for now.  If you continue to
press enter, you will keep getting a list of issues until \LaTeX \ reaches the
end of the file.  It's usually best to just quit and fix the first problem
first.  When you have an issue, keep these things in mind:

\begin{itemize}
\item Start by locating the line number of the problem.  In the above example,
  our line number is {\tt l.137}, or line 137.
\item \emph{READ} the error message.  They can be esoteric, but often \LaTeX \
  is telling you exactly what is wrong.
\item \emph{ALWAYS} fix the first problem first.  Errors cascade such that one
  issue will cause many more.  Fix the first one and many more will disappear.
\item Look for simple but common errors.  Did you mispell a command?  Did you
  forget to close out an environment with an {\tt end} command?  Are you
  missing a special package or style file required in your document?
\item Isolate the issue. If you comment out the line that is causing the
  problem, does it still happen?  Can you narrow it down to a certain spot
  in that line?  Once you know the exact issue, Google it!
\end{itemize}

A final note on compilation: the steps above are for working from the command
line.  Special editors, such as TeXShop, will have buttons to push and
settings to play with to get the output just right.  I recommend feeling out
these programs by creating really simple example files and testing compilation
out on those.

\section{Make yer own commands.}

Making your own commands is easy and right useful.  As an example, above,
rather than use the verbose {\tt \bslash textbackslash}, I created a shorter
command called {\tt \bslash bslash} that does the same thing with half of the
typing.  Making commands with variable arguments is possible, too.  Here's the
result of a command called {\tt \bslash func}, which inserts arguments into the
correct position in a simple mathematical function:
\func{2x}{26}; \func{36}{x-y}.  Again, see the source code for details.

\section{Title pages, etc.}
There are built-in tools for making title pages, contents, etc.  See the
commands in the source code; be sure to use {\tt \bslash newpage} to ensure
each winds up on its own page.

\section{Making Bibliographies}
It's possible to do the bibliography by hand, but that's for suckers.  Are
you a sucker? NO!  Use BibTex, fool.

\subsection{Bibtex Files}
A bibtex file contains all of the info for
any references you may use in the following format:

\begin{quote}
\begin{verbatim}
@ARTICLE{welling:2010c,
   author = {{Welling}, D.~T.},
    title = "{The long-term effects of space weather on satellite operations}",
  journal = {Annales Geophysicae},
     year = 2010,
    month = jun,
   volume = 28,
    pages = {1361-1367},
      doi = {10.5194/angeo-28-1361-2010}
}
\end{verbatim}
\end{quote}

This is an {\it article} entry, but you can also make {\it book},
{\it conference}, {\it inproceedings}, and other entries.  There are many other
fields that can be filled in to make your entry more complete.

\subsection{Building Bibtex Files}
There are many sources for getting bibtex entries.  Typically, your research
group or advisor will have a standard one that contains most everything.
Many websites that list articles will have corresponding bibtex entries to save
you the hassle of building them manually.  Other times, you'll just have to add
an entry by yourself.  In the end, you'll have a running bibtex file that grows
as you write more.

\subsection{Citations}
The label {\tt welling:2010c} is how you reference a citation in \LaTeX.  For
example, to reference \cite[p. 13]{welling:2010c} in the text, I typed
\verb+\cite[p. 13]{welling:2010c}+ voila!  Citation acheived.  This sentence is
very important \cite[]{dungey1961,axford1961,Parker:1960}.
There are other commands,
such as {\tt \bslash citet}, which puts the citation in the sentence and does
not bracket it off.  There is also {\tt \bslash citep}, which creates a
parenthetical citation.
{\tt \bslash nocite} will ensure the cited work winds up
in the bibliography without creating an inline-citation.
Example: \citet{welling:2011} said that dogs sometimes eat potatoes.
He was wrong.  The {\tt \bslash citep} and {\tt \bslash citet} commands often
work much better than the plain {\tt \bslash cite} command, so I recommend
using those.  However, there is one extra step required to use these:
To get these extra  commands, we must use an additional
package, {\tt natlib}.  As such, the following command appears in this
document's preamble:

\begin{quote}
\begin{verbatim}
\usepackage[authoryear]{natbib}
\end{verbatim}
\end{quote}

\noindent ...where the {\tt authoryear} syntax specifies that I want to cite
by author-year.  Other options inlcude {\tt apalike}, {\tt alpha}, and others.
Look them up!

\subsection{Building the Bib}
Once you have a bibtex file and have created all of the citations, put this at
the end of your article (or where you wish to put your bibliography):

\begin{quote}
\begin{verbatim}
\bibliographystyle{plainnat}
\bibliography{sample_bib}
\end{verbatim}
\end{quote}

These commands point to the bibliography style files (\emph{must} end in
{\tt .bst}) and your bibtex file (\emph{must} end in {\tt .bib}).  There are
some built in bibliography files, but typically you are given a particular file
 from a journal.  Here, we're using the built-in bibstyle, {\tt plainnat.bst}.
This is included with the natlib package.  If it wasn't, we would need that
file either installed in the correct \LaTeX folder or placed in the current
working directory.

Compilation becomes a bit more difficult.  First, run your \LaTeX interpreter
once.  There will be much gnashing of teeth as \LaTeX won't know what to do
with your citations.  That's fine; ignore it.  Next, run bibtex as follows:

\begin{quote}
\begin{verbatim}
bibtex example
\end{verbatim}
\end{quote}

\emph{Note that we did NOT use the file extension!}  Finally, run your \LaTeX\
interpreter again; two more times if you want to be thorough.   Here, it's good
to start using a Makefile to make your life easier.  You'll notice that bibtex
creates a bunch of new files, notably {\tt example.bbl}.
\emph{This file is your bibliography}, and if you open it, you'll see what you
must type into your file manually if you don't use bibtex!

Finally, run your \LaTeX interpreter once (or twice for cross-references) more
to finish your document.  Beautiful!  Note that using the plain bib-style and
the Article document class, References did not get its own section.  It's
possible to force this, either by changing document class, using a different
bib style, or using a combination of commands to force \LaTeX to do your
bidding (you'll note that we have taken that route in the source file.)

\section{Other Crap}
You can do damn near anything in \LaTeX, just be sure to GDS (the golden rule of
programming).  Two columns, text wrapping around figures and tables, different
fonts, advanced tabbing, etc. are all possible.  It's possible to create your
own stuff, but this is usually not necessary- someone has likely done it before.

% These two lines force a new page and a section in the table of contents
% for the bibliography.  Very useful.
\clearpage
\addcontentsline{toc}{section}{Bibliography}
% Using Bibtex, we just use these two lines to add the bib!
\bibliographystyle{plainnat}
\bibliography{sample_bib}

% End the document environment.  No other lines will be read after this point.
\end{document}