manual.tex

\documentclass{article}

\newcommand{\thetitle}{The Julia Programming Language}

\usepackage{amsmath}
\usepackage[hyperfigures,bookmarks,bookmarksopen,bookmarksnumbered,colorlinks,linkcolor=black,citecolor=black,filecolor=blue,menucolor=black,pagecolor=blue,frenchlinks=true,pdftitle={\thetitle}]{hyperref}
\usepackage[left=1in,top=1in,right=1in,bottom=1.25in,nohead]{geometry}
\usepackage[utf8x]{inputenc}
\usepackage{tikz}

\title{\vspace{2.5in}\thetitle}
\author{
Jeff Bezanson \vspace{0.5em}\\
Stefan Karpinski \vspace{0.5em}\\
Viral Shah \vspace{0.5em}\\
Alan Edelman \vspace{0.5em}
}

\renewcommand{\sec}[1]{\label{sec:#1}}
\newcommand{\fig}[1]{\label{fig:#1}}
\newcommand{\tab}[1]{\label{tab:#1}}

\newcommand{\Section}[1]{\hyperref[sec:#1]{Section~\ref*{sec:#1}}}
\newcommand{\Figure}[1]{\hyperref[fig:#1]{Figure~\ref*{fig:#1}}}
\newcommand{\Table}[1]{\hyperref[tab:#1]{Table~\ref*{tab:#1}}}

\renewcommand{\bullet}{{$\diamond$}}
\renewcommand{\labelitemi}{\bullet}
\renewcommand{\labelitemii}{\bullet}
\renewcommand{\labelitemiii}{\bullet}

\renewcommand{\O}{\ensuremath{\operatorname{O}}}

\newcommand{\placeholder}[1]{$\left<\text{\emph{#1}}\right>$}

\begin{document}

\maketitle

\clearpage

\section*{Preface}

Scientific computing has traditionally required the highest
performance, yet domain experts have largely moved to slower dynamic
languages for daily work.  We believe there are many good reasons to
prefer dynamic languages for these applications, and we do not expect
their use to diminish.  Fortunately, modern language design and
compiler techniques make it possible to mostly eliminate the
performance trade-off and provide a single environment productive
enough for prototyping and efficient enough for deploying
applications.  The Julia programming language fills this role: it is a
flexible, dynamic language, designed expressly for scientific
computing, and achieving performance comparable to traditional
compiled languages.

The syntax of Julia is similar to Matlab, and consequently Matlab
programmers should feel immediately comfortable with Julia.  While
Matlab is quite effective for prototyping and exploring numerical
linear algebra, it has limitations for programming tasks outside of
this relatively narrow scope.  Julia keeps Matlab's ease and
expressiveness for high-level numerical computing, but transcends its
general programming limitations.  To achieve this, it borrows much
from the C programming language, and is strongly influenced by the
lineage of dynamic languages: Lisp, Perl, Python, Lua and Ruby.

\clearpage

\tableofcontents

\clearpage

\section{Getting Started}\sec{getting-started}

\subsection{Obtaining and Installing Julia}\sec{obtaining-and-installing}

\subsection{Running Code}\sec{running-code}

The easiest way to learn and experiment with Julia is by interacting with the read-eval-print loop (repl):
\begin{verbatim}
  $ julia
                 _      
     _       _ _(_)_     |
    (_)     | (_) (_)    |  
     _ _   _| |_  __ _   |
    | | | | | | |/ _` |  |
    | | |_| | | | (_| |  |  2009-2011 contributors
   _/ |\__'_|_|_|\__'_|  |  
  |__/                   |

  julia> 1 + 2
  3

  julia> ans
  3

  julia> load("file.j");
\end{verbatim}
When run in repl mode, \verb|julia| displays a banner and prompts the user for input.
Once the user has entered a complete expression, such as \verb|1 + 2|, and hits enter, the repl evaluates the expression and shows its value.
If an expression is entered into the repl with a trailing semicolon, its value is not shown.
The variable \verb|ans| is bound to value of the last evaluated expression whether it is shown or not.
The \verb|load| function reads and evaluates the contents of the given file.

To run code in a file non-interactively, you can give it as the first argument to the julia command:
\begin{verbatim}
  $ julia script.j arg1 arg2...
\end{verbatim}
As the example implies, the following command-line arguments to julia are taken as command-line arguments to the program \verb|script.j|.
There are various ways to run Julia code and provide options, similar to those taken by the \verb|perl| and \verb|ruby| programs:

\begin{verbatim}
  julia [options] [program] [args...]
   -q --quiet               Quiet startup without banner
   -R --no-readline         Disable readline functionality
   -e --eval=<expr>         Evaluate <expr> and don't print
   -E --print=<expr>        Evaluate and print <expr>
   -P --post-boot=<expr>    Evaluate <expr> right after boot
   -H --home=<dir>          Load files relative to <dir>
   -T --tab=<size>          Set REPL tab width to <size>
   -L --lisp                Start with Lisp prompt not Julia
   -b --bare                Bare REPL: don't load start.j
   -h --help                Print this message
\end{verbatim}


\section{Numbers and Arithmetic}\sec{numbers-and-arithmetic}

Julia provides a broad range of numeric types together with a full complement of arithmetic operators, bitwise operators, and common mathematical functions on them.
The following are Julia's primitive numeric types:
\begin{itemize}
  \item Integer types:
  \begin{itemize}
    \item \verb|Int8|~: signed 8-bit integers ranging from $-2^7$ to $2^7-1$.
    \item \verb|Uint8|~: unsigned 8-bit integers ranging from 0 to $2^8-1$.
    \item \verb|Int16|~: signed 16-bit integers ranging from $-2^{15}$ to $2^{15}-1$.
    \item \verb|Uint16|~: unsigned 16-bit integers ranging from 0 to $2^{16}-1$.
    \item \verb|Int32|~: signed 32-bit integers ranging from $-2^{31}$ to $2^{31}-1$.
    \item \verb|Uint32|~: unsigned 32-bit integers ranging from 0 to $2^{32}-1$.
    \item \verb|Int64|~: signed 64-bit integers ranging from $-2^{63}$ to $2^{63}-1$.
    \item \verb|Uint64|~: unsigned 64-bit integers ranging from 0 to $2^{64}-1$.
  \end{itemize}
  \item Floating point types:
  \begin{itemize}
    \item \verb|Float32|~: IEEE 754 32-bit floating point numbers.
    \item \verb|Float64|~: IEEE 754 64-bit floating point numbers.
  \end{itemize}
\end{itemize}
Full support for complex and rational numbers is built on top of these primitive numeric types.
All numeric types interoperate naturally without explicit casting, thanks to a flexible type promotion system.
Moreover, this promotion system (detailed in \Section{conversion-and-promotion}) is user-extensible, so user-defined numeric types can be made to interoperate just as naturally with built in numerics and with each other.

\subsection{Integer Literals}\sec{integer-literals}

The default type for an integer literal is \verb|Int32|:
\begin{verbatim}
  julia> typeof(1)
  Int32
\end{verbatim}
Larger integer literals which cannot be represented using only 32 bits but can be represented in 64 bits create 64-bit integers:
\begin{verbatim}
  julia> typeof(4294967296)
  Int64
\end{verbatim}
Integers can be input in hexadecimal form using the \verb|0x| prefix as in C:
\begin{verbatim}
  julia> 0xff
  255

  julia> typeof(ans)
  Int32

  julia> 0xffffffff
  4294967295

  julia> typeof(ans)
  Int64
\end{verbatim}
There is no literal input format for integer types besides \verb|Int32| and \verb|Int64|. You can, however convert \verb|Int32| and \verb|Int64| values to other types easily:
\begin{verbatim}
  julia> int8(-15)
  -15

  julia> typeof(ans)
  Int8

  julia> uint8(231)
  231

  julia> typeof(ans)
  Uint8
\end{verbatim}

\subsection{Floating Point Literals}\sec{floating-point-literals}

Floating point numbers are input in the standard formats:
\begin{verbatim}
  julia> 1.0
  1.0

  julia> 1.
  1.0

  julia> 0.5
  0.5

  julia> .5
  0.5

  julia> -1.23
  -1.23

  julia> 1e10
  1e+10

  julia> 2.5e-4
  0.00025
\end{verbatim}
The above results are all \verb|Float64| values. There is no literal format for \verb|Float32|, but you can convert values to \verb|Float32| easily:
\begin{verbatim}
  julia> float32(-1.5)
  -1.5

  julia> typeof(ans)
  Float32
\end{verbatim}
There are three specified standard floating point values that do not correspond to a point on the real number line: infinity (\verb|Inf|), minus infinity (\verb|-Inf|), and not-a-number (\verb|NaN|).
By the IEEE 754 standard, these floating point values are the results of certain arithmetic operations:
\begin{verbatim}
  julia> 1/0
  Inf

  julia> -5/0
  -Inf

  julia> 0.000001/0
  Inf

  julia> 0/0
  NaN

  julia> 500 + Inf
  Inf

  julia> 500 - Inf
  -Inf

  julia> Inf - Inf
  NaN

  julia> Inf/Inf
  NaN
\end{verbatim}

\subsection{Arithmetic Operators}\sec{arithmetic-operators}

The following arithmetic and bitwise operators are supported on numeric types:
\begin{itemize}
  \item Arithmetic operators (all numeric types):
  \begin{itemize}
    \item \verb|+x|~: unary plus is the identity operation.
    \item \verb|-x|~: unary minus maps values to their additive inverses.
    \item \verb|x + y|~: binary plus performs addition.
    \item \verb|x - y|~: binary minus performs subtraction.
    \item \verb|x * y|~: times performs multiplication.
    \item \verb|x / y|~: divide performs division.
  \end{itemize}
  \item Bitwise operators (integer types only)\,:
  \begin{itemize}
    \item \verb|~x|~: bitwise not.
    \item \verb|x & y|~: bitwise and.
    \item \texttt{x | y}~: bitwise or.
    \item \verb|x $ y|~: bitwise xor.
    \item \verb|x << y|~: logical shift left.
    \item \verb|x >> y|~: logical shift right.
    \item \verb|x >>> y|~: arithmetic shift right.
  \end{itemize}
\end{itemize}
Here are some simple examples using arithmetic operators:\,\footnote{By convention, we tend to space less tightly binding operators less tightly, but there are no syntactic constraints.}
\begin{verbatim}
  julia> 1 + 2 + 3
  6

  julia> 1 - 2
  -1

  julia> 3*2/12
  0.5
\end{verbatim}
Julia has a type promotion system that allows arithmetic operations on mixtures of argument types to ``just work'' naturally and automatically (see \Section{conversion-and-promotion} for details of the promotion system):
\begin{verbatim}
  julia> 1 + 2.5
  3.5

  julia> 0.5*12
  6.0

  julia> 3*2/12 + 1
  1.5
\end{verbatim}
The above expressions all promote to \verb|Float64| since that is the smallest floating point type that can faithfully represent all possible \verb|Int32| values.
However, more nuanced promotions also work:
\begin{verbatim}
  julia> uint8(12) - int8(15)
  -3

  julia> typeof(ans)
  Int16

  julia> uint8(12) - float32(1.5)
  10.5

  julia> typeof(ans)
  Float32
\end{verbatim}
Here are some examples with bitwise operators:
\begin{verbatim}
  julia> ~123
  -124

  julia> ~uint32(123)
  4294967172

  julia> ~uint8(123)
  132

  julia> 123 & 234
  106

  julia> 123 | 234
  251

  julia> typeof(ans)
  Int32

  julia> uint8(123) | uint16(234)
  251

  julia> typeof(ans)
  Uint16

  julia> 123 $ 234
  145
\end{verbatim}
As a general rule of thumb, arguments are promoted to the smallest type that can accurately represent all of the arguments.

Every binary arithmetic and bitwise operator also has an updating version that assigns the result of the operation back into its left operand.
For example, the updating form of \verb|+| is the \verb|+=| operator.
Writing \verb|x += 3| is equivalent to writing \verb|x = x + 3|:
\begin{verbatim}
  julia> x = 1
  1

  julia> x += 3
  4

  julia> x
  4
\end{verbatim}
The updating versions of arithmetic and bitwise operators are:
\verb|+= -= *= /= &=|\hspace{1.3ex}\texttt{|=}\hspace{1.3ex}\verb|$= <<= >>= >>>=|\,.

\subsection{Numeric Comparisons}\sec{numeric-comparisons}

Standard comparison operations are defined for primitive numeric types:
\begin{itemize}
  \item \verb|==|~: equality.
  \item \verb|!=|~: inequality.
  \item \verb|<|~: less than.
  \item \verb|<=|~: less than or equal to.
  \item \verb|>|~: greater than.
  \item \verb|>=|~: greater than or equal to.
\end{itemize}
Here are some simple examples:
\begin{verbatim}
  julia> 1 == 1
  true

  julia> 1 == 2
  false

  julia> 1 != 2
  true
  
  julia> 1 == 1.0
  true

  julia> 1 < 2
  true

  julia> 1.0 > 3
  false

  julia> 1 >= 1.0
  true

  julia> -1 <= 1
  true

  julia> -1 <= -1
  true

  julia> -1 <= -2
  false

  julia> 3 < -0.5
  false
\end{verbatim}
As is evident here, promotion also applies to comparisons:
the comparisons are performed in whatever type the arguments are promoted to, which is generally the smallest type in which all the values can be faithfully represented.

After promotion to a common type, integers are compared in the standard manner:
by comparison of bits.
Floating point numbers are compared according to the IEEE 754 standard:
finite numbers are ordered in the usual manner;
infinity is equal to itself and greater than everything else except \verb|NaN|;
minus infinity is equal to itself and less then everything else except \verb|NaN|;
and \verb|NaN| is not equal to, less than, or greater than anything, including itself:
\begin{verbatim}
  julia> NaN == NaN
  false

  julia> NaN != NaN
  true

  julia> NaN < NaN
  false

  julia> NaN > NaN
  false
\end{verbatim}
For situations where one wants to compare floating point values so that \verb|NaN| equals \verb|NaN|, such as hash key comparisons, the function \verb|isequal| is also provided, which considers \verb|NaN|s to be equal to each other:
\begin{verbatim}
  julia> isequal(NaN,NaN)
  true
\end{verbatim}
Unlike most languages, comparisons can be arbitrarily chained:
\begin{verbatim}
  julia> 1 < 2 <= 2 < 3 == 3 > 2 >= 1 == 1 < 3 != 5
  true
\end{verbatim}
Chaining comparisons is often quite convenient in numerical code.
Only as many initial comparisons and their operand expressions as are necessary to determine the final truth value of the entire chain are evaluated.
See \Section{short-circuit-evaluation} for further discussion of this behavior.

\subsection{Mathematical Functions}

Julia provides a comprehensive set of mathematical functions and operators.
These mathematical operations are defined over as broad a class of numerical values as permit sensible definitions.
The following is a partial list of functions and operators provided:
\begin{itemize}
  \item \verb|div(x,y)| --- truncated division; quotient rounded towards zero.
  \item \verb|fld(x,y)| --- floored division; quotient rounded towards $-\infty$.
  \item \verb|rem(x,y)| --- remainder; satisfies \verb|x == div(x,y)*y + rem(x,y)|, implying that sign matches \verb|x|.
  \item \verb|mod(x,y)| --- modulus; satisfies \verb|x == fld(x,y)*y + mod(x,y)|, implying that sign matches \verb|y|.
  \item \verb|x % y| --- equivalent to \verb|mod(x,y)|.
  \item \verb|gcd(x,y...)| --- greatest common divisor of \verb|x|, \verb|y|... with sign matching \verb|x|.
  \item \verb|lcm(x,y...)| --- least common multiple of \verb|x|, \verb|y|... with sign matching \verb|x|.
  \item \verb|sign(x)| --- indicates the sign of \verb|x| using $-1$, $0$, $+1$.
  \item \verb|signbit(x)| --- indicates the sign bit of \verb|x| using $-1$, $+1$.\footnote{For IEEE floating point values, this has precise specified semantics.
  In particular, there are both positive and negative zero and \texttt{NaN} values.
  For other numeric types, this is essentially just a test of whether \texttt{x < 0} or not.}
  \item \verb|copysign(x,y)| --- a value with the magnitude of \verb|x| and the sign of \verb|y|.
  \item \verb|sqrt(x)| --- the square root of \verb|x|.
  \item \verb|exp(x)| --- the natural exponential function $e^x$ at \verb|x|.
  \item \verb|x^y| --- \verb|x| raised to the exponent \verb|y| ($x^y$).
  \item \verb|log(x)| --- the natural logarithm of \verb|x|.
  \item \verb|log2(x)| --- the base 2 logarithm of \verb|x|.
  \item \verb|log10(x)| --- the base 10 logarithm of \verb|x|.
  \item \verb|log(b,x)| --- the base \verb|b| logarithm of \verb|x|.
\end{itemize}
Additionally, all the standard trigonometric functions are defined:
\verb|sin|,   \verb|cos|,   \verb|tan|,   \verb|cot|,  \verb|sec|,  \verb|csc|,
\verb|sinh|,  \verb|cosh|,  \verb|tanh|,  \verb|coth|, \verb|sech|, \verb|csch|,
\verb|asin|,  \verb|acos|,  \verb|atan|,  \verb|acot|, \verb|asec|, \verb|acsc|,
\verb|acoth|, \verb|asech|, \verb|acsch|, \verb|sinc|, \verb|cosc|.

The mathematical functions with operator notation, \verb|%| and \verb|^|, both also have an updating form, like the arithmetic and bitwise operators:
\begin{verbatim}
  julia> x = 2; x ^= 5; x
  32

  julia> x = 7; x %= 4; x
  3
\end{verbatim}
Like the updating forms of other operators, \verb|x ^= y| means \verb|x = x^y| and \verb|x %= y| means \verb|x = x % y|.

\subsection{Numeric Literal Coefficients}

To make common numeric formulas and expressions clearer, Julia allows variables to be immediately preceded by a numeric literal, implying multiplication.
This makes writing polynomial expressions much cleaner:
\begin{verbatim}
  julia> x = 3
  3

  julia> 2x^2 - 3x + 1
  10

  julia> 1.5x^2 - .5x + 1
  13.0
\end{verbatim}
% TODO: note about variables and assignment.
You can also use a numeric literal coefficients with parenthesized expressions:
\begin{verbatim}
  julia> 2(x-1)^2 - 3(x-1) + 1
  3
\end{verbatim}
These two simple syntactic enhancements significantly reduce the visual noise incurred when writing common mathematical formulae.
Note that no space may come between a numeric literal coefficient and the identifier or parenthesized expression which it multiplies.

Juxtaposed coefficients conflict with two numeric literal syntaxes:
hexadecimal integer literals and engineering notation for floating point literals.
Here are some situations where syntactic conflicts arise:
\begin{itemize}
\item The hexadecimal integer literal expression \verb|0xff| could be interpreted as the numeric literal \verb|0| multiplied by the variable \verb|xff|.
\item The floating point literal expression \verb|1e10| could be interpreted as the numeric literal \verb|1| multiplied by the variable \verb|e10|, and similarly with the equivalent \verb|E| form.
\end{itemize}
In both cases, we resolve the ambiguity in favor of interpretation as a numeric literals:
\begin{itemize}
\item Expressions starting with \verb|0x| are always hexadecimal literals.
\item Expressions starting with $d.dd$\,\verb|e| or $d.dd$\,\verb|E| are always floating point literals.
\end{itemize}
One final note is that parenthesized expressions can also be used as coefficients to variables:
\begin{verbatim}
  julia> (x-1)x
  6
\end{verbatim}
Juxtaposing two parenthesized expressions, however, does not imply multiplication:
\begin{verbatim}
  julia> (x-1)(x+1)
  type error: apply: expected Function, got Int32
\end{verbatim}
The error occurs since parentheses following an expression which is not a numeric literal introduces a function call, not multiplication, and the value of \verb|(x-1)| is an integer rather than a function.

\subsection{Complex Numbers}

The global constant \verb|im| is bound to the complex number $i$, representing one of the square roots of $-1$.
Since Julia allows numeric literals to be juxtaposed with identifiers as coefficients, this binding suffices to provide convenient syntax for complex numbers, similar to the traditional mathematical notation, $1 + 2i$:\,\footnote{It was deemed harmful to co-opt the name \texttt{i} for a global constant, as that would preclude its use as a variable.}
\begin{verbatim}
  julia> 1 + 2im
  1 + 2im
\end{verbatim}
You can perform all the standard arithmetic operations with complex numbers:
\begin{verbatim}
  julia> (1 + 2im)*(2 - 3im)
  8 + 1im

  julia> (1 + 2im)/(1 - 2im)
  -0.6 + 0.8im

  julia> (1 + 2im) + (1 - 2im)
  2 + 0im

  julia> (-3 + 2im) - (5 - 1im)
  -8 + 3im

  julia> (-1 + 2im)^2
  -3 - 4im

  julia> (-1 + 2im)^2.5
  2.7296244647840089 - 6.9606644595719001im

  julia> (-1 + 2im)^(1 + 1im)
  -0.2791038107582666 + 0.0870805341410243im

  julia> 3(2 - 5im)
  6 - 15im

  julia> 3(2 - 5im)^2
  -63 - 60im

  julia> 3(2 - 5im)^-1
  0.2068965517241379 + 0.5172413793103448im
\end{verbatim}
The promotion mechanism ensures that combinations of operands of different types just work:
\begin{verbatim}
  julia> 2(1 - 1im)
  2 - 2im

  julia> (2 + 3im) - 1
  1 + 3im

  julia> (1 + 2im) + 0.5
  1.0 + 2.5im

  julia> (2 + 3im) - 0.5im
  2.0 + 2.5im

  julia> 0.75(1 + 2im)
  0.75 + 1.5im

  julia> (2 + 3im) / 2
  1.0 + 1.5im

  julia> (1 - 3im) / (2 + 2im)
  -0.5 - 1.0im

  julia> 1 + 3/4im
  1.0 + 0.75im
\end{verbatim}
Note that \verb|3/4im| parses as \verb|3/4*im|, which, since division and multiplication have equal precedence, is equivalent to \verb|(3/4)*im| rather than the quite different value, \verb|3/(4im) == -(3/4)im|.

Standard functions to manipulate complex values are provided:
\begin{verbatim}
  julia> real(1 + 2.5im)
  1.0

  julia> imag(1 + 2.5im)
  2.5

  julia> conj(1 + 2.5im)
  1.0 - 2.5im

  julia> norm(1 + 2.5im)
  7.25

  julia> abs(1 + 2.5im)
  2.6925824035672519
\end{verbatim}
The full gamut of mathematical functions are also defined for complex numbers:
\begin{verbatim}
  julia> sqrt(im)
  0.7071067811865476 + 0.7071067811865475im

  julia> sqrt(1 + 2im)
  1.272019649514069 + 0.7861513777574233im

  julia> cos(1 + 2im)
  2.0327230070196656 - 3.0518977991517997im

  julia> exp(1 + 2im)
  -1.1312043837568135 + 2.4717266720048188im

  julia> sinh(1 + 2im)
  -0.4890562590412937 + 1.4031192506220405im
\end{verbatim}

If you need to construct a complex number using variables, the literal numeric coefficient notation will not work, so you have to explicitly write the multiplication operation:
\begin{verbatim}
  julia> a = 1; b = 2; a + b*im
  1 + 2im
\end{verbatim}

\subsection{Rational Numbers}

Julia has rational numbers to represent exact ratios of integers.
Rationals are constructed by the \texttt{//} operator:
\begin{verbatim}
  julia> 2//3
  2//3
\end{verbatim}
If the numerator and denominator of a rational have common factors, they are reduced to lowest terms such that the denominator is non-negative:
\begin{verbatim}
  julia> 6//9
  2//3

  julia> -4//8
  -1//2

  julia> 5//-15
  -1//3

  julia> -4//-12
  1//3
\end{verbatim}
This normalized form for a ratio of integers is unique, so equality of rational values can be tested by checking for equality of the numerator and denominator.
The standardized numerator and denominator of a rational value can be extracted using the \verb|num| and \verb|den| functions:
\begin{verbatim}
  julia> num(2//3)
  2

  julia> den(2//3)
  3
\end{verbatim}
Direct comparison of the numerator and denominator is generally not necessary, since the standard arithmetic and comparison operations are defined for rational values:
\begin{verbatim}
  julia> 2//3 == 6//9
  true

  julia> 2//3 == 9//27
  false

  julia> 3//7 < 1//2
  true

  julia> 3//4 > 2//3
  true

  julia> 2//4 + 1//6
  2//3

  julia> 5//12 - 1//4
  1//6

  julia> 5//8 * 3//12
  5//32

  julia> 6//5 / 10//7
  21//25
\end{verbatim}
Rationals can be easily converted to floating point numbers:
\begin{verbatim}
  julia> float(3//4)
  0.75
\end{verbatim}
Conversion from rational to floating point respects the following identity for any integral values of \verb|a| and \verb|b|:
\begin{verbatim}
  julia> isequal(float(a//b), a/b)
  true
\end{verbatim}
This includes cases where \verb|a == 0| or \verb|b == 0|, in which situations the conversion from rational value to floating point produces the appropriate $\pm$\verb|Inf| or \verb|NaN| value:
\begin{verbatim}
  julia> 5//0
  1//0

  julia> float(ans)
  Inf

  julia> 0//0
  0//0

  julia> float(ans)
  NaN

  julia> -3//0
  -1//0

  julia> float(ans)
  -Inf
\end{verbatim}
In a sense, Julia's rational values are a convenient way of deferring the computation of integer ratios, thereby allowing exact canceling of common factors and avoiding accumulation of floating point errors.

As usual, the promotion system makes interactions with other numeric types natural and effortless:
\begin{verbatim}
  julia> 3//5 + 1
  8//5

  julia> 3//5 - 0.5
  0.1

  julia> 2//7 * (1 + 2im)
  2//7 + 4//7im

  julia> 2//7 * (1.5 + 2im)
  0.4285714285714285 + 0.5714285714285714im

  julia> 3//2 / (1 + 2im)
  3//10 - 3//5im

  julia> 1//2 + 2im
  1//2 + 2//1im

  julia> 1 + 2//3im
  1//1 + 2//3im

  julia> 0.5 == 1//2
  true

  julia> 0.33 == 1//3
  false

  julia> 0.33 < 1//3
  true

  julia> 1//3 - 0.33
  0.0033333333333333
\end{verbatim}

\section{Strings}
\sec{strings}

% Traditionally, strings are conceptualized as sequences of characters, which mathematically is a function from indices to characters.
% When all characters are exactly one byte, this can be conveniently and efficiently represented with a plain old array of bytes.
% It's simple and efficient.
% End of story.
% 
% Unicode complicates things because common encodings like UTF-8 and UTF-16 are variable-width, meaning that characters require different numbers of bytes in their representation.
% In UTF-8, for example, all of the ASCII characters are one byte, encoded just as in ASCII.
% All other characters, however, take between two and four bytes to represent.
% This means that you can't efficiently look up the $k$th character of a string by doing array indexing anymore:
% the $k$th byte of the representation is no longer the $k$th character.
% Worse still, a byte might not be the beginning of a character at all, but right in the middle of a character (this is called a ``continuation byte'').
% 
% If you allow people direct access to the bytes of an encoded string, they can and will do all sorts of bad things that produce invalid Unicode and broken behaviors when Unicode input is received.
% To provide a string abstraction that makes strings behave like functions from indices to Unicode characters (i.e. code points), you have to chose one of the following:
% \begin{enumerate}
% 
% \item Have fast, natural random access to characters, but store strings so that every character is big enough to accommodate the entire Unicode character set.
% The natural choice of encoding for this is UTF-32, in which each code point (integer value representing a unique character) is simply represented by its 32-bit integer value.
% This also requires processing every string before accessing or manipulating it to convert it from its input encoding (usually UTF-8) to UTF-32.
% Transcoding introduces a lot of overhead, forcing every string to be transcoded, typically both on input and output, as well as inflating memory usage for all strings.
% 
% \item Sacrifice the ability to represent every Unicode character and use only the two-byte characters of a 16-bit encoding like UTF-16.
% With this you can represent virtually all modern languages, but you cannot write in ancient languages like Egyptian hieroglyphs, Linear B, or represent some unusual modern characters such as certain unified Han ideographs.
% This allows fast random access, and reduces the memory inflation compared to the UTF-32 approach, but still requires transcoding almost every string on input and output.
% 
% \item Keep strings in their input form, but make indexing into a string an $\O(k)$ operation which requires scanning the entire string from the beginning to find the $k$th character from there.
% This turns a lot of straightforward $\O(n)$ string processing algorithms into $\O(n^2)$ algorithms unless you completely avoid indexing into strings altogether.
% 
% \item Represent strings by a clever, relatively complex data structure that allows strings to remain encoded, but somehow makes indexing the $k$th character look like it's faster than $\O(k)$, when it is amortized over many operations.
% One possible way to do this is to remember the last few indices that were accessed and figure out new indices relative to them.
% 
% \item Do not allow indexing into strings. Instead, only provide interfaces, such as iterating characters, which are Unicode safe as well as being efficiently implementable without transcoding strings.
% 
% \item Ignore the whole issue and just equate strings with byte arrays and let Unicode bugger itself (a.k.a.~the C approach\footnote{To be fair, the C language long predates the Unicode standard.}).
% 
% \end{enumerate}
% Technically, option 5 doesn't actually keep the abstraction of strings as functions from indices to characters, so perhaps it doesn't belong here;
% and option 6 isn't a solution at all, but rather a matter of deciding that you just don't care.
% Option 2 is not really a solution, either, but a pragmatic compromise that gets you 90\% of the way (unless you happen to want to process hieroglyphs).
% Frankly, none of these options is good enough for something as fundamental and performance-critical as string processing.
% 
% \subsection{The Partial Function Approach}
% \sec{partial-function-strings}
% 
% Our approach is to change the abstraction of what a string is instead of choosing any of the above.
% Rather than conceptualizing a string as a function from indices to characters, we conceptualize a string as a \emph{partial function} from indices to characters.
% What does this mean?
% It means that when indexing into a string, for some indices no character value is returned:
% instead of returning a value, the language throws an exception.
% So in short \verb|str[k]| will throw an exception if $k$ doesn't correspond to a character.
% For UTF-8 strings that are plain ASCII this will never happen.
% For UTF-32 strings it will never happen.
% For UTF-16 strings including only the common two-byte characters it will never happen.
% For other instances of encoded strings, it could happen, however.
% 
% How does this modified abstraction help?
% It recognizes that bytes and characters are not one-to-one in many encodings, but still allows you store strings in their native encoding and retrieve characters efficiently by a byte index, rather than a character index.
% If you try to get or set a character at an index that isn't the start of a character, it's an exception---indicating that the partial function isn't defined there.
% The ``string''---as one normally thinks of it---is the sequence characters returned by the string as the indices range from one to the maximum index.
% The gotcha is that some indices don't return a character.
% 
% Code that na\"ively iterates through all indices will work and work with C-like performance, until it encounters strange input data, at which point it will throw a nice clean exception letting you know exactly what the problem is.
% You can probably just modify the code to catch the exception and move on to the next index.
% Alternately, you can rewrite the code to use a Unicode character iterator instead.
% Moreover, if you always consider string indices as opaque objects, and never do arithmetic with them (iterating through indices counts as arithmetic: \verb|k+=1|), then as long as you only index into a string with an index given to you by a string function, this kind of thing will never happen.
% 
% By changing the string abstraction, we can support arbitrary string encodings and other representations at C-like efficiency and with a nice, safe, clean programmatic interface.

There are a few noteworthy high-level features about Julia's approach to strings:
\begin{itemize}
\item Like C, but unlike most dynamic languages, Julia has a first-class type representing a single character, called \verb|Char|.
A \verb|Char| is a special kind of 32-bit integer, whose numeric value represents a single Unicode code point.
\item Conceptually, a \verb|String| is a \emph{partial function} from indices to \verb|Char| values --- for some index values, no character value is returned, and instead an exception is thrown.
This for allows efficient indexing into strings by the byte index of an encoded representation rather than by a character index, which cannot be implemented efficiently and simply for variable-width encodings of Unicode strings.
\item There are many different classes implementing the \verb|String| interface, not a single special one.
They all implement a common programming interface, however, and any string type can be used in any function expecting a \verb|String|.
The predefined string types are no more special than user-defined ones.
\item Strings are immutable: the value of a \verb|String| object cannot be changed.
To construct a different string value, you construct a new string object from parts of other string objects.
\end{itemize}
Although there are various implementations of the \verb|String| interface, we do not delve into the details of these variations here:
you can use all strings transparently in the same way in all string operations.

\subsection{Characters}

Like C, but unlike Perl, Python, or Ruby, Julia has a type for individual characters: \verb|Char|.
A \verb|Char| is just a 32-bit integer with a special literal representation and some specific arithmetic behaviors, interpreted as a Unicode code point.
Here is how \verb|Char| values are input and shown:
\begin{verbatim}
  julia> 'x'
  'x'

  julia> typeof(ans)
  Char
\end{verbatim}
You can convert a \verb|Char| to its integer value, i.e. code point, easily:
\begin{verbatim}
  julia> int('x')
  120

  julia> typeof(ans)
  Int32
\end{verbatim}
You can convert an integer value back to a \verb|Char| just as easily:
\begin{verbatim}
  julia> char(120)
  'x'
\end{verbatim}
Not all integer values are valid Unicode code points, but for performance, the \verb|char| conversion does not check that every character value is valid.
If you want to check that each converted value is a value code point, use the \verb|safe_char| conversion instead:
\begin{verbatim}
  julia> char(0xd800)
  '???'

  julia> safe_char(0xd800)
  invalid Unicode code point: U+d800

  julia> char(0x110000)
  '\U00110000'

  julia> safe_char(0x110000)
  invalid Unicode code point: U+110000
\end{verbatim}
As of this writing, the valid Unicode code points are \verb|U+0000| through \verb|U+d7ff| and \verb|U+e000| through \verb|U+10ffff|.
These have not all been assigned intelligible meanings yet, nor are they necessarily interpretable by applications, but all of these values are considered to be valid Unicode characters.

You can input any Unicode character in single quotes using \verb|\u| followed by up to four hexadecimal digits or \verb|\U| followed by up to eight hexadecimal digits (the longest valid value only requires six):
\begin{verbatim}
  julia> '\u0'
  '\0'

  julia> '\u78'
  'x'

  julia> '\u2200'
  '∀'

  julia> '\U10ffff'
  '\U0010ffff'
\end{verbatim}
Julia uses your system's locale and language settings to determine which characters can be printed as-is and which must be output using the generic, escaped \verb|\u| or \verb|\U| input forms.
In addition to these Unicode escape forms, all of C's traditional escaped input forms are usable as well:
\begin{verbatim}
  julia> int('\0')
  0

  julia> int('\t')
  9

  julia> int('\n')
  10

  julia> int('\e')
  27

  julia> int('\x7f')
  127

  julia> int('\177')
  127

  julia> int('\xff')
  255
\end{verbatim}
Like any integers, you can do arithmetic and comparisons with \verb|Char| values:
\begin{verbatim}
  julia> 'x' - 'a'
  23

  julia> 'A' < 'a'
  true

  julia> 'A' <= 'a' <= 'Z'
  false

  julia> 'A' <= 'X' <= 'Z'
  true
\end{verbatim}
Arithmetic with \verb|Char| values always promotes them to \verb|Int32|.
To create a new \verb|Char| value, explicit conversion back to the \verb|Char| type is required:
\begin{verbatim}
  julia> 'A' + 1
  66

  julia> char(ans)
  'B'
\end{verbatim}
% Requiring explicit conversion allows a series of intermediate computations to be done efficiently, only checking that the final value is a valid Unicode code point.

\subsection{String Basics}

Here a variable is initialized with a simple string literal:
\begin{verbatim}
  julia> str = "Hello, world.\n"
  "Hello, world.\n"
\end{verbatim}
If you want to extract a character from a string, you index into it:
\begin{verbatim}
  julia> str[1]
  'H'

  julia> str[6]
  ','

  julia> str[end]
  '\n'
\end{verbatim}
All indexing in Julia is 1-based like Matlab and Mathematica, rather than 0-based like most other programming languages:
the first element of any integer-indexed object is found at index \verb|1|, not index \verb|0|, and the last element is found at index \verb|n| rather than \verb|n-1|, when the object has a length of \verb|n|.

In any indexing expression, the keyword, \verb|end|, can be used as a shorthand for \verb|length(x)|, where \verb|x| is the object being indexed into, whether it is a string, an array, or some other indexable object.
You can perform arithmetic and other operations with \verb|end|, just like a normal value:
\begin{verbatim}
  julia> str[end-1]
  '.'

  julia> str[end/2]
  ' '

  julia> str[end*1/3]
  'o'

  julia> str[end*2/3]
  'o'
\end{verbatim}
Using an index less than 1 or greater than \verb|end| raises an error:
\begin{verbatim}
  julia> str[0]
  in next: arrayref: index out of range

  julia> str[end+1]
  in next: arrayref: index out of range
\end{verbatim}
You can also extract a substring using range indexing:
\begin{verbatim}
  julia> str[4:9]
  "lo, wo"
\end{verbatim}
Note the distinction between \verb|str[k]| and \verb|str[k:k]|:
\begin{verbatim}
  julia> str[6]
  ','

  julia> str[6:6]
  ","
\end{verbatim}
The former is a single character value of type \verb|Char|, while the latter is a string value that happens to contain only a single character.
In Julia these are very different things.

\subsection{Interpolation}

One of the most common and useful string operations is concatenation:
\begin{verbatim}
  julia> greet = "Hello"
  "Hello"

  julia> who = "world"
  "world"

  julia> strcat(greet, ", ", who, ".\n")
  "Hello, world.\n"
\end{verbatim}
Constructing strings like this can become a bit cumbersome, however.
To reduce the need for these verbose calls to \verb|strcat|, Julia allows interpolation into string literals using \verb|$|, as in Perl:
\begin{verbatim}
  julia> "$greet, $who.\n"
  "Hello, world.\n"
\end{verbatim}
This is more readable and convenient and exactly equivalent to the above string concatenation\,---\,the system rewrites this apparent single string literal into a concatenation of string literals with variables.

The shortest complete expression after the \verb|$| is taken as the expression whose value is to be interpolated into the string.
Thus, you can interpolate any expression into a string using parentheses:
\begin{verbatim}
  julia> "1 + 2 = $(1 + 2)"
  "1 + 2 = 3"
\end{verbatim}
The expression need not be contained in parentheses, however.
For example, since a literal array expression is not complete until the opening \verb|[| is closed by a matching \verb|]|, you can interpolate an array like this:
\begin{verbatim}
  julia> x = 2; y = 3; z = 5;

  julia> "x,y,z: $[x,y,z]."
  "x,y,z: [2,3,5]."
\end{verbatim}
Both concatenation and string interpolation call the generic \verb|string| function to convert objects into \verb|String| form.
Most non-\verb|String| objects are converted to strings as they are shown in the Julia repl:
\begin{verbatim}
  julia> v = [1,2,3]
  [1,2,3]

  julia> "v: $v"
  "v: [1,2,3]"
\end{verbatim}
The \verb|string| function is the identity for \verb|String|s and \verb|Char|s values, so these are interpolated into strings as themselves, unquoted and unescaped:
\begin{verbatim}
  julia> c = 'x'
  'x'

  julia> "hi, $c"
  "hi, x"
\end{verbatim}
To include a literal \verb|$| in a string literal, escape it with a backslash:
\begin{verbatim}
  julia> println("I have \$100 in my account.");
  I have $100 in my account.
\end{verbatim}

\subsection{Common Operations}

Another useful string function is \verb|repeat|:
\begin{verbatim}
  julia> repeat(".:Z:.", 10)
  ".:Z:..:Z:..:Z:..:Z:..:Z:..:Z:..:Z:..:Z:..:Z:..:Z:."
\end{verbatim}
You can lexicographically compare strings using the standard comparison operators:
\begin{verbatim}
  julia> "abracadabra" < "xylophone"
  true

  julia> "abracadabra" == "xylophone"
  false

  julia> "Hello, world." != "Goodbye, world."
  true

  julia> "1 + 2 = 3" == "1 + 2 = $(1 + 2)"
  true
\end{verbatim}
You can search for the index of a particular character using the \verb|strchr| function:
\begin{verbatim}
  julia> strchr("xylophone", 'x')
  1

  julia> strchr("xylophone", 'p')
  5

  julia> strchr("xylophone", 'z')
  char not found
\end{verbatim}
You can start the search for a character at a given offset by providing a third argument:
\begin{verbatim}
  julia> strchr("xylophone", 'o')
  4

  julia> strchr("xylophone", 'o', 5)
  7

  julia> strchr("xylophone", 'o', 8)
  char not found
\end{verbatim}
Some other useful functions include:
\begin{itemize}
\item \verb|length(str)| gives the maximal (byte) index that can be used to index into \verb|str|.

\item \verb|strlen(str)| the number of characters in \verb|str|.
This is \emph{not} the same as \verb|length(str)|, but we do always have the identity \verb|strlen(str)| $\le$ \verb|length(str)|.

\item \verb|i = start(str)| gives the first valid index at which a character can be found in \verb|str| (typically 1).

\item \verb|c, j = next(str,i)| returns next character at or after the index \verb|i| and the next valid character index following that.
With the \verb|start| and \verb|length|, can be used to iterate through the characters in \verb|str|.

% TODO: figure this out and fix it.

\item \verb|c, j = prev(str,i)| returns the character at or before index \verb|i| and the index at which it occurs.
With \verb|length| and \verb|start| can be used to iterate through the characters in \verb|str| in reverse.

\item \verb|ind2chr(str,i)| gives the number of characters in \verb|str| up to and including any at index \verb|i|.

\item \verb|chr2int(str,j)| gives the index at which the \verb|j|th character in \verb|str| occurs.
\end{itemize}

% \subsection{String Internals}
% 
% What is the actual type and structure a string object?
% \begin{verbatim}
%   julia> dump("Hello, world.\n")
%   Latin1String(data=[104,101,108,108,111,...,119,111,114,108,100],)
% \end{verbatim}
% Standard string literals like the above always produce either a \verb|Latin1String| or a \verb|UTF8String|.
% Both of these types of strings are implemented using a byte array encoding \verb|Char| values.
% \verb|Latin1String| uses a fixed-width, single-byte encoding, while \verb|UTF8String| uses the variable-width, UTF-8 encoding.
% 
% Here are the actual declarations of the basic string types from Julia's bootstrapping code:
% \begin{verbatim}
%   abstract String
% 
%   type Latin1String <: String
%       data::Array{Uint8,1}
%   end
% 
%   type UTF8String <: String
%       data::Array{Uint8,1}
%   end
% \end{verbatim}
% \verb|String| is an abstract supertype, which is used to refer to all concrete implementations of the string interface.
% The \verb|Latin1String| and \verb|UTF8String| classes are both thin wrappers around an array of bytes (\verb|Uint8| values), holding the string's encoded data.
% The only difference is in their interpretation:
% \begin{enumerate}
% \item In a \verb|Latin1String|, bytes and characters are one-to-one, and each byte encodes its Unicode code point directly, the way classic C strings do.
% As you may have guessed, this encoding is called Latin-1.
% \item In a \verb|UTF8String|, bytes and characters are not one-to-one, but instead uses the UTF-8 encoding, which matches ASCII and Latin-1 up to \verb|0x7f|, and uses two, three of four bytes to encode Unicode characters with higher code points.
% \end{enumerate}
% How does one generate a \verb|UTF8String| object rather than a \verb|Latin1String| object?
% One does so just by using a Unicode character escape sequence above \verb|0x7f| in a string literal:
% \begin{verbatim}
%   julia> "\u2200 x \u2203 y > x"
%   "∀ x ∃ y > x"
% 
%   julia> dump(ans)
%   UTF8String(data=[226,136,128,32,120,...,121,32,62,32,120],)
% \end{verbatim}
% Also, absent other indications, external text input is assumed to be encoded as UTF-8, and therefore creates \verb|UTF8String| objects.
% String literals created in Julia without escapes, however, can be safely represented using Latin-1, which, being a fixed-width encoding, has much better performance characteristics than UTF-8.
% In particular, \verb|Latin1String|s have zero decoding overhead because each character is represented directly by its byte value.
% Therefore, Julia uses \verb|Latin1String|s internally whenever it can.
% 
% Because there are so many different ways a sequence of characters can be represented, Julia has many different string types, each with a different underlying implementation.
% Also, programmers can easily define their own new string types.
% The distinction between different string implementations is transparent to the casual observer in Julia.
% You can perform string operations with all combinations of types of strings, and they will work:
% all string functions are implemented generically in terms of a minimal core set of methods which any string must provide.
% 
% Generic implementations of string methods are often less efficient than optimal.
% Julia's dispatch system fortunately makes it simple to provide specialized, fast methods in cases where the specific representation of a string can be leveraged somehow.
% The typical user never needs to think about this:
% just call the right generic function and the work will be dispatched to the appropriate method.
% Consider, for example, comparing the lexicographic ordering of two strings:
% \begin{verbatim}
%   julia> "abracadabra" < "xylophone"
%   true
% \end{verbatim}
% There is a generic string \verb|<| method which can compare any two strings, character by character, regardless of encoding or implementation.
% In this case, however, both strings are \verb|Latin1String| objects, and a much faster method of comparison exists:
% the \verb|libc| library's \verb|memcmp| function.
% So a specialized \verb|<| method is provided to compare two \verb|Latin1String|s using this much faster method.
% The usage is completely transparent, however:
% regardless of what kinds of strings you have, you simply call \verb|a < b| to compare them.
% If \verb|memcmp| can be used, it will be;
% if not, the comparison will work, albeit not quite as quickly.
% The same trick applies to comparing a pair of \verb|UTF8String|s:
% UTF-8 is carefully designed to allow using \verb|memcmp|.
% 
% Allowing many different string representations to coexist and interoperate smoothly provides significant flexibility and power.
% For example, Julia performs string concatenation using ropes:
% \begin{verbatim}
%   julia> strcat("foo","bar")
%   "foobar"
% 
%   julia> dump(ans)
%   RopeString(head="foo",tail="bar",depth=1,length=6,)
% \end{verbatim}
% This makes concatenation, which is by far one of the most common string operations, take $\O(1)$ time rather than $O(n)$ time, as it does if a new memory buffer must be allocated and both strings copied into it.
% Another very useful operation is repeating a string:
% \begin{verbatim}
%   julia> zzz = repeat(".:Z:.", 100000);
% 
%   julia> strlen(zzz)
%   500000
% 
%   julia> zzz[end>>1-15:end>>1+16]
%   "..:Z:..:Z:..:Z:..:Z:..:Z:..:Z:.."
% \end{verbatim}
% In julia this requires very little memory because the repeat operation just creates a special kind of string:
% \begin{verbatim}
%   julia> dump(zzz)
%   RepString(string=".:Z:.",repeat=100000,)
% \end{verbatim}
% The resulting object behaves as though you had a 5MB string in memory, but does so using mod operations when indexing rather than by actually allocating 5MB.
% If you actually want to allocate all that memory, you can force Julia to do so by coercing the \verb|RepString| into a byte-backed ``C string'':
% \begin{verbatim}
%   julia> zzz = cstring(zzz);
% 
%   julia> typeof(zzz)
%   Latin1String
% \end{verbatim}

\section{Functions}\sec{functions}

In Julia, a function is an object that maps tuples of values (arguments) to tuples of values (results), or throws an exception when the arguments cannot be appropriately mapped to return values.
Julia functions are not pure mathematical functions, in the sense that functions can alter and be affected by the global state of the program.
They are also not total functions since they may fail to map an input to an output.
This may happen when dispatch fails to find an appropriate method to execute for the given function and arguments, or when a function fails to return a value because it raises an exception during its execution.

The basic syntax for defining functions in Julia is:
\begin{verbatim}
  function f(x,y)
    x + y
  end
\end{verbatim}
This syntax is similar to Matlab, but there are some significant differences:
\begin{itemize}
\item In Matlab, this definition must be saved in a file, named \verb|f.m|, whereas in Julia, this expression can appear anywhere, including at the repl prompt.
\item In Matlab, the closing \verb|end| is optional, being implied by the end of the file.
In Julia, the terminating \verb|end| is required.
\item in Matlab, this function would print the value \verb|x + y| but would not return any value, whereas in Julia, the last expression evaluated is a function's return value.
\item Expression values are never printed automatically except in the repl.
Semicolons are only required to separate expressions on the same line.
\end{itemize}
In general, while the function definition syntax is reminiscent of Matlab, the similarity is largely superficial.
Therefore, rather than continually comparing the two, in what follows, we will simply describe the behavior of functions in Julia directly.

There is a second, more terse syntax for defining a function in Julia.
The traditional function declaration syntax demonstrated above is equivalent to the following compact ``assignment form'':
\begin{verbatim}
  f(x,y) = x + y
\end{verbatim}
In the assignment form, the body of the function must be a single expression, although it can be a compound expression (see \Section{compound-expressions}).
Short, simple function definitions are common in Julia.
The short function syntax is accordingly quite idiomatic, considerably reducing both typing and visual noise.

A function is called using the traditional parenthesis syntax:
\begin{verbatim}
  julia> f(2,3)
  5
\end{verbatim}
Without parentheses, the expression \verb|f| refers to the function object, and can be passed around like any value:
\begin{verbatim}
  julia> g = f;

  julia> g(2,3)
  5
\end{verbatim}
There are two other ways that functions can be applied:
using special operator syntax for certain function names
(see \Section{operators-are-functions}), or with the \verb|apply| function:
\begin{verbatim}
  julia> apply(f,2,3)
  5
\end{verbatim}
The \verb|apply| function applies its first argument\,---\,a function object\,---\,to its remaining arguments.

\subsection{The \texttt{return} Keyword}\sec{the-return-keyword}

The value returned by a function is the value of the last expression evaluated, which, by default, is the last expression in the body of the function definition.
In the example function, \verb|f|, from the previous section this is the value of the expression \verb|x + y|.
As in C and most other imperative or functional languages, the \verb|return| keyword causes a function to return immediately, providing an expression whose value is returned: % TODO: make return value actually optional.
\begin{verbatim}
  function g(x,y)
    return x * y
    x + y
  end
\end{verbatim}
Since functions definitions can be entered into the repl, it is easy to compare these definitions:
\begin{verbatim}
  f(x,y) = x + y

  function g(x,y)
    return x * y
    x + y
  end

  julia> f(2,3)
  5

  julia> g(2,3)
  6
\end{verbatim}
Of course, in a purely linear function body like \verb|g|, the usage of \verb|return| is pointless since the expression \verb|x + y| is never evaluated and we could simply make \verb|x * y| the last expression in the function and omit the \verb|return|.
In conjunction with other control flow, however, \verb|return| is of real use.
Here, for example, is a function that computes the hypotenuse length of a right triangle with sides of length $x$ and $y$, avoiding overflow:
\begin{verbatim}
  function hypot(x,y)
      x = abs(x)
      y = abs(y)
      if x > y
          r = y/x
          return x*sqrt(1+r*r)
      end
      if y == 0
          return zero(x)
      end
      r = x/y
      return y*sqrt(1+r*r)
  end
\end{verbatim}
There are three possible points of return from this function, returning the values of three different expressions, depending on the values of $x$ and $y$.
The \verb|return| on the last line could be omitted since it is the last expression.

\subsection{Operators Are Functions}\sec{operators-are-functions}

In Julia, most operators are just functions with support for special syntax.\footnote{The exceptions are operators with special evaluation semantics like \texttt{\&\&} and \texttt{||}.
These operators cannot be functions since short-circuit evaluation (see \Section{short-circuit-evaluation}) requires that their operands are not evaluated before evaluation of the operator.}
Accordingly, you can also apply them using parenthesized argument lists, just as you would any other function:
\begin{verbatim}
  julia> 1 + 2 + 3
  6

  julia> +(1,2,3)
  6
\end{verbatim}
The infix form is exactly equivalent to the function application form\,---\,in fact the former is parsed to produce the function call internally.
This also means that you can assign and pass around operators such as \verb|+| and \verb|*| just like you would with other function values:
\begin{verbatim}
  julia> f = +;

  julia> f(1,2,3)
  6
\end{verbatim}
Under the name, \verb|f|, the function does not support infix notation, however.

% Since operators like \verb|+| are just normal Julia functions, you can add new methods for them.
% For example, the addition method for complex numbers is defined as:
% \begin{verbatim}
%   +(z::Complex, w::Complex) = Complex(z.re + w.re, z.im + w.im)
% \end{verbatim}
% For more about types like \verb|Complex|, their structure and how to define them, see \Section{types}.

\subsection{Anonymous Functions}\sec{anonymous-functions}

Functions in Julia are first-class objects:
they can be assigned to variables, called using the standard function call syntax from the variable they have been assigned to.
They can be used as arguments, and they can be returned as values.
They can also be created anonymously, without giving them a name:
\begin{verbatim}
  julia> x -> x^2 + 2x - 1
  #<function>
\end{verbatim}
This creates an unnamed function taking one argument and returning the value of the polynomial $x^2 + 2x - 1$ at that value.
The primary use for anonymous functions is passing them to functions which take other functions as arguments.
A classic example is the \verb|map| function, which applies a function to each value of an array and returns a new array containing the resulting values:
\begin{verbatim}
  julia> map(round, [1.2,3.5,1.7])
  [1.0,4.0,2.0]
\end{verbatim}
% TOOD: make sure type inference gets the right return type.
This is fine if a named function effecting the transform one wants already exists to pass as the first argument to \verb|map|.
Often, however, a ready-to-use, named function does not exist.
In these situations, the anonymous function construct allows easy creation of a single-use function object without needing a name:
\begin{verbatim}
  julia> map(x -> x^2 + 2x - 1, [1,3,-1])
  [2,14,-2]
\end{verbatim}

\subsection{Multiple Return Values}

In Julia, one returns a tuple of values to simulate returning multiple values.
However, tuples can be created and destructured without needing parentheses, thereby providing an illusion that multiple values are being returned, rather than a single tuple value.
For example, the following function returns a pair of values:
\begin{verbatim}
  function foo(a,b)
    a+b, a*b
  end
\end{verbatim}
If you call it at the repl without assigning the return value anywhere, you will see the tuple returned:
\begin{verbatim}
  julia> foo(2,3)
  (5,6)
\end{verbatim}
A typical usage of such a pair of return values, however, extracts each value into a variable.
Julia supports simple tuple ``destructuring'' that facilitates this:
\begin{verbatim}
  julia> x, y = foo(2,3);

  julia> x
  5

  julia> y
  6
\end{verbatim}
You can also return multiple values via an explicit usage of the \verb|return| keyword:
\begin{verbatim}
  function foo(a,b)
    return a+b, a*b
  end
\end{verbatim}
This has the exact same effect as the previous definition of \verb|foo|.

\subsection{Varargs Functions}

It is often convenient to be able to write functions taking an arbitrary number of arguments.
Such functions are traditionally known as ``varargs'' functions, which is short for ``\emph{var}iable number of \emph{arg}ument\emph{s}.''
You can define a varargs function by appending the last argument with ``\verb|...|'':
\begin{verbatim}
  bar(a,b,x...) = (a,b,x)
\end{verbatim}
The variables \verb|a| and \verb|b| are bound to the first two argument values as usual, and the variable \verb|x| is bound to an iterable collection of the zero or more values passed to \verb|bar| after its first two arguments:
\begin{verbatim}
  julia> bar(1,2)
  (1,2,())

  julia> bar(1,2,3)
  (1,2,(3,))

  julia> bar(1,2,3,4)
  (1,2,(3,4))

  julia> bar(1,2,3,4,5,6)
  (1,2,(3,4,5,6))
\end{verbatim}
In all these cases, \verb|x| is bound to a tuple of the trailing values passed to \verb|bar|.

On the flip side, it is often handy to ``splice'' the values contained in an iterable collection into a function call as individual arguments.
To do this, one also uses ``\verb|...|'' but in the function call instead:
\begin{verbatim}
  julia> x = (3,4)
  (3,4)

  julia> bar(1,2,x...)
  (1,2,(3,4))
\end{verbatim}
In this case a tuple of values is spliced into a varargs call precisely where the variable number of arguments go.
This need not be the case, however:
\begin{verbatim}
  julia> x = (2,3,4)
  (2,3,4)

  julia> bar(1,x...)
  (1,2,(3,4))

  julia> x = (1,2,3,4)
  (1,2,3,4)

  julia> bar(x...)
  (1,2,(3,4))
\end{verbatim}
Furthermore, the iterable object spliced into a function call need not be a tuple:
\begin{verbatim}
  julia> x = [3,4]
  [3,4]

  julia> bar(1,2,x...)
  (1,2,(3,4))

  julia> x = [1,2,3,4]
  [1,2,3,4]

  julia> bar(x...)
  (1,2,(3,4))
\end{verbatim}
Also, the function that arguments are spliced into need not be a varargs function (although it often is):
\begin{verbatim}
  baz(a,b) = a + b

  julia> args = [1,2]
  [1,2]

  julia> baz(args...)
  3

  julia> args = [1,2,3]
  [1,2,3]

  julia> baz(args...)
  no method baz(Int32,Int32,Int32)
\end{verbatim}
As you can see, if the wrong number of elements are in the spliced container, then the function call will fail, just as it would if too many arguments were given explicitly.

% NOTE: this section is good, but it is currently not true!
% we have to unpack the range object in order to do dispatch.
% furthermore, this is NOT an efficient way to sum integers in julia.
%As a final example, you can sum the values in any collection using the \verb|+| operator and splicing:
%\begin{verbatim}
%  julia> x = [1,2,3,4]
%  [1,2,3,4]
%
%  julia> +(x...)
%  10
%
%  julia> x = 1:100
%  1:100
%
%  julia> +(x...)
%  5050
%\end{verbatim}
%In this example, the range object, \verb|1:100|, is never materialized in memory as a full dense vector.
%Instead, it is a lazily computed, vector-like object.
%The definition of the \verb|+| operator with many arguments iterates over its collection of arguments, summing them into an accumulator:
%\begin{verbatim}
%  function +(a, b, c, xs...)
%      accum = a + b + c
%      for x = xs
%          accum += x
%      end
%      accum
%  end
%\end{verbatim}
%Thus, the \verb|+(x...)| call is actually quite efficient:
%the values 1 through 100 are produced lazily, one at a time, and are accumulated as they are generated by the \verb|+| function.

\subsection{Further Reading}

We should mention here that this is far from a complete picture of defining functions.
Julia has a sophisticated type system and allows multiple dispatch on argument types.
None of the examples given here provide any type annotations on their arguments, meaning that they are applicable to all types of arguments.
The type system is described in \Section{types} and defining a function in terms of methods chosen by multiple dispatch on runtime argument types is described in \Section{methods}.

\section{Control Flow}\sec{control-flow}

Julia provides a variety of control flow constructs:
\begin{itemize}
\item Compound expressions: \verb|begin| and \verb|(;)|.
\item Conditional evaluation: \verb|if|-\verb|elseif|-\verb|else| and \verb|?:| (ternary operator).
\item Short-circuit evaluation: \verb|&&|, \texttt{||} and chained comparisons.
\item Repeated evaluation: \verb|while| and \verb|for|.
\item Exception handling: \verb|try|-\verb|catch|, \verb|error| and \verb|throw|.
\item Tasks: \verb|yieldto|.
\end{itemize}
The first five control flow mechanisms are standard to high-level programming languages.
Tasks are not so standard:
they provide non-local control flow, making it possible to switch between
temporarily-suspended computations.
In fact, both exception handling and cooperative multitasking are implemented in Julia using tasks.
Everyday programming, however, requires no direct usage of tasks.

\subsection{Compound Expressions}\sec{compound-expressions}

Sometimes it is convenient to have a single expression which evaluates several subexpressions.
There are two Julia constructs that accomplish this:
\verb|begin| blocks and \verb|(;)| chains.
The value of both compound expression constructs is that of the last subexpression.
Here's an example of a \verb|begin| block:
\begin{verbatim}
  julia> z = begin
           x = 1
           y = 2
           x + y
         end
  3
\end{verbatim}
Since these are fairly small, simple expressions, they could easily be placed onto a single line, which is where the \verb|(;)| chain syntax comes in handy:
\begin{verbatim}
  julia> z = (x = 1; y = 2; x + y)
  3
\end{verbatim}
This syntax is particularly useful with the terse single-line function definition form introduced in \Section{functions}.
Although it is typical, there is no requirement that \verb|begin| be multiline or that \verb|(;)| be single-line:
\begin{verbatim}
  julia> begin x = 1; y = 2; x + y end
  3

  julia> (x = 1;
          y = 2;
          x + y)
  3
\end{verbatim}

\subsection{Conditional Evaluation}\sec{conditional-evaluation}

Conditional evaluation allows portions of code to be evaluated or not evaluated depending on the value of another expression.
Here is the anatomy of the \verb|if|-\verb|elseif|-\verb|else| conditional syntax:
\begin{verbatim}
  if x < y
    println("x is less than y")
  elseif x > y
    println("x is greater than y")
  else
    println("x is equal to y")
  end
\end{verbatim}
The semantics are just what you'd expect:
if the condition expression \verb|x < y| is \verb|true|, then the corresponding block is evaluated;
otherwise the condition expression \verb|x > y| is evaluated, and if it is \verb|true|, the corresponding block is evaluated;
if neither expression is true, the \verb|else| block is evaluated.
Here it is in action:
\begin{verbatim}
  julia> x = 1; y = 2;

  julia> if x < y
           println("x is less than y")
         elseif x > y
           println("x is greater than y")
         else
           println("x is equal to y")
         end
  x is less than y

  julia> x = 2; y = 1;

  julia> if x < y
           println("x is less than y")
         elseif x > y
           println("x is greater than y")
         else
           println("x is equal to y")
         end
  x is greater than y

  julia> x = 1; y = 1;

  julia> if x < y
           println("x is less than y")
         elseif x > y
           println("x is greater than y")
         else
           println("x is equal to y")
         end
  x is equal to y
\end{verbatim}
The \verb|elseif| and \verb|else| blocks are optional, and as many \verb|elseif| blocks as desired can be used.
The condition expressions in the \verb|if|-\verb|elseif|-\verb|else| construct are evaluated until the first one evaluates to \verb|true|, after which the associated block is evaluated, and no further condition expressions or blocks are evaluated.

Unlike C, Matlab, Perl, Python, and Ruby\,---\,but like Java, and a few other stricter, typed languages\,---\,it is an error if the value of a conditional expression is anything but \verb|true| or \verb|false|:
\begin{verbatim}
  julia> if 1
           println("true")
         end
  type error: lambda: in if, expected Bool, got Int32
\end{verbatim}
This error indicates that the conditional was of the wrong type:
\verb|Int32| rather than the required \verb|Bool|.

The so-called ``ternary operator,'' \verb|?:|, is closely related to the \verb|if|-\verb|elseif|-\verb|else| syntax, but is used where a conditional choice between single expression values is required, as opposed to conditional execution of longer blocks of code.
It gets its name from being the only operator in most languages taking three operands:
\begin{quote}
  \emph{a} \verb|?| \emph{b} \verb|:| \emph{c}
\end{quote}
The expression \emph{a}, before the \verb|?|, is a condition expression, and the ternary operation evaluates the expression \emph{b}, before the \verb|:|, if the condition \emph{a} is \verb|true| or the expression \emph{c}, after the \verb|:|, if it is \verb|false|.

The easiest way to understand this behavior is to see an example.
In the previous example, the \verb|println| call is shared by all three branches:
the only real choice is which literal string to print.
This could be written more concisely using the ternary operator.
For the sake of clarity, let's try a two-way version first:
\begin{verbatim}
  julia> x = 1; y = 2;

  julia> println(x < y ? "less than" : "not less than")
  less than

  julia> x = 1; y = 0;

  julia> println(x < y ? "less than" : "not less than")
  not less than
\end{verbatim}
If the expression \verb|x < y| is true, the entire ternary operator expression evaluates to the string \verb|"less than"| and otherwise it evaluates to the string \verb|"not less than"|.
The original three-way example requires chaining multiple uses of the ternary operator together:
\begin{verbatim}
  julia> println(x < y ? "x is less than y"    :
                 x > y ? "x is greater than y" : "x is equal to y")
  x is less than y

  julia> x = 2; y = 1;

  julia> println(x < y ? "x is less than y"    :
                 x > y ? "x is greater than y" : "x is equal to y")
  x is greater than y

  julia> x = 1; y = 1;

  julia> println(x < y ? "x is less than y"    :
                 x > y ? "x is greater than y" : "x is equal to y")
  x is equal to y
\end{verbatim}
To facilitate chaining, the operator associates from right to left.

It is significant that like \verb|if|-\verb|elseif|-\verb|else|, the expressions before and after the \verb|:| are only evaluated if the condition expression evaluates to \verb|true| or \verb|false|, respectively:
\begin{verbatim}
  v(x) = (println(x); x)

  julia> 1 < 2 ? v("yes") : v("no")
  yes
  "yes"

  julia> 1 > 2 ? v("yes") : v("no")
  no
  "no"
\end{verbatim}

\subsection{Short-Circuit Evaluation}\sec{short-circuit-evaluation}

Short-circuit evaluation is quite similar to conditional evaluation.
The behavior is found in most imperative programming languages having the \verb|&&| and \texttt{||} boolean operators:
in a series of boolean expressions connected by these operators, only the minimum number of expressions are evaluated as are necessary to determine the final boolean value of the entire chain.
Explicitly, this means that:
\begin{itemize}
  \item In the expression \emph{a} \verb|&&| \emph{b}, the subexpression \emph{b} is only evaluated if \emph{a} evaluates to \verb|false|.
  \item In the expression \emph{a} \texttt{||} \emph{b}, the subexpression \emph{b} is only evaluated if \emph{a} evaluates to \verb|true|.
\end{itemize}
The reasoning is that \emph{a} \verb|&&| \emph{b} must be \verb|false| if \emph{a} is \verb|false|, regardless of the value of \emph{b}, and likewise, the value of \emph{a} \texttt{||} \emph{b} must be true if \emph{a} is \verb|true|, regardless of the value of \emph{b}.
Both \verb|&&| and \texttt{||} associate to the right, but \verb|&&| has higher precedence than than \texttt{||} does.
It's easy to experiment with this behavior:
\begin{verbatim}
  t(x) = (println(x); true)
  f(x) = (println(x); false)

  julia> t(1) && t(2)
  1
  2
  true

  julia> t(1) && f(2)
  1
  2
  false

  julia> f(1) && t(2)
  1
  false

  julia> f(1) && f(2)
  1
  false

  julia> t(1) || t(2)
  1
  true

  julia> t(1) || f(2)
  1
  true

  julia> f(1) || t(2)
  1
  2
  true

  julia> f(1) || f(2)
  1
  2
  false
\end{verbatim}
You can easily experiment in the same way with the associativity and precedence of various combinations of \verb|&&| and \texttt{||} operators.

Just like condition expressions used in \verb|if|, \verb|elseif| or the ternary operator, the operands of \verb|&&| or \texttt{||} must be boolean values (\verb|true| or \verb|false|).
Using a non-boolean value is an error:
\begin{verbatim}
  julia> 1 && 2
  type error: lambda: in if, expected Bool, got Int32
\end{verbatim}

Chained numeric comparisons also exhibit short-circuit evaluation behavior.
Recall from \Section{numeric-comparisons} that numeric comparisons in Julia can be arbitrarily chained:
\begin{verbatim}
  julia> a = 1; b = 2; c = 3;

  julia> a < b <= c
  true
\end{verbatim}
This last expression is equivalent to the less concise:
\begin{verbatim}
  julia> a < b && b <= c
  true
\end{verbatim}
In particular, this implies that chained comparisons exhibit short-circuit behavior.
Let's see this in action:
\begin{verbatim}
  v(x) = (println(x); x)

  julia> v(1) < v(2) <= v(3)
  1
  2
  3
  true

  julia> v(1) > v(2) <= v(3)
  1
  2
  false
\end{verbatim}
% TODO: THIS IS NOT THE ACTUAL OUTPUT
The first two expressions in a comparison chain are always evaluated, since their values are required to check the first comparison, which must be checked.
Subsequent expressions, however, need not be evaluated if a comparison earlier in the chain is \verb|false|.
Note that the middle expression is only evaluated once, rather than twice as it would be if the expression were written as \verb|v(1) < v(2) && v(2) <= v(3)|.

\subsection{Repeated Evaluation}\sec{repeated-evaluation}

There are two constructs for repeated evaluation of expressions:
the \verb|while| loop and the \verb|for| loop.
Here is an example of a \verb|while| loop:
\begin{verbatim}
  julia> i = 1;

  julia> while i <= 5
           println(i)
           i += 1
         end
  1
  2
  3
  4
  5
\end{verbatim}
The \verb|while| loop evaluates the condition expression (\verb|i < n| in this case), and as long it remains \verb|true|, keeps also evaluating the body of the \verb|while| loop.
If the condition expression is \verb|false| when the \verb|while| loop is first reached, the body is never evaluated.

The \verb|for| loop makes common repeated evaluation idioms easier to write.
Since counting up and down like the above \verb|while| loop does is so common, it can be expressed more concisely with a \verb|for| loop:
\begin{verbatim}
  julia> for i = 1:5
           println(i)
         end
  1
  2
  3
  4
  5
\end{verbatim}
Here the \verb|1:5| is a \verb|Range| object, representing the sequence of numbers 1, 2, 3, 4, 5.
The \verb|for| loop iterates through these values, assigning each one in turn to the variable \verb|i|.
One rather important distinction between the previous \verb|while| loop form and the \verb|for| loop form is the scope during which the variable is visible.
If the variable \verb|i| has not been introduced in an other scope, in the \verb|for| loop form, it is visible only inside of the \verb|for| loop, and not afterwards.
You'll either need a new repl instance or a different variable name to test this:
\begin{verbatim}
  julia> for j = 1:5
           println(j)
         end
  1
  2
  3
  4
  5
  ()

  julia> j
  j not defined
\end{verbatim}
See \Section{scoping} for a detailed explanation of variable scope and how it works in Julia.

In general, the \verb|for| loop construct can iterate over all sorts of containers:
\begin{verbatim}
  julia> for i = [1,4,0]
           println(i)
         end
  1
  4
  0

  julia> for s = ["foo","bar","baz"]
           println(s)
         end
  foo
  bar
  baz
\end{verbatim}
Various types of iterable containers will be introduced and discussed in later section.

It is sometimes convenient to terminate the repetition of a \verb|while| before the test condition is falsified or stop iterating in a \verb|for| loop before the end of the iterable object is reached.
This can be accomplished with the \verb|break| keyword:
\begin{verbatim}
  julia> i = 1;

  julia> while true
           println(i) 
           if i >= 5 
             break
           end
           i += 1
         end
  1
  2
  3
  4
  5

  julia> for i = 1:1000
           println(i)               
           if i >= 5
             break
           end
         end
  1
  2
  3
  4
  5
\end{verbatim}
The above \verb|while| loop would never terminate on its own, and the \verb|for| loop would iterate up to 1000.
These loops are both exited early by using the \verb|break| keyword.

In other circumstances, it is handy to be able to stop an iteration and move on to the next one immediately.
The \verb|continue| keyword accomplishes this:
\begin{verbatim}
  julia> for i = 1:10
           if i % 3 != 0
             continue
           end
           println(i)
         end
  3
  6
  9
\end{verbatim}
This is a somewhat contrived example since we could produce the same behavior more clearly by negating the condition and placing the \verb|println| call inside the \verb|if| block.
In realistic usage there is more code to be evaluated after the \verb|continue|, and often there are multiple points from which one calls \verb|continue|.

\subsection{Exception Handling}\sec{exception-handling}

When an unexpected condition occurs, a function may be unable to return a reasonable value to its caller.
In such cases, it may be best for the exceptional condition to either terminate the program, printing a diagnostic error message, or if the programmer has provided code to handle such exceptional circumstances, allow that code to take the appropriate action.

The \verb|error| function is used to indicate that an unexpected condition has occurred which should interrupt the normal flow of control.
The built in \verb|sqrt| function returns \verb|NaN| if applied to a negative real value:\,\footnote{Applied to a negative \emph{complex} value, \texttt{sqrt} returns the complex square root: \texttt{sqrt(-1 + 0im) == 0.0 + 1.0im}.}
\begin{verbatim}
  julia> sqrt(-1)
  NaN
\end{verbatim}
Suppose we want to stop execution immediately if the square root of a negative number is taken.
To do this, we can define a fussy version of the \verb|sqrt| function that raises an error if its argument is negative:
\begin{verbatim}
  fussy_sqrt(x) = x >= 0 ? sqrt(x) : error("negative x not allowed")

  julia> fussy_sqrt(2)
  1.4142135623730951

  julia> fussy_sqrt(-1)
  negative x not allowed
\end{verbatim}
If \verb|fussy_sqrt| is called with a negative value from another function, instead of trying to continue execution of the calling function, it returns immediately, displaying the error message in the repl:
\begin{verbatim}
  function verbose_fussy_sqrt(x)
    println("before fussy_sqrt")
    r = fussy_sqrt(x)
    println("after fussy_sqrt")
    return r
  end

  julia> verbose_fussy_sqrt(2)
  before fussy_sqrt
  after fussy_sqrt
  1.4142135623730951

  julia> verbose_fussy_sqrt(-1)
  before fussy_sqrt
  negative x not allowed
\end{verbatim}
Now suppose we want to handle this circumstance rather than just giving with an error.
To catch an error, you use the \verb|try| and \verb|catch| keywords.
Here is a rather contrived example that computes the square root of the absolute value of \verb|x| by handling the error raised by \verb|fussy_sqrt|:
\begin{verbatim}
  function sqrt_abs(x)
    try
      fussy_sqrt(x)
    catch
      fussy_sqrt(-x)
    end
  end

  julia> sqrt_abs(2)
  1.4142135623730951

  julia> sqrt_abs(-2)
  1.4142135623730951
\end{verbatim}
Of course, it would be far simpler and more efficient to just return \verb|sqrt(abs(x))|.
However, this demonstrates how \verb|try| and \verb|catch| operate:
the \verb|try| block is executed initially, and the value the entire construct is the value of the last expression if no exceptions are thrown during execution;
if an exception is thrown during the evaluation of the \verb|try| block, however, execution of the \verb|try| code ceases immediately and the \verb|catch| block is evaluated instead.
If the \verb|catch| block succeeds without incident (it can in turn raise an exception, which would unwind the call stack further), the value of the entire \verb|try|-\verb|catch| construct is that of the last expression in the \verb|catch| block.

% TODO: catch with and argument.

% The use of \verb|error| to indicate an ``uncontinuable'' unexpected condition, and \verb|try|-\verb|catch| to handle such errors gracefully saves programmers from spending half of their time and effort checking for errors.
% It is not uncommon for well-written C programs to devote as much code to checking for errors as it does to performing useful work.
% Virtually all modern programming languages have facilities for raising and catching exceptions.

\subsection{Tasks}\sec{tasks}

Tasks are a control flow feature that allows computations to be suspended
and resumed in a flexible manner. This feature is sometimes called by other
names, such as symmetric coroutines, lightweight threads,
cooperative multitasking, or one-shot continuations.

When a piece of computing work (in practice, executing a particular function)
is designated as a \verb|Task|, it becomes possible to interrupt it by
switching to another \verb|Task|. The original \verb|Task| can later be
resumed, at which point it will pick up right where it left off. At first,
this may seem similar to a function call. However there are two key
differences. First, switching tasks does not use any space, so any number
of task switches can occur without consuming the call stack. Second, you
may switch among tasks in any order, unlike function calls, where the called
function must finish executing before control returns to the calling
function.

This kind of control flow can make it much easier to solve certain problems.
In some problems, the various pieces of required work are not naturally
related by function calls; there is no obvious ``caller''
or ``callee'' among the jobs that need to be done. An example is the
producer-consumer problem, where one complex procedure is generating values
and another complex procedure is consuming them. The consumer cannot simply
call a producer function to get a value, because the producer may have
more values to generate and so might not yet be ready to return. With
\verb|Task|s, the producer and consumer can both run as long as they need to,
passing values back and forth as necessary.

\section{Variables}

Until now, we have used variables without any explanation.
Julia's usage of variables closely resembles that of other dynamic languages, so we have hopefully gotten away with this liberty.
In this section, we correct this oversight and provide details of how variables are used, declared, and scoped in Julia.

\subsection{Scoping}\sec{scoping}

The \emph{scope} of a variable is the region of code within which a variable
is visible.
Variable scoping helps avoid variable naming conflicts.
The concept is intuitive:
two functions can both have arguments called \verb|x| without the two \verb|x|'s referring to the same thing.
Similarly there are many other cases where different blocks of code can use the same name without referring to the same thing.
The rules for when the same variable name does or doesn't refer to the same thing are called scope rules;
this section spells them out in detail.

Certain constructs in the language introduce \emph{scope blocks}, which
are regions of code that are eligible to be the scope of some set of variables.
The scope of a variable cannot be an arbitrary set of
source lines, but will always line up with one of these blocks. These
constructs introducing such blocks are:
\begin{itemize}
\item function bodies (any syntax)
\item \verb|while| loops
\item \verb|for| loops
\item \verb|try| blocks
\item \verb|catch| blocks
\item \verb|let| blocks
\item \verb|type| blocks.
\end{itemize}
Certain constructs introduce new variables into the current innermost scope. When
a variable is introduced into a scope, it is also inherited by all inner
scopes unless one of those inner scopes explicitly overrides it. These
constructs which introduce new variables into the current scope are as follows:
\begin{itemize}
\item A declaration \verb|local x| introduces a new local variable.
\item A declaration \verb|global x| makes \verb|x| in the current scope
and inner scopes refer to the global variable of that name.
\item A function's arguments are introduced as new local variables into the
function's body scope.
\item An assignment \verb|x = y| introduces a new local variable \verb|x|
only if \verb|x| is neither declared global nor explicitly introduced as local
by any enclosing scope, before or \emph{after} the current line of code.
\end{itemize}
In the following example, there is only one \verb|x| assigned both inside
and outside a loop:
\begin{verbatim}
  function foo(n)
      x = 0
      for i = 1:n
          x = x + 1
      end
      x
  end
  
  julia> foo(10)
  10
\end{verbatim}
In the next example, the loop has a separate \verb|x| and the function
always returns zero:
\begin{verbatim}
  function foo(n)
      x = 0
      for i = 1:n
          local x
          x = i
      end
      x
  end

  julia> foo(10)
  0
\end{verbatim}
In this example, an \verb|x| exists only inside the loop, and
the function encounters an undefined variable error on its last line
(unless there is a global variable \verb|x|):
\begin{verbatim}
  function foo(n)
      for i = 1:n
          x = i
      end
      x
  end

  julia> foo(10)
  in foo: x not defined
\end{verbatim}
A variable that is not assigned to or otherwise introduced locally defaults to global,
so this function would return the value of the global \verb|x|
if there is such a variable, or produce an error if no such global exists.
As a consequence, the only way to assign to a global variable inside
a non-top-level scope is to explicitly declare the variable as global within some scope, since
otherwise the assignment would introduce a new local rather than assigning to the global. This rule works out
well in practice, since the vast majority of variables assigned inside
functions are intended to be local variables, and using global variables, should be the exception rather than the rule, especially assigning new values to them.

One last example shows that an outer assignment introducing \verb|x| need not come before an inner usage:
\begin{verbatim}
  function foo(n)
      f = y -> n + x + y
      x = 1
      f(2)
  end

  julia> foo(10)
  13
\end{verbatim}
This last example may seem slightly odd for a normal variable, but allows for named functions\,---\,which are just normal variables holding function objects\,---\,to be used before they are defined.
This allows functions to be defined in whatever order is intuitive and convenient, rather than forcing bottom up ordering or requiring forward declarations, both of which one typically sees in C programs.
As an example, here is an inefficient, mutually recursive way to test if positive integers are even or odd:\,\footnote{Julia provides built-in, efficient functions to test this called \texttt{iseven} and \texttt{isodd}.}
\begin{verbatim}
  even(n) = n == 0 ? true  :  odd(n-1)
  odd(n)  = n == 0 ? false : even(n-1)

  julia> even(3)
  false

  julia> odd(3)
  true
\end{verbatim}
Since functions can be used before they are defined, as long as they are defined by the time they are actually called, no syntax for forward declarations is necessary, and definitions can be ordered arbitrarily.

At the interactive prompt, variable scope works the same way as anywhere
else. The prompt behaves as if there is scope block wrapped around everything
you type, except that this scope block is identified with the global scope.
This is especially apparent in the case of assignments:
\begin{verbatim}
  julia> for i = 1:1; y = 10; end
  
  julia> y
  y not defined
  
  julia> y = 0
  0
  
  julia> for i = 1:1; y = 10; end
  
  julia> y
  10
\end{verbatim}
In the former case, \verb|y| only exists inside of the \verb|for| loop.
In the latter case, an outer \verb|y| has been introduced and so is inherited
within the loop. Due to the special identification of the prompt's scope
block with the global scope, it is not necessary to declare
\verb|global y| inside the loop. However, in code not entered into the interactive prompt
this declaration would be necessary in order to modify a global variable.

\section{Types}\sec{types}

Type systems have traditionally fallen into two quite different camps:
static type systems, where every value must have a fully specified type, computable before the execution of a program, and dynamic type systems, where nothing is known about types of values flowing through a piece of code until run-time, when the values themselves are available.
Object orientation and generic programming allow some flexibility in statically type languages by letting code be written without the precise type of values being known at compile time.
This ability to write code that can operate on different types is called polymorphism.
In stark contrast, all code in classical dynamically typed languages is polymorphic:
only by explicitly checking types, or when objects fail to support operations at run-time, are the types of any values ever restricted.

Julia's type system strikes a balance between dynamic typing and static typing.
Fundamentally, the type system is dynamic, but it is possible to indicate that certain values are of specific types.
More importantly, it is possible to perform method dispatch on the types of function arguments.
Method dispatch is explored in detail in \Section{methods}, but is rooted in the type system presented here.
The default behavior in Julia when types are omitted is always classical dynamic behavior:
a program without type annotations is dynamically typed code.
Thus, one can write many useful Julia programs without ever explicitly using types, but when additional expressiveness is needed, it is easy to gradually introduce explicit type annotations into previously ``untyped'' code.
Doing so will typically increase both the performance and robustness of these systems, and counterintuitively, often significantly simplify them.

Describing Julia's type system in the lingo of types, it is dynamic, nominative, parametric and dependent.
Generic types can be parameterized by other types and integers, and the relationships between types in the hierarchy is explicitly declared, rather than implied by compatible structure.
Parametric typing allows concisely and elegantly defining and talking about a type like \verb|List|, without caring or specifying what type of objects the list holds\,---\,for many list algorithms, the type of values is unimportant.
In situations where the type of objects contained in a list is significant, one can simply write \verb|List{Int32}|, for example, to specify that a list contains only 32-bit integers.
Concrete types may not subtype each other, so all actual types of run-time values are never interchangeable without conversion.
Thus, the type system is nominative:
an \verb|Int32| may not be used as a \verb|Char|, even though they have the same 32-bit integer structure.

High-level aspects of Julia's type system that should be mentioned up front are:
\begin{itemize}

\item Like traditional dynamically typed languages, but unlike statically typed languages like C or Java, only values, not variables, have types.
There is no meaningful concept of the compile-time type of anything:
the only type of a value is its actual type when the program is running.

\item Variables have no type: they are simply names bound to values.
Although type annotations can restrict the possible types of a value, the variable mentioned can be re-bound to values of any type.

\item There is no distinction between object and non-object types:
all values in Julia are true objects having a type that belongs to the single, fully connected type graph.

\item There is no structural inheritance:
all concrete types, specifying an actual, instantiable implementation of a type are final and may not be inherited from or subclassed by other concrete types.

\item The type graph is not flat:
all other nodes in the type graph are abstract, however\,---\,they serve only to describe various subsets of concrete types.
Every type is a subtype of the abstract type called \verb|Any|.%
\footnote{In type theory, the abstract type, \texttt{Any}, of which all objects are instances, and all types are subtypes, is called ``top'' because it is at the apex of the type graph.
Julia also has a ``bottom'' type, called \texttt{None}, another abstract type, of which no object is an instance, and of which all other types are supertypes;
thus it is at the nadir of the type graph.}

\item Julia types\,---\,both concrete and abstract\,---\,can be paramaterized by other types or integers.
This allows algorithms to be written generically and reused without repetition.
Type parameters may be completely omitted when they do not need to be referenced explicitly.

% TODO: no multiple inheritance yet
%\item Julia supports multiple inheritance:
%a type may declare that it is a subtype of several abstract types.
%% Thus, the type hierarchy is a directed, acyclic graph rather than a tree.
%The absence of implementation inheritance eliminates data representation problems classically encountered in the presence of multiple inheritance.%
%\footnote{The other problems classically caused by multiple inheritance are ambiguities and instabilities in method dispatch introduced when different methods of the same function are dispatched on non-disjoint types, sharing common descendant subtypes.
%These problems are prevented by a straightforward rule described in \Section{dispatch-and-inheritance}.}

\end{itemize}
The Julia type system is designed to be powerful and expressive, yet clear, intuitive and unobtrusive.
Many Julia programmers may never feel the need to write code that explicitly uses types.
However, some kinds of programming becomes easier, faster and more robust with judicious use of explicit types.

\subsection{Bits Types}\sec{bits-types}

A bits type is a concrete type whose data consists of plain old bits.
Classic examples of bits types are integers and floating point values.
Unlike most languages, Julia lets you declare bits types, rather than providing only a fixed set of built-in bits types.
In fact, the standard bits types are all defined in the language itself:
\begin{verbatim}
  bitstype 8 Bool

  bitstype 8  Int8  <: Int
  bitstype 16 Int16 <: Int
  bitstype 32 Int32 <: Int
  bitstype 64 Int64 <: Int

  bitstype 8  Uint8  <: Uint
  bitstype 16 Uint16 <: Uint
  bitstype 32 Uint32 <: Uint
  bitstype 64 Uint64 <: Uint
  bitstype 32 Char   <: Uint

  bitstype 32 Float32 <: Float
  bitstype 64 Float64 <: Float
\end{verbatim}
The general syntax of a bitstype declaration is
\begin{quote}
  \verb|bitstype| \placeholder{bits} \placeholder{name} [~\verb|<:| \placeholder{supertype}\:[\verb|,|\,\placeholder{supertype}\,]$^+$\,]
\end{quote}
The number of bits indicates how much storage the type requires and the name gives the new type a name.
A bits type can optionally be declared to be a subtype of one or more supertypes.
The \verb|<:| operator means ``is a subtype of,'' and, used in declarations like this, declares the right-hand types to be immediate supertypes of the newly declared type.
If supertypes are omitted, then the type defaults to having \verb|Any| as its immediate supertype.
The declaration of \verb|Bool| above therefore means that a boolean value takes eight bits to store, and has \verb|Any| as its only supertype.

Currently, only sizes of 8, 16, 32, and 64 bits are supported.
Therefore, boolean values, although they really need just a single bit, cannot be declared to be any smaller then eight bits.

The types \verb|Bool|, \verb|Int8| and \verb|Uint8| all have identical representations:
they are eight-bit chunks of memory.
Since Julia's type system is nominative, they are not interchangeable despite having the same structure.
Another fundamental difference between them is that they have different supertypes:
\verb|Bool|'s direct supertype is \verb|Any|, \verb|Int8|'s is \verb|Int|, and \verb|Uint8|'s is \verb|Uint|.
Concrete types cannot be subtyped in Julia, so \verb|Any|, \verb|Int|, and \verb|Uint| must be abstract types, to be introduced in the next section (\Section{abstract-types}).
All other differences between \verb|Bool|, \verb|Int8|, and \verb|Uint8| are matters of behavior---
the way functions are defined to act when given objects of these types as arguments.
The necessity of a nominative type system becomes apparent from this:
otherwise, it would be impossible to make \verb|Bool| behave any differently than \verb|Int8| or \verb|Uint8|.

\subsection{Abstract Types}\sec{abstract-types}

Abstract types cannot be instantiated.
Rather, they are nodes in the type graph describing sets of related concrete types:
all those concrete types which are subtypes of the abstract type in question.

Recall that in \Section{numbers-and-arithmetic}, we introduced a variety of types of numeric values:
\verb|Int8|, \verb|Uint8|, \verb|Int16|, \verb|Uint16|, \verb|Int32|, \verb|Uint32|, \verb|Int64|, \verb|Uint64|, \verb|Float32|, and \verb|Float64|.
It is common for a piece of code to make sense only if its arguments are some kind of integers, but not really depend on what particular \emph{kind} of integers, as long as the right low-level operations are used.
For example, the greatest common denominator algorithm works for all kinds of integers, but will not work for floating point numbers.
Abstract types allow you to easily talk about any type that is an integer, without restricting an algorithm to any specific integer type.

As an example, let's consider the actual declaration of the abstract type hierarchy for Julia's integer and floating point types, all bits types whose declarations were given in \Section{bits-types}.
The abstract types in this part of the type hierarchy are declared using the \verb|abstract| keyword:
\begin{verbatim}
  abstract Number
  abstract Real  <: Number
  abstract Int   <: Real
  abstract Uint  <: Int
  abstract Float <: Real
\end{verbatim}
The \verb|abstract| keyword introduces a new abstract type, and like the \verb|bitstype| declaration, can be optionally followed by supertypes, indicating that the newly declared abstract type is a subtype of those other types.
Again, if no supertype is given, the default supertype is \verb|Any|.
In the above declarations, each type has exactly one supertype.
These declarations imply the following type hierarchy for integers and floats:
\begin{center}
\begin{tikzpicture}[>=latex,line join=bevel,font=\small\tt,scale=0.45]
\input{ints_and_floats}
\end{tikzpicture}
\end{center}
The bottom row of types are concrete bits types, while the types above are all abstract types, dividing and subdividing the concrete types into convenient classes.
This diagram is incomplete:
there are other subtypes of both \verb|Number| and \verb|Real|, which will be introduced in \Section{parametric-types}.

\subsection{Record Types}\sec{record-types}

Record types are called records, structures (``structs'' in C), or objects in various languages.
They are types whose values are a collection of named fields which can be used as a single composite value.
In mainstream object oriented languages, such as C++ and Java, record types also have named functions associated with them, and the combination is called an ``object.''
In purer object-oriented languages, such as Smalltalk or Ruby, all values are objects and need not be records, but functions are still bundled with objects and called methods.
In Julia, functions are not bundled with the objects they operate on;
they are dispatched on all of their arguments, so associating a method with any particular argument is inappropriate.
See \Section{methods} for details of Julia's dispatch mechanism.

Since record types are the most common form of concrete type, they are simply introduced with the \verb|type| keyword followed by a block listing field names.
The fields have optional type annotations indicated with the \verb|::| operator followed by a type value.
Fields with no type annotation default to \verb|Any|, and can accordingly hold any type of value.
Here's an example declaration for the \verb|Foo| record type:
\begin{verbatim}
  type Foo
    bar::Int32
    baz::Float64
  end
\end{verbatim}
The new type, \verb|Foo|, declared here, is a first-class Julia object:
you can manipulate it like any other value.
In addition to being a type value, \verb|Foo| also acts like a function\,---\,one that constructs new \verb|Foo| objects from the pieces that make up a \verb|Foo|:
\begin{verbatim}
  julia> foo = Foo(2,1.5)
  Foo(2,1.5)

  julia> typeof(foo)
  Foo

  julia> foo.bar
  2

  julia> foo.baz
  1.5
\end{verbatim}
As you can see, the fields of a \verb|Foo| object like \verb|foo| are accessed using conventional dot (``\verb|.|'') notation.
Let's see what happens if you try to construct a \verb|Foo| object with \verb|bar| and \verb|baz| values of the wrong type:
\begin{verbatim}
  julia> ok = Foo(1.5,2.5)
  Foo(1,2.5)

  julia> bad = Foo(1,"hello")
  cannot convert "hello" to Float64
\end{verbatim}
The constructor automatically tries to convert values to the appropriate types if it can by calling the \verb|convert| function on them.
By default, Julia knows how to convert many values to other types and new conversions are easily defined by adding new methods to \verb|convert| (see \Section{conversion-and-promotion}).
Floating point values are converted to integers by truncation so here the value \verb|ok| created has \verb|ok.bar == 1|.
On the other hand, there is no built in conversion from string values to floating point, so the construction of \verb|bad| fails.

The declaration block of new record types can also include explicitly declared constructor methods for the type.
Let's say we want to be able construct \verb|Foo| values passing a float into the \verb|bar| position, but instead of truncating the value, we want to round to the nearest integer.
To do this, we would change the declaration of \verb|Foo| to include an explicit constructor method:
\begin{verbatim}
  type Foo
    bar::Int32
    baz::Float64

    Foo(bar, baz) = new(round(bar), baz)
  end
\end{verbatim}
Inside of a \verb|type| block, the variable \verb|new| is bound to the raw constructor function for the type being declared:
it takes an argument for each field and constructs a new object by setting the fields to those values, converting values to the appropriate types as necessary, and failing if no conversion exists.
In the absence of any explicit constructors, the \verb|new| function is externally exposed as the default constructor for a type.
When constructor methods \emph{are} provided, the \verb|new| function is not exposed and since \verb|new| is only visible within the scope of the \verb|type| block, the type declaration controls all the ways to make a new object of that type.

Using this new definition of \verb|Foo|, we can try constructing some \verb|Foo| objects again:
\begin{verbatim}
  julia> Foo(1,2.5)
  Foo(1,2.5)

  julia> Foo(1.5,2.5)
  Foo(2,2.5)

  julia> Foo("hello",2.5)
  no method round(Latin1String,)

  julia> Foo(1,"world")
  cannot convert "world" to Float64
\end{verbatim}
The new explicit constructor for \verb|Foo| objects always calls \verb|round| on its first argument:
in the first usage of the \verb|Foo| constructor, \verb|1| is unaltered by the \verb|round| function, while in the second, \verb|1.5| is rounded to \verb|2.0|, which is in turn converted to the \verb|Int32| value, \verb|2|, and assigned into the \verb|bar| slot of a new \verb|Foo| object.
In the third usage, the constructor attempts to call \verb|round| on the string \verb|"hello"|, but there is no \verb|round| method for strings.
In the last case, the second argument cannot be converted from string to floating point, just as before.

\Section{methods} introduces methods, allowing functions to be defined in terms of different behaviors for different types of arguments.
This is useful for defining behaviors of type constructors on arguments of various types:
when used as a function to construct \verb|Foo| objects, \verb|Foo| is just like any other function, and can have as many different methods defined on it as are necessary to specify its overall behavior.

One final note:
record types, like all other types, can be declared to have one or more abstract supertypes.
These are optionally listed following the \verb|<:| operator after the name of the new type:
\begin{verbatim}
  abstract Fooish

  type Foo <: Fooish
    bar::Int32
    baz::Float64

    Foo(bar, baz) = new(round(bar), baz)
  end
\end{verbatim}
In the absence of such declarations, the default supertype is \verb|Any|.
In the above example, \verb|Fooish| is a subtype of \verb|Any| and \verb|Foo| is a subtype of \verb|Fooish|.
This would be of little use if \verb|Foo| were the only concrete subtype of \verb|Fooish|, since there's only one choice of implementation for the \verb|Fooish| abstraction.
However, we can define an alternate implementation of the \verb|Fooish| type now:
\begin{verbatim}
  type AltFoo <: Fooish
    mrt::String
  end
\end{verbatim}
This new type, \verb|AltFoo|, has a completely different implementation than \verb|Foo|, but yet is also a type of \verb|Fooish|.
Thus, either \verb|Foo| or \verb|AltFoo| objects can be used when a \verb|Fooish| type of object is needed.
To make this useful, of course, \verb|Foo| and \verb|AltFoo| need to implement some common interfaces, and generic \verb|Fooish| behavior should be defined in terms of the \verb|Fooish| abstraction.

\subsection{Parametric Types}\sec{parametric-types}

\subsection{Other Kinds of Types}\sec{other-kinds-of-types}

\subsection{Conversion and Promotion}\sec{conversion-and-promotion}

\subsection{Summary of Numeric Types}

\begin{center}
\begin{tikzpicture}[>=latex,line join=bevel,font=\small\tt,scale=0.45]
\input{numbers}
\end{tikzpicture}
\end{center}

% \subsection{Tag Types}
% \subsection{Struct Types}
% 
% Julia comes with pre-defined rational and complex numeric types, but they are just defined in the language in terms of the more basic numeric types given above using the standard facility for defining new types. For example, the declaration of the \verb|Rational| type is the following:
% \begin{verbatim}
%   struct Rational{T<:Int} <: Real
%     num::T
%     den::T
%   end
% \end{verbatim}
% A few facts are in order before you can understand this declaration:
% \begin{itemize}
% \item A \verb|struct| type is a named bundle of fields as in the C language. In this case the fields are \verb|num| and \verb|den| which are used to store the numerator and the denominator, respectively, of a rational number.
% \item The \verb|Rational{T}| syntax is used for parametric types. This declaration defines \verb|Rational| with respect to a type parameter, \verb|T|.
% \item The \verb|<:| operator asserts that the value on the left is a subtype of the value on the right. In this case it is used twice:
%   \begin{itemize}
%     \item to assert that the type parameter, \verb|T|, is a subtype of \verb|Int|, which includes all of the above integer types;
%     \item to assert that \verb|Rational| itself is a subtype of \verb|Real|, which includes the integer and floating-point types as well.
%   \end{itemize}
% \item The \verb|::| operator asserts that the name on the left will be bound to a value of the type on the right. Thus whatever type parameter \verb|T| is given as, the numerator and denominator of the rational number are of that type.
% \end{itemize}
% This is all somewhat complicated, but the result is easy to use:
% \begin{verbatim}
%   julia> Rational(1,2)
%   1//2
% 
%   julia> typeof(ans)
%   Rational{Int32}
% \end{verbatim}
% Applying the \verb|Rational| type to a pair of values (1,2) creates a \verb|Rational|. The output notation 1//2 is also acceptable as input notation:
% \begin{verbatim}
%   julia> 1//2
%   1//2
% \end{verbatim}
% Despite being effectively user-defined types, \verb|Rational| values interoperate completely with other numeric types:
% \begin{verbatim}
%   julia> 1//2 + 2
%   5//2
% 
%   julia> 1//2 + 1.5
%   2.0
% \end{verbatim}
% If you want to create an ``exotic'' rational object of a type like \verb|Rational{Uint8}| all you need to do is use \verb|Uint8| values to construct them:
% \begin{verbatim}
%   julia> uint8(123)//uint8(234)
%   41//78
% 
%   julia> typeof(ans)
%   Rational{Uint8}
% \end{verbatim}
% If you use mixed types to construct a \verb|Rational|, the same promotions that are used for arithmetic apply:
% \begin{verbatim}
%   julia> uint8(123)//int8(-12)
%   -41//4
% 
%   julia> typeof(ans)
%   Rational{Int16}
% \end{verbatim}
% 
% \subsection{Struct Constructors}\sec{struct-constructors}
% 
% \subsection{Bits Types}
% 
% \subsection{Conversion and Promotion}\sec{conversion-and-promotion}
% 
% \subsection{Other Kinds of Types}

\section{Methods}\sec{methods}

Recall from \Section{functions} that a function is an object that maps a tuple of arguments to a tuple of return values, or throws an exception if no appropriate values can be returned.
It is quite common for a function to behave quite differently for different types of arguments.
In terms of implementation, adding two integers is a very different operation than adding two floating point numbers, both of which are quite different from adding an integer to a floating point number.
Despite their implementations differences, these operations all fall under the general concept of ``addition.''
Accordingly, in Julia, these behaviors belong to a single generic function object: the \verb|+| function.

Since different implementations are required for different types of arguments, it is convenient to be able to choose a specific behavior based on the number and types of arguments.
This choice is called dispatch.
The individual behaviors that are chosen between are called \emph{methods}, and each function can have many different methods, each specialized for different types of argument values.
Together, all of a function's various methods define how the function behaves for all possible tuples of argument values.
Until now, we have defined only functions with a single method that handles all argument types.

Julia allows the dispatch process to choose which of a function's methods to call based on the types of all of a function's arguments.
This is different than typical object-oriented languages, where dispatch occurs based only on the first argument, which often has a special argument syntax, and is sometimes implied rather than explicitly given as an argument.
Using all of a function's arguments to choose which method should be invoked, rather than just the first, is known as \emph{multiple dispatch}.
Multiple dispatch is particularly useful for mathematical operations, where it makes little sense to artificially deem the operations to ``belong'' to one argument more than any of the others.
Does the addition operation in \verb|x + y| belong to \verb|x| any more than it does to \verb|y|?
The implementation of mathematical operations usually depends on all arguments.

The \verb|::| operator is used after the name of a function parameter in a method declaration to describe what types of values the method should be used for:
\begin{verbatim}
  f(x,y) = x + y
  f(x::Float64, y::Float64) = x * y
\end{verbatim}
In the absence of a type declaration with \verb|::|, the type of an argument is \verb|Any| by default, so any value will match the method signature.
Thus, the above two lines define two methods for the generic function, \verb|f|:
one which applies to any pair of values, and one which applies only to a pair of \verb|Float64| values.
When a function is applied to actual arguments, the most specific method applicable to the arguments given is used:
\begin{verbatim}
  julia> f(2,3)
  5

  julia> f(2.0,3.0)
  6.0
\end{verbatim}
The most specific method that applies to the given arguments is called.
The \verb|f(Float64,Float64)| method cannot be applied to the arguments \verb|2,3| because \verb|2| and \verb|3| are of type \verb|Int32|, not \verb|Float64|.
This method does apply to the arguments \verb|2.0,3.0|, however, since they are both \verb|Float64| values.
All arguments types must match for a method to be applicable:
\begin{verbatim}
  julia> f(2,3.0)
  5.0
\end{verbatim}
Here, the \verb|Float64| method of \verb|f| cannot be applied since 2 is not a \verb|Float64|.
In the first method, the argument types are unconstrained, so this serves as a catchall method, and is called here.

If you've been entering these definitions in the repl, you'll have noticed that it shows you all the methods defined for a given generic function when a new method is defined:
\begin{verbatim}
  julia> f(x,y) = x + y
  Methods for generic function f
  f(Any,Any)

  julia> f(x::Float64, y::Float64) = x * y
  Methods for generic function f
  f(Float64,Float64)
  f(Any,Any)

  julia> f
  Methods for generic function f
  f(Float64,Float64)
  f(Any,Any)
\end{verbatim}

Although it seems a simple concept, multiple dispatch on the types of values is perhaps the single most powerful and central feature of the Julia language.
Core operations typically have dozens of methods:
\begin{verbatim}
  julia> +
  Methods for generic function +
  +(Real,Range{T<:Real})
  +(Real,Range1{T<:Real})
  +(Union(Range{T<:Real},Range1{T<:Real}),Real)
  +(Union(Range{T<:Real},Range1{T<:Real}),
    Union(Range{T<:Real},Range1{T<:Real}))
  +()
  +(Number,)
  +(Any,Any,Any)
  +(Any,Any,Any,Any)
  +(Any,Any,Any,Any,Any)
  +(Any,Any,Any,Any...)
  +(Int8,Int8)
  +(Int16,Int16)
  +(Int32,Int32)
  +(Int64,Int64)
  +(Uint8,Uint8)
  +(Uint16,Uint16)
  +(Uint32,Uint32)
  +(Uint64,Uint64)
  +(Float32,Float32)
  +(Float64,Float64)
  +(Char,Char)
  +(Rational{T<:Int},Rational{T<:Int})
  +(Complex{T<:Real},Complex{T<:Real})
  +(T<:Number,T<:Number)
  +(Number,Number)
  +(Tensor{T<:Number,N},)
  +(Tensor{S,N},Tensor{T,N})
  +(Number,Tensor{T,N})
  +(Tensor{T,N},Number)
\end{verbatim}
Multiple dispatch together with the flexible parametric type system, give Julia its ability to abstractly express high-level algorithms decoupled from implementation details, yet generate efficient specialized code at run time.

\subsection{Method Ambiguities}\sec{method-ambiguities}

It is possible to define a set of function methods such that there is no
unique most specific method applicable to some combinations of arguments:
\begin{verbatim}
  julia> f(x,y) = x + y
  Methods for generic function f
  f(Any,Any)

  julia> f(x::Float64, y) = 2x + y
  Methods for generic function f
  f(Float64,Any)
  f(Any,Any)

  julia> f(x, y::Float64) = x + 2y
  Warning: new definition f(Any,Float64) is ambiguous with
  f(Float64,Any). Make sure f(Float64,Float64) is also defined.
  Methods for generic function f
  f(Float64,Any)
  f(Any,Float64)
  f(Any,Any)

  julia> f(2,3)
  5

  julia> f(2.0,3)
  7.0

  julia> f(2,3.0)
  8.0

  julia> f(2.0,3.0)
  7.0
\end{verbatim}
Here the arguments \verb|2.0| and \verb|3.0| could be handled by either the \verb|f(Float64,Any)| or the \verb|f(Any,Float64)| method, and neither is more specific than the other.
In such cases, Julia warns you about this ambiguity, but allows you to proceed, arbitrarily picking a method.
You should avoid method ambiguities by specifying an appropriate method for the intersection case:
\begin{verbatim}
  julia> f(x,y) = x + y
  Methods for generic function f
  f(Any,Any)

  julia> f(x::Float64, y::Float64) = 2x + 2y
  Methods for generic function f
  f(Float64,Float64)
  f(Any,Any)

  julia> f(x::Float64, y) = 2x + y
  Methods for generic function f
  f(Float64,Float64)
  f(Float64,Any)
  f(Any,Any)

  julia> f(x, y::Float64) = x + 2y
  Methods for generic function f
  f(Float64,Float64)
  f(Float64,Any)
  f(Any,Float64)
  f(Any,Any)

  julia> f(2,3)
  5

  julia> f(2.0,3)
  7.0

  julia> f(2,3.0)
  8.0

  julia> f(2.0,3.0)
  10.0
\end{verbatim}
To suppress Julia's warning, the disambiguating method must be defined first.

\subsection{Dispatch and Inheritance}\sec{dispatch-and-inheritance}

% \section{Tensors and Comprehensions}
% 
% Julia introduces a new programming construct called a multidimensional
% array comprehension or just an array comprehension for short. Array
% comprehensions are similar to the notion of list comprehensions in
% other languages such as Python, Haskell and OCaml, but extend this
% notion to manipulate and generate arrays of arbitrary dimension. Each
% dummy variable used in the array comprehension corresponds to a
% dimension of the output array; if the comprehension expression value
% itself has non-zero dimension then the total dimension of the output
% is the number of dummy variables plus the dimension of the value. If
% we view n-d arrays as rank-n tensors, and thus see 1-d arrays as
% vectors and 2-d arrays as matrices, many common vector, matrix and
% tensor operations can be expressed concisely and clearly using array
% comprehensions.
% 
% Array comprehensions are envisioned to be a key construct of the julia
% language that will differentiate it from other languages. On one hand,
% Matlab is pretty fast, and it is almost impossible to beat Matlab at
% what it does. On the other hand, Matlab codes when rewritten in C
% often run 10 times faster. What gives? The key idea behind array
% comprehensions is to express almost all operations at a higher level,
% close to their mathematical definitions. Optimizations can then be
% applied to this high level to produce heavily optimized low-level
% code, for multiple comprehensions and compounded comprehensions. This
% scheme should allow the generation of optimized low-level code from a
% high level specification that matches the structure of optimized C
% code written by a good C programmer.
% 
% \subsection{Array Comprehension Notations}
% 
% The following sections give three increasingly succinct syntaxes for writing array comprehensions. Through the forms, we follow the basic example of how to express the row sum and column sums of a matrix. We first present the most general, verbose notation for array comprehensions together with its meaning, and then present two increasingly abbreviated but equivalent forms.
% 
% \subsubsection{Explicit range}
% This is the most general form for writing array comprehensions. The general form is:
% \begin{verbatim}
% A = [ F(x,y,...) | x=rx, y=ry, ... ]
% \end{verbatim}
% 
% The meaning of this form is that F(x,y,...) is evaluated with the
% variables x, y, etc. taking on each value in their given list of
% values. Values can be specified as any iterable object, but will
% commonly be ranges like 1:n or 2:(n-1), or explicit arrays of values
% like [1.2, 3.4, 5.7]. The result is a tensor object with dimensions
% that are the concatenation of the dimensions of the dummy variable
% ranges rx, ry, etc. and the dimension of the result of each F(x,y,...)
% evaluations—which must all have identical shape. See below for details
% on array comprehensions of non-scalar expression.
% 
% To clarify, let's consider the concrete example of computing row and
% column sums of a matrix, A. For a single dummy variable, the array
% comprehension notation with explicit variable ranges is similar to
% list comprehensions in other languages:
% \begin{verbatim}
% row_sums = [ sum(A[i,:]) | i=1:size(A,1) ]
% col_sums = [ sum(A[:,j]) | j=1:size(A,2) ]
% \end{verbatim}
% 
% \subsection{Array Comprehensions of Non-Scalar Expressions}
% If the computed expression of an array comprehension is not a scalar,
% then all the values produced must be arrays of identical shape. The
% dummy variable vectorization dimensions come before the expression
% dimensions making the total dimension of the output array the number
% of dummy variables plus the dimension of the inner expression. This
% convention can be expressed by the following identity. If F is a
% function mapping scalars to vectors, the following holds:
% \begin{verbatim}
% [ F(i) | i=ri ] == [ F(i)[j] | i=ri, j=rj ]
% \end{verbatim}
% 
% \subsection{Examples}
% 
% \begin{itemize}
% \item Diagonal of a matrix is computed as:
% \begin{verbatim}
% d = [ A[i,i] | i=1:min(dim(A)) ]
% \end{verbatim}
% \item Matrix product is computed as:
% \begin{verbatim}
% C = [ sum([ A[i,j].*B[j,k] | j ]) | i=1:size(A,1), k=1:size(B,2) ]
% \end{verbatim}
% 
% 
% \end{itemize}

% \section{I/O}
% \section{Data Structures}
% \subsection{Hash Tables}
% \subsection{Sets}
% \subsection{Queues and Dequeues}
% \subsection{Trees}
% \subsection{Lists}

% \section{Calling C Functions}
\section{Running External Programs}

% Perl, Python, and Ruby are well known for their ability to easily run and interact with other programs.
% In Perl and Ruby, backticks provide a powerful and simple way to call a program and capture its output as as a string:
% \begin{verbatim}
%   #!/usr/bin/env perl
%   $greeting = `echo -n hello`;
%   print "$greeting, world.\n";
% \end{verbatim}
% In this rather simplistic example, the \verb|echo| program prints the string \verb|"hello"| and that output is captured into the variable \verb|$greeting|.
% Arbitrary shell commands can be spawned in backticks because backticks actually spawn a shell to interpret and run these commands.
% Thus, much of the power of this approach comes from the shell---the programming language just spawns the shell and arranges to capture the output.
% You can pass data to the programs spawned by interpolating values into the shell command:
% \begin{verbatim}
%   #!/usr/bin/env perl
%   $sorted = `sort -n $file`;
% \end{verbatim}
% Here things become a bit dangerous:
% if the value of the variable \verb|$file| contains characters that are specially interpreted by the shell, they will be.
% For example, if \verb|$file| is the string \verb|"/Volumes/External HD/data.csv"|, then the above command will attempt to sort the contents of two files named \verb|/Volumes/External| and \verb|HD/data.csv|, which are likely to either not exist, or possibly worse, not be the intended files.
% 
% There are two approaches one can take to address this issue: escape all the shell metacharacters in the the string \verb|$file| before interpolating it, or avoid using the shell by calling a lower level function like \verb|exec|.
% Both Perl and Ruby provide some ability to start a program and then read from its output file descriptor, but these approaches rapidly become quite cumbersome.
% Shell metacharacter escaping is provided by some third party modules, but is not a standard part of the installation of any of the scripting languages, and is hard to get right:
% the shell itself has a lot of complexity and syntax.
% In practice, programmers calling external programs simply tend to just hope that there are no strange characters in their file names.
% A few of the more paranoid will wrap arguments in single quotes within the backticks, writing \verb|`sort -n '$file'`|.
% This, however, is quite ugly, annoying, and worst of all, doesn't actually fix the problem.
% 
% Julia takes the second approach:
% instead of calling a shell to spawn external commands, Julia performs all the tricky UNIX pipe plumbing for you.
% Moreover, it allows you to easily create pipelines \emph{in Julia} where one command pipes output to another.
% In essence, Julia aims to be a better shell than the shell.

Julia borrows backtick notation for commands from the shell, Perl, and Ruby.
However, in Julia, writing
\begin{verbatim}
  julia> `echo hello`
  `echo hello`
\end{verbatim}
differs in a several aspects from the behavior in various shells, Perl, or Ruby:
\begin{itemize}

\item Instead of immediately running the command, backticks create a \verb|Cmd| object to represent the command.
You can use this object to connect the command to others via pipes, run it, and read or write to it.

\item When the command is run, Julia does not capture its output unless you specifically arrange for it to.
Instead, the output of the command by default goes to \verb|stdout| as it would using \verb|libc|'s \verb|system| call.

\item The command is never run with a shell.
Instead, Julia parses the command syntax directly, appropriately interpolating variables and splitting on words as the shell would, respecting shell quoting syntax.
The command is run as \verb|julia|'s immediate child process, using \verb|fork| and \verb|exec| calls.

\end{itemize}
Here's a simple example of actually running an external program:
\begin{verbatim}
  julia> run(`echo hello`)
  hello
  true
\end{verbatim}
The \verb|hello| is the output of the \verb|echo| command, while the \verb|true| is the return value of the command, indicating that it succeeded.
(These are colored differently by the repl if your terminal supports color.)

\subsection{Interpolation}

Suppose you want to do something a bit more complicated and use the name of a file in the variable \verb|file| as an argument to a command.
You can use \verb|$| for interpolation much as you would in a string literal:
\begin{verbatim}
  julia> file = "/etc/passwd"
  "/etc/passwd"

  julia> `sort $file`
  `sort /etc/passwd`
\end{verbatim}
A common pitfall when running external programs via a shell is that if a file name contains characters that are special to the shell, they may cause undesirable behavior.
Suppose, for example, rather than \verb|/etc/passwd|, we wanted to sort the contents of the file \verb|/Volumes/External HD/data.csv|.
Let's try it:
\begin{verbatim}
  julia> file = "/Volumes/External HD/data.csv"
  "/Volumes/External HD/data.csv"

  julia> `sort -n $file`
  `sort -n '/Volumes/External HD/data.csv'`
\end{verbatim}
How did the file name get quoted?
Julia knows that \verb|file| is meant to be interpolated as a single argument, so it quotes the word for you.\footnote{This not quite accurate:
the value of \texttt{file} is never interpreted by a shell, so there's no need for actual quoting.
The quotes are inserted only for presentation to the user, and so that you can cut and paste it back into the repl.}
This will even work if you interpolate a value as part of a shell word:
\begin{verbatim}
  julia> path = "/Volumes/External HD"
  "/Volumes/External HD"

  julia> name = "data"
  "data"

  julia> ext = "csv"
  "csv"

  julia> `sort $path/$name.$ext`
  `sort '/Volumes/External HD/data.csv'`
\end{verbatim}
As you can see, the space in the \verb|path| variable is appropriately escaped.
But what if you \emph{want} to interpolate multiple words?
In that case, just use an array (or any other iterable container):
\begin{verbatim}
  julia> files = ["/etc/passwd","/Volumes/External HD/data.csv"]
  ["/etc/passwd","/Volumes/External HD/data.csv"]

  julia> `grep foo $files`
  `grep foo /etc/passwd '/Volumes/External HD/data.csv'`
\end{verbatim}
If you interpolate an array as part of a shell word, Julia emulates the shell's \verb|{a,b,c}| argument generation:
\begin{verbatim}
  julia> names = ["foo","bar","baz"]
  ["foo","bar","baz"]

  julia> `grep xylophone $names.txt`
  `grep xylophone foo.txt bar.txt baz.txt`
\end{verbatim}
If you interpolate multiple arrays, the shell's Cartesian product generation behavior is emulated:
\begin{verbatim}
  julia> names = ["foo","bar","baz"]
  ["foo","bar","baz"]

  julia> exts = ["aux","log"]
  ["aux","log"]

  julia> `rm -f $names.$exts`
  `rm -f foo.aux foo.log bar.aux bar.log baz.aux baz.log`
\end{verbatim}
Since you can interpolate literal arrays, you can easily use this generative functionality without needing to create temporary array objects first:
\begin{verbatim}
  julia> `rm -rf ${"foo","bar","baz"}.${"aux","log"}`
  `rm -rf foo.aux foo.log bar.aux bar.log baz.aux baz.log`
\end{verbatim}

\subsection{Quoting}

Inevitably, one wants to write commands that aren't quite so simple, and it becomes necessary to use quotes.
Here's a simple example of a perl one-liner at a shell prompt:
\begin{verbatim}
  $ perl -le '$|=1; for (0..3) { print }'
  0
  1
  2
  3
\end{verbatim}
The Perl expression needs to be in single quotes for two reasons:
so that spaces don't break the expression into multiple shell words, and so that uses of variables like \texttt{\$|} (yes, that's a variable), don't cause interpolation.
In other instances, you may want to use double quotes so that interpolation \emph{does} occur:
\begin{verbatim}
  $ first="A"
  $ second="B"
  $ perl -le '$|=1; print for @ARGV' "1: $first" "2: $second"
  1: A
  2: B
\end{verbatim}
In general, the Julia backtick syntax is carefully designed so that you can just cut-and-paste shell commands as-is into backticks and they will work:
the escaping, quoting, and interpolation behaviors are the same as the shell's.
The only difference is that the interpolation is integrated and aware of Julia's notion of what is a single string value, and what is a container for multiple values.
Let's try the above two examples in Julia:
\begin{verbatim}
  julia> `perl -le '$|=1; for (0..3) { print }'`
  `perl -le '$|=1; for (0..3) { print }'`

  julia> run(ans)
  0
  1
  2
  3
  true

  julia> first = "A"; second = "B";

  julia> `perl -le 'print for @ARGV' "1: $first" "2: $second"`
  `perl -le 'print for @ARGV' '1: A' '2: B'`

  julia> run(ans)
  1: A
  2: B
  true
\end{verbatim}
The results are identical, and Julia's interpolation behavior mimics the shell's with some improvements due to the fact that Julia supports first-class iterable objects while most shells use strings split on spaces for this, which introduces ambiguities.
When trying to port shell commands to Julia, try cut and pasting first.
Since Julia shows commands to you before running them, you can easily and safely just examine its interpretation without doing any damage.

\subsection{Pipelines}

Shell metacharacters, such as \texttt{|}, \verb|&|, and \verb|>|, are not special inside of Julia's backticks:
unlike in the shell, inside of Julia's backticks, a pipe is always just a pipe:
\begin{verbatim}
  julia> run(`echo hello | sort`)
  hello | sort
  true
\end{verbatim}
This command prints the word ``hello'' followed by a literal pipe character followed by the word ``sort.''
Then how does one construct a pipeline?
Use Julia's \texttt{|} operator on \verb|Cmd| objects instead:
\begin{verbatim}
  julia> run(`echo hello` | `sort`)
  hello
  true
\end{verbatim}
This pipes the output of the \verb|echo| command to the \verb|sort| command.
Of course, this isn't terribly interesting since there's only one line to sort, but we can certainly do much more interesting things:
\begin{verbatim}
  julia> run(`cut -d: -f3 /etc/passwd` | `sort -n` | `tail -n5`)
  210
  211
  212
  213
  214
  true
\end{verbatim}
This prints the highest five user IDs on a UNIX system.

Another pipelining facility that Julia provides is running multiple commands in parallel:
\begin{verbatim}
  julia> run(`echo hello` & `echo world`)
  world
  hello
  true
\end{verbatim}
The order of the output here is non-deterministic because the two \verb|echo| processes are started nearly simultaneously, and race to make the first write to the \verb|stdout| descriptor they share with each other and the \verb|julia| parent process.
Julia lets you pipe the output from both of these processes to another program:
\begin{verbatim}
  julia> run(`echo world` & `echo hello` | `sort`)
  hello
  world
  true
\end{verbatim}
In terms of UNIX plumbing, what's happening here is that a single UNIX pipe object is created and written to by both \verb|echo| processes, and the other end of the pipe is read from by the \verb|sort| command.

The combination of a programming language, a first-class command abstraction, and automatic setup of pipes between processes is a powerful one.
To give some sense of the complex pipelines that can be created easily, here are some more sophisticated examples (apologies for excessive Perlage):
\begin{verbatim}
  prefixer(prefix, sleep) =
      `perl -nle '$|=1; print "'$prefix' ", $_; sleep '$sleep';'`

  julia> run(`perl -le '$|=1; for(0..9){ print; sleep 1 }'` |
             prefixer("A",2) & prefixer("B",2))
  A	0
  B	1
  A	2
  B	3
  A	4
  B	5
  A	6
  B	7
  A	8
  B	9
  true
\end{verbatim}
This is a classic example of a single producer feeding two concurrent consumers:
one \verb|perl| process generates lines with the numbers 0 through 9 on them, while two parallel processes consume that output, one prefixing lines with the letter ``A,'' the other with the letter ``B.''
Which consumer gets the first line is non-deterministic, but once that race has been won, the lines are consumed alternately by one process and then the other.\footnote{Setting \texttt{\$|=1} in Perl causes each print statement to flush the \texttt{stdout} handle, which is necessary for this example to work.
Otherwise all the output is buffered and printed to the pipe at once, to be read by a single consumer process.}

Here is an even more complex multi-stage producer-consumer example:
\begin{verbatim}
  julia> run(`perl -le '$|=1; for(0..9){ print; sleep 1 }'` |
             prefixer("X",3) & prefixer("Y",3) & prefixer("Z",3) |
             prefixer("A",2) & prefixer("B",2))
  B	Y	0
  A	Z	1
  B	X	2
  A	Y	3
  B	Z	4
  A	X	5
  B	Y	6
  A	Z	7
  B	X	8
  A	Y	9
  true
\end{verbatim}
This example is similar to the previous one, except there are two stages of consumers, and the stages have different latency so they use a different number of parallel workers, to maintain saturated throughput.

Finally, we have an example of how you can make a process read from itself:
\begin{verbatim}
  julia> gen = `perl -le '$|=1; for(0..9){ print; sleep 1 }'`
  `perl -le '$|=1; for(0..9){ print; sleep 1 }'`

  julia> dup = `perl -ne '$|=1; warn $_; print ".$_"; sleep 1'`
  `perl -ne '$|=1; warn $_; print ".$_"; sleep 1'`

  julia> run(gen | dup | dup)
  0
  .0
  1
  ..0
  2
  .1
  3
  ...0
  4
  .2
  5
  ..1
  6
  .3
  ....0
  7
  .4
  8
  9
  ..2
  .5
  ...1
  .6
  ..3
  .....0
  .7
  ..4
  .8
  .9
  ...2
  ..5
  ....1
  ..6
  ...3
\end{verbatim}
This example never terminates since the \verb|dup| process reads its own output and duplicates it to \verb|stderr| forever.
We strongly encourage you to try all these examples to see how they work.


\section{Arrays}

\subsection{Cell Arrays}

\subsection{Sparse Arrays}


\section{Parallel Computing}
\begin{itemize}
   \item \verb|remote_call(w, func, args...)| ---
     tell a worker to call a function on the given arguments.
     returns a \verb|RemoteRef| for the result.

   \item \verb|remote_do(w, func, args...)| ---
     remote function call with no result

   \item \verb|wait(r)| ---
     wait for a \verb|RemoteRef| to finish computing

   \item \verb|fetch(r)| ---
     wait for and get the value of a \verb|RemoteRef|

   \item \verb|pmap(func, lst)| ---
     call a function on each element of \verb|lst| (some 1-d thing), in
     parallel.

   \item \verb|send_msg(socket, x)| ---
     send a Julia object through a socket

   \item \verb|recv_msg(socket)| ---
     read the next Julia object from a socket
\end{itemize}


\section{Calling C Code}


\section{Standard Library Reference}

\subsection{Primitive Functions}

\subsection{Sets}

\subsection{Hash Tables}

\subsection{I/O}

\subsection{Regular Expressions}

\subsection{Mathematical Functions}


\section{Metaprogramming}

\subsection{Expressions and Eval}

\subsection{Macros}
% Macros are totally different from inlining.
% Macros are a hook into the compiler that lets you examine and rewrite the syntax of a piece of the program.
% You can use them to implement entirely new syntactic constructs like remote spawn, parallel for loops, string interpolation, pattern matching, Julia's command syntax, etc.
% 
% Macros also run at an earlier binding time than functions and so have different semantics.
% Inlining moves code around in a way that keeps the same function call semantics, i.e. you can't ``tell'' that it happened.
% Macros are just the opposite.
% For example, say I have a function that contains an inner function:
% 
% \begin{verbatim}
%   function foo()
%     bar(x) = XXX
%     ...
%     bar(...)
%   end
% \end{verbatim}
% 
% Now I want to abstract away the definition of \verb|bar|.
% Maybe I want to use it in multiple functions and I don't want to copy and paste it.
% With macros I can do this:
% 
% \begin{verbatim}
%   macro definestuff(name)
%     quote
%       ($name)(x) = XXX
%     end
%   end
% 
%   function foo()
%     @definestuff bar
%     ...
%   end
% \end{verbatim}
% 
% This is not possible without macros.
% If you passed \verb|:bar| to a function, that function has no way to define a local \verb|bar| inside \verb|foo|.
% If it used \verb|eval|, it would define a top-level function called \verb|bar|. 
% Since the macro runs so much earlier, it can change the code of \verb|foo| itself, so it can easily modify local variables.
% 
% And this example hardly shows the full power, since the argument to
% the macro is only a symbol.
% This is just to show the semantic differences.
% Another example is \verb|spawn|:
% 
% \begin{verbatim}
%   macro spawn(expr)
%     quote
%       spawn(()->($expr))
%     end
%   end
% \end{verbatim}
% 
% Now you can write \verb|@spawn a+b| and it will call a function \verb|spawn| on \verb|a+b| wrapped in a thunk.
% This syntax improvement requires macros:
% the function call \verb|spawn(a+b)| couldn't work since \verb|a+b| will be fully evaluated before \verb|spawn| is called.
% Calling a quoted expression, as in \verb|spawn(:(a+b))|, is ugly and moreover simply wouldn't work since \verb|spawn| cannot use the expression \verb|:(a+b)| by itself to access the values of local variables \verb|a| and \verb|b|.
% 
% People often compare macros to inlining (for example, the designer(s) of C++), but this is a pun.
% There is only a superficial similarity of inserting code into other code.

\end{document}