never necessary:
\begin{alltt}
-! Postfix equivalent of (2 + 3) {*} 6
+! Postfix translation of (2 + 3) {*} 6
2 3 + 6 {*}
\emph{30}
-! Postfix equivalent of 2 + (3 {*} 6)
+! Postfix translation of 2 + (3 {*} 6)
2 3 6 {*} +
\emph{20}
\end{alltt}
2 4 8 {*} {*} .
\emph{64}
\end{alltt}
+
However, the stack effect of \texttt{{*} {*}} is \texttt{( a b c -{}-
a{*}b{*}c )}. We would like to write a word that takes \emph{one} input
only. To achieve this, we need to be able to duplicate the top stack
\texttt{swap ( x y -{}- y x )} Swap top two stack elements. Used when
a word expects parameters in a different order.
+\texttt{over ( x y -{}- x y x )} Bring the second stack element ``over''
+the top element.
+
\texttt{rot ( x y z -{}- y z x )} Rotate top three stack elements
to the left.
\texttt{-rot ( x y z -{}- z x y )} Rotate top three stack elements
to the right.
-\texttt{over ( x y -{}- x y x )} Bring the second stack element {}``over''
-the top element.
-
\texttt{nip ( x y -{}- y )} Remove the second stack element.
\texttt{tuck ( x y -{}- y x y )} Tuck the top stack element under
\texttt{dupd ( x y -{}- x x y )} Duplicate the second stack element.
-\texttt{swapd ( x y z -{}- y x z )} Swap the second and third stack elements.
-
-\texttt{transp ( x y z -{}- z y x )} Swap the first and third stack elements.
-
\texttt{2drop ( x y -{}- )} Discard the top two stack elements.
\texttt{2dup ( x y -{}- x y x y )} Duplicate the top two stack elements. A frequent use for this word is when two values have to be compared using something like \texttt{=} or \texttt{<} before being passed to another word.
: numbers-game number-to-guess numbers-game-loop ;
\end{verbatim}
-\section{More about numbers}
-
-Factor provides a rich set of math words. Factor numbers more closely model the mathematical concept of a number than other languages. Where possible, exact answers are given -- for example, adding or multiplying two integers never results in overflow, and dividing two integers yields a fraction rather than a truncated result. Complex numbers are supported, allowing many functions to be computed with parameters that would raise errors or return ``not a number'' in other languages.
-
-\subsection{Integers}
-
-The simplest type of number is the integer. Integers come in two varieties -- \emph{fixnums} and \emph{bignums}. As their names suggest, a fixnum is a fixed-width quantity\footnote{Fixnums range in size from $-2^{w-3}-1$ to $2^{w-3}$, where $w$ is the word size of your processor (for example, 32 bits). Because fixnums automatically grow to bignums, usually you do not have to worry about details like this.}, and is a bit quicker to manipulate than an arbitrary-precision bignum.
-
-The predicate word \texttt{integer?} tests if the top of the stack is an integer. If this returns true, then exactly one of \texttt{fixnum?} or \texttt{bignum?} would return true for that object. Usually, your code does not have to worry if it is dealing with fixnums or bignums.
-
-Unlike some languages where the programmer has to declare storage size explicitly and worry about overflow, integer operations automatically return bignums if the result would be too big to fit in a fixnum. Here is an example where multiplying two fixnums returns a bignum:
-
-\begin{alltt}
-134217728 fixnum? .
-\emph{t}
-128 fixnum? .
-\emph{t}
-134217728 128 * .
-\emph{17179869184}
-134217728 128 * bignum? .
-\emph{t}
-\end{alltt}
-
-Integers can be entered using a different base. By default, all number entry is in base 10, however this can be changed by prefixing integer literals with one of the parsing words \texttt{BIN:}, \texttt{OCT:}, or \texttt{HEX:}. For example:
-
-\begin{alltt}
-BIN: 1110 BIN: 1 + .
-\emph{15}
-HEX: deadbeef 2 * .
-\emph{7471857118}
-\end{alltt}
-
-The word \texttt{.} prints numbers in decimal, regardless of how they were input. A set of words in the \texttt{prettyprint} vocabulary is provided for print integers using another base.
-
-\begin{alltt}
-1234 .h
-\emph{4d2}
-1234 .o
-\emph{2232}
-1234 .b
-\emph{10011010010}
-\end{alltt}
-
-\subsection{Rational numbers}
-
-If we add, subtract or multiply any two integers, the result is always an integer. However, this is not the case with division. When dividing a numerator by a denominator where the numerator is not a integer multiple of the denominator, a ratio is returned instead.
-
-\begin{alltt}
-1210 11 / .
-\emph{110}
-100 330 / .
-\emph{10/33}
-\end{alltt}
-
-Ratios are printed and can be input literally in the form of the second example. Ratios are always reduced to lowest terms by factoring out the greatest common divisor of the numerator and denominator. A ratio with a denominator of 1 becomes an integer. Trying to create a ratio with a denominator of 0 raises an error.
-
-The predicate word \texttt{ratio?} tests if the top of the stack is a ratio. The predicate word \texttt{rational?} returns true if and only if one of \texttt{integer?} or \texttt{ratio?} would return true for that object. So in Factor terms, a ``ratio'' is a rational number whose denominator is not equal to 1.
-
-Ratios behave just like any other number -- all numerical operations work as expected, and in fact they use the formulas for adding, subtracting and multiplying fractions that you learned in high school.
-
-\begin{alltt}
-1/2 1/3 + .
-\emph{5/6}
-100 6 / 3 * .
-\emph{50}
-\end{alltt}
-
-Ratios can be deconstructed into their numerator and denominator components using the \texttt{numerator} and \texttt{denominator} words. The numerator and denominator are both integers, and furthermore the denominator is always positive. When applied to integers, the numerator is the integer itself, and the denominator is 1.
-
-\begin{alltt}
-75/33 numerator .
-\emph{25}
-75/33 denominator .
-\emph{11}
-12 numerator .
-\emph{12}
-\end{alltt}
-
-\subsection{Floating point numbers}
-
-Rational numbers represent \emph{exact} quantities. On the other hand, a floating point number is an \emph{approximation}. While rationals can grow to any required precision, floating point numbers are fixed-width, and manipulating them is usually faster than manipulating ratios or bignums (but slower than manipulating fixnums). Floating point literals are often used to represent irrational numbers, which have no exact representation as a ratio of two integers. Floating point literals are input with a decimal point.
-
-\begin{alltt}
-1.23 1.5 + .
-\emph{1.73}
-\end{alltt}
-
-The predicate word \texttt{float?} tests if the top of the stack is a floating point number. The predicate word \texttt{real?} returns true if and only if one of \texttt{rational?} or \texttt{float?} would return true for that object.
-
-Floating point numbers are \emph{contagious} -- introducing a floating point number in a computation ensures the result is also floating point.
-
-\begin{alltt}
-5/4 1/2 + .
-\emph{7/4}
-5/4 0.5 + .
-\emph{1.75}
-\end{alltt}
-
-Apart from contaigion, there are two ways of obtaining a floating point result from a computation; the word \texttt{>float ( n -{}- f )} converts a rational number into its floating point approximation, and the word \texttt{/f ( x y -{}- x/y )} returns the floating point approximation of a quotient of two numbers.
-
-\begin{alltt}
-7 4 / >float .
-\emph{1.75}
-7 4 /f .
-\emph{1.75}
-\end{alltt}
-
-Indeed, the word \texttt{/f} could be defined as follows:
-
-\begin{alltt}
-: /f / >float ;
-\end{alltt}
-
-However, the actual definition is slightly more efficient, since it computes the floating point result directly.
-
-\subsection{Complex numbers}
-
-Just like we had to widen the integers to the rationals in order to divide, we have to widen the real numbers to the set of \emph{complex numbers} to solve certain kinds of equations. For example, the equation $x^2 + 1 = 0$ has no solution for real $x$, because there is no real number that is a square root of -1. This is so because the real numbers are not \emph{algebraically complete}.
-
-Complex numbers, however, are algebraically complete, and Factor will find one solution to this equation\footnote{The other, of course being \texttt{\#\{ 0 -1 \}}.}:
-
-\begin{alltt}
--1 sqrt .
-\emph{\#\{ 0 1 \}}
-\end{alltt}
-
-The literal syntax for a complex number is \texttt{\#\{ re im \}}, where \texttt{re} is the real part and \texttt{im} is the imaginary part. For example, the literal \texttt{\#\{ 1/2 1/3 \}} corresponds to the complex number $1/2 + 1/3i$.
-
-The words \texttt{i} an \texttt{-i} push the literals \texttt{\#\{ 0 1 \}} and \texttt{\#\{ 0 -1 \}}, respectively.
-
-The predicate word \texttt{complex?} tests if the top of the stack is a complex number. Note that unlike math, where all real numbers are also complex numbers, Factor only considers a number to be a complex number if its imaginary part is non-zero.
-
-Complex numbers can be deconstructed into their real and imaginary components using the \texttt{real} and \texttt{imaginary} words. Both components can be pushed at once using the word \texttt{>rect ( z -{}- re im )}.
-
-\begin{alltt}
--1 sqrt real .
-\emph{0}
--1 sqrt imaginary .
-\emph{1}
--1 sqrt sqrt >rect .s
-\emph{\{ 0.7071067811865476 0.7071067811865475 \}}
-\end{alltt}
-
-A complex number can be constructed from a real and imaginary component on the stack using the word \texttt{rect> ( re im -{}- z )}.
-
-\begin{alltt}
-1/3 5 rect> .
-\emph{\#\{ 1/3 5 \}}
-\end{alltt}
-
-Complex numbers are stored in \emph{rectangular form} as a real/imaginary component pair (this is where the names \texttt{>rect} and \texttt{rect>} come from). An alternative complex number representation is \emph{polar form}, consisting of an absolute value and argument. The absolute value and argument can be computed using the words \texttt{abs} and \texttt{arg}, and both can be pushed at once using \texttt{>polar ( z -{}- abs arg )}.
-
-\begin{alltt}
-5.3 abs .
-\emph{5.3}
-i arg .
-\emph{1.570796326794897}
-\#\{ 4 5 \} >polar .s
-\emph{\{ 6.403124237432849 0.8960553845713439 \}}
-\end{alltt}
-
-A new complex number can be created from an absolute value and argument using \texttt{polar> ( abs arg -{}- z )}.
-
-\begin{alltt}
-1 pi polar> .
-\emph{\#\{ -1.0 1.224606353822377e-16 \}}
-\end{alltt}
-
-\subsection{Transcedential functions}
-
-The \texttt{math} vocabulary provides a rich library of mathematical functions that covers exponentiation, logarithms, trigonometry, and hyperbolic functions. All functions accept and return complex number arguments where appropriate. These functions all return floating point values, or complex numbers whose real and imaginary components are floating point values.
-
-\texttt{\^{} ( x y -- x\^{}y )} raises \texttt{x} to the power of \texttt{y}. In the cases of \texttt{y} being equal to $1/2$, -1, or 2, respectively, the words \texttt{sqrt}, \texttt{recip} and \texttt{sq} can be used instead.
-
-\begin{alltt}
-2 4 \^ .
-\emph{16.0}
-i i \^ .
-\emph{0.2078795763507619}
-\end{alltt}
-
-All remaining functions have a stack effect \texttt{( x -{}- y )}, it won't be repeated for brevity.
-
-\texttt{exp} raises the number $e$ to a specified power. The number $e$ can be pushed on the stack with the \texttt{e} word, so \texttt{exp} could have been defined as follows:
-
-\begin{alltt}
-: exp ( x -- e^x ) e swap \^ ;
-\end{alltt}
-
-However, it is actually defined otherwise, for efficiency.\footnote{In fact, the word \texttt{\^{}} is actually defined in terms of \texttt{exp}, to correctly handle complex number arguments.}
-
-\texttt{log} computes the natural (base $e$) logarithm. This is the inverse of the \texttt{exp} function.
-
-\begin{alltt}
--1 log .
-\emph{\#\{ 0.0 3.141592653589793 \}}
-e log .
-\emph{1.0}
-\end{alltt}
-
-\texttt{sin}, \texttt{cos} and \texttt{tan} are the familiar trigonometric functions, and \texttt{asin}, \texttt{acos} and \texttt{atan} are their inverses.
-
-The reciprocals of the sine, cosine and tangent are defined as \texttt{sec}, \texttt{cosec} and \texttt{cot}, respectively. Their inverses are \texttt{asec}, \texttt{acosec} and \texttt{acot}.
-
-\texttt{sinh}, \texttt{cosh} and \texttt{tanh} are the hyperbolic functions, and \texttt{asinh}, \texttt{acosh} and \texttt{atanh} are their inverses.
-
-Similarly, the reciprocals of the hyperbolic functions are defined as \texttt{sech}, \texttt{cosech} and \texttt{coth}, respectively. Their inverses are \texttt{asech}, \texttt{acosech} and \texttt{acoth}.
-
-\subsection{Modular arithmetic}
-
-In addition to the standard division operator \texttt{/}, there are a few related functions that are useful when working with integers.
-
-\texttt{/i ( x y -{}- x/y )} performs a truncating integer division. It could have been defined as follows:
-
-\begin{alltt}
-: /i / >integer ;
-\end{alltt}
-
-However, the actual definition is a bit more efficient than that.
-
-\texttt{mod ( x y -{}- x\%y )} computes the remainder of dividing \texttt{x} by \texttt{y}. If the result is 0, then \texttt{x} is a multiple of \texttt{y}.
-
-\texttt{/mod ( x y -{}- x/y x\%y )} pushes both the quotient and remainder.
-
-\begin{alltt}
-100 3 mod .
-\emph{1}
--546 34 mod .
-\emph{-2}
-\end{alltt}
-
-\texttt{gcd ( x y -{}- z )} pushes the greatest common divisor of two integers; that is, the largest number that both integers could be divided by and still yield integers as results. This word is used behind the scenes to reduce rational numbers to lowest terms when doing ratio arithmetic.
-
-\subsection{Bitwise operations}
-
-There are two ways of looking at an integer -- as a mathematical entity, or as a string of bits. The latter representation faciliates the so-called \emph{bitwise operations}.
-
-\texttt{bitand ( x y -{}- x\&y )} returns a new integer where each bit is set if and only if the corresponding bit is set in both $x$ and $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-and with a mask switches off all flags that are not explicitly set in the mask.
-
-\begin{alltt}
-BIN: 101 BIN: 10 bitand .b
-\emph{0}
-BIN: 110 BIN: 10 bitand .b
-\emph{10}
-\end{alltt}
-
-\texttt{bitor ( x y -{}- x|y )} returns a new integer where each bit is set if and only if the corresponding bit is set in at least one of $x$ or $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-or with a mask switches on all flags that are set in the mask.
-
-\begin{alltt}
-BIN: 101 BIN: 10 bitor .b
-\emph{111}
-BIN: 110 BIN: 10 bitor .b
-\emph{110}
-\end{alltt}
-
-\texttt{bitxor ( x y -{}- x\^{}y )} returns a new integer where each bit is set if and only if the corresponding bit is set in exactly one of $x$ or $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-xor with a mask toggles on all flags that are set in the mask.
-
-\begin{alltt}
-BIN: 101 BIN: 10 bitxor .b
-\emph{111}
-BIN: 110 BIN: 10 bitxor .b
-\emph{100}
-\end{alltt}
-
-\texttt{shift ( x n -{}- y )} returns a new integer consisting of the bits of the first integer, shifted to the left by $n$ positions. If $n$ is negative, the bits are shifted to the right instead, and bits that ``fall off'' are discarded.
-
-\begin{alltt}
-BIN: 101 5 shift .b
-\emph{10100000}
-BIN: 11111 -2 shift .b
-\emph{111}
-\end{alltt}
-
-The attentive reader will notice that shifting to the left is equivalent to multiplying by a power of two, and shifting to the right is equivalent to performing a truncating division by a power of two.
-
\section{Sequences}
Factor supports two primary types for storing sequential data; lists and vectors.
--- /dev/null
+% :indentSize=4:tabSize=4:noTabs=true:mode=tex:
+
+\documentclass[english]{article}
+\usepackage[T1]{fontenc}
+\usepackage[latin1]{inputenc}
+\usepackage{alltt}
+\usepackage{tabularx}
+\usepackage{times}
+\pagestyle{headings}
+\setcounter{tocdepth}{2}
+\setlength\parskip{\medskipamount}
+\setlength\parindent{0pt}
+
+\newcommand{\sidebar}[1]{{\fbox{\fbox{\parbox{10cm}{\begin{minipage}[b]{10cm}
+{\LARGE For wizards}
+
+#1
+\end{minipage}}}}}}
+
+\newcommand{\chapkeywords}[1]{{\parbox{10cm}{\begin{minipage}[b]{10cm}
+\begin{quote}
+\emph{Key words:} \texttt{#1}
+\end{quote}
+\end{minipage}}}}
+\makeatletter
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
+%% Because html converters don't know tabularnewline
+\providecommand{\tabularnewline}{\\}
+
+\usepackage{babel}
+\makeatother
+\begin{document}
+
+\title{Factor Developer's Guide}
+
+
+\author{Slava Pestov}
+
+\maketitle
+\tableofcontents{}
+
+\section{Introduction}
+
+\subsection{Inspirations for Factor, history.}
+
+\section{First steps}
+
+This section will cover the basics of interactive development using the listener. Short code examples will be presented, along with an introduction to programming with the stack, a guide to using source files, and some hints for exploring the library.
+
+\subsection{The listener}
+
+\chapkeywords{print write read}
+
+Factor is an \emph{image-based environment}. When you compiled Factor, you also generated a file named \texttt{factor.image}. You will learn more about images later, but for now it suffices to understand that to start Factor, you must pass the image file name on the command line:
+
+\begin{alltt}
+./f factor.image
+\textbf{Loading factor.image... relocating... done
+This is native Factor 0.69
+Copyright (C) 2003, 2004 Slava Pestov
+Copyright (C) 2004 Chris Double
+Type ``exit'' to exit, ``help'' for help.
+65536 KB total, 62806 KB free
+ok}
+\end{alltt}
+
+An \texttt{\textbf{ok}} prompt is printed after the initial banner, indicating the listener is ready to execute Factor expressions. You can try the classical first program:
+
+\begin{alltt}
+\textbf{ok} "Hello, world." print
+\textbf{Hello, world.}
+\end{alltt}
+
+As you can guess, listener interaction will be set in a typewriter font. I will use boldface for program output, and plain text for user input You should try each code example in the guide, and try to understand it.
+
+One thing all programmers have in common is they make large numbers of mistakes. There are two types of errors; syntax errors, and logic errors. Syntax errors indicate a simple typo or misplaced character. The listener will indicate the point in the source code where the confusion occurs:
+
+\begin{alltt}
+\textbf{ok} "Hello, world" pr,int
+\textbf{<interactive>:1: Not a number
+"Hello, world" pr,int
+ ^
+:s :r :n :c show stacks at time of error.}
+\end{alltt}
+
+A logic error is not associated with a piece of source code, but rather an execution state. We will learn how to debug them later.
+
+\subsection{Colon definitions}
+
+\chapkeywords{:~; see}
+
+Once you build up a collection of useful code snippets, you can reuse them without retyping them each time.
+
+Lets try writing a program to prompt the user for their name, and then output a personalized greeting.
+
+\begin{alltt}
+\textbf{ok} "What is your name? " write read
+\textbf{What is your name? }Lambda the Ultimate
+\textbf{ok} "Greetings, " write print
+\textbf{Greetings, Lambda the Ultimate}
+\end{alltt}
+
+Now, instead of re-typing the entire program each time we want to execute it, it would be nice if we could just type one \emph{word}.
+
+A ``word'' is the main unit of program organization
+in Factor -- it corresponds to a ``function'', ``procedure''
+or ``method'' in other languages. Some words, like \texttt{print}, \texttt{write} and \texttt{read}, along with dozens of others we will see, are part of Factor. Other words will be created by you.
+
+When you create a new word, you associate a name with a particular sequence of \emph{already-existing} words. You should practice the suggestively-named \emph{colon definition syntax} in the listener:
+
+\begin{alltt}
+\textbf{ok} : ask-name "What is your name? " write read ;
+\end{alltt}
+
+What did we do above? We created a new word named \texttt{ask-name}, and associated with it the definition \texttt{"What is your name? " write read}. Now, lets type in two more colon definitions. The first one associates a name with the second part of our example. The second colon definition puts the first two together into a complete program.
+
+\begin{alltt}
+\textbf{ok} : greet "Greetings, " write print ;
+\textbf{ok} : friend ask-name greet ;
+\end{alltt}
+
+Now that the three words \texttt{ask-name}, \texttt{greet}, and \texttt{friend} have been defined, simply typing \texttt{friend} in the listener will run the example as if you had typed it directly.
+
+\begin{alltt}
+\textbf{ok} friend
+\textbf{What is your name? }Lambda the Ultimate
+\textbf{Greetings, Lambda the Ultimate}
+\end{alltt}
+
+You can look at the definition of any word, including library words, using \texttt{see}:
+
+\begin{alltt}
+\textbf{ok} \\ greet see
+\textbf{IN: scratchpad
+: greet
+ "Greetings, " write print ;}
+\end{alltt}
+
+\sidebar{
+Factor is written in itself. Indeed, most words in the Factor library are colon definitions, defined in terms of other words. Out of more than two thousand words in the Factor library, less than two hundred are \emph{primitive}, or built-in to the runtime.
+
+If you exit Factor by typing \texttt{exit}, any colon definitions entered at the listener will be lost. However, you can save a new image first, and use this image next time you start Factor in order to have access to your definitions.
+
+\begin{alltt}
+\textbf{ok} "work.image" save-image\\
+\textbf{ok} exit
+\end{alltt}
+
+The \texttt{factor.image} file you start with initially is just an image that was saved after the standard library, and nothing else, was loaded.
+}
+
+\subsection{The stack}
+
+\chapkeywords{.s .~clear}
+
+The \texttt{ask-name} word passes a piece of data to the \texttt{greet} word in the following definition:
+
+\begin{alltt}
+: friend ask-name greet ;
+\end{alltt}
+
+In order to be able to write more sophisticated programs, you will need to master usage of the \emph{stack}. The stack is used to exchange data between words. Input parameters -- for example, strings like \texttt{"Hello "}, or numbers, are pushed onto the top of the stack. The most recently pushed value is said to be \emph{at the top} of the stack. When a word is executed, it pops
+input parameters from the top of the
+stack. Results are then pushed back on the stack.
+
+Lets look at the \texttt{friend} example one more time. Recall that first, the \texttt{friend} word calls the \texttt{ask-name} word defined as follows:
+
+\begin{alltt}
+: ask-name "What is your name? " write read ;
+\end{alltt}
+
+Read this definition from left to right, and visualize the data flow. First, the string \texttt{"What is your name? "} is pushed on the stack. The \texttt{write} word is called; it removes the string from the stack and writes it, without returning any values. Next, the \texttt{read} word is called. It waits for input from the user, then pushes the entered string on the stack.
+
+After \texttt{ask-name}, the \texttt{friend} word finally calls \texttt{greet}, which was defined as follows:
+
+\begin{alltt}
+: greet "Greetings, " write print ;
+\end{alltt}
+
+This word pushes the string \texttt{"Greetings, "} and calls \texttt{write}, which writes this string. Next, \texttt{print} is called. Recall that the \texttt{read} call inside \texttt{ask-name} left the user's input on the stack; well, it is still there, and \texttt{print} writes it. In case you haven't already guessed, the difference between \texttt{write} and \texttt{print} is that the latter outputs a terminating new line.
+
+How did we know that \texttt{write} and \texttt{print} take one value from the stack each, or that \texttt{read} leaves one value on the stack? The answer is, you don't always know, however, you can use \texttt{see} to look up the \emph{stack effect comment} of any library word:
+
+\begin{alltt}
+\textbf{ok} \\ print see
+\textbf{IN: stdio
+: print ( string -{}- )
+ "stdio" get fprint ;}
+\end{alltt}
+
+You can see that the stack effect of \texttt{print} is \texttt{( string -- )}. This is a mnemonic indicating that this word pops a string from the stack, and pushes no values back on the stack. As you can verify using \texttt{see}, the stack effect of \texttt{read} is \texttt{( -- string )}.
+
+The contents of the stack can be printed using the \texttt{.s} word:
+
+\begin{alltt}
+\textbf{ok} 1 2 3 .s
+\textbf{1
+2
+3}
+\end{alltt}
+
+The \texttt{.} (full-stop) word removes the top stack element, and prints it. Unlike \texttt{print}, which will only print a string, \texttt{.} can print any object.
+
+\begin{alltt}
+\textbf{ok} "Hi" .
+\textbf{"Hi"}
+\end{alltt}
+
+You might notice that \texttt{.} surrounds strings with quotes, while \texttt{print} prints the string without any kind of decoration. This is because \texttt{.} is a special word that outputs objects in a form \emph{that can be parsed back in}. This is a fundamental feature of Factor -- data is code, and code is data. We will learn some very deep consequences of this throughout this guide.
+
+If the stack is empty, calling \texttt{.} will raise an error. This is in general true for any word called with insufficient parameters, or parameters of the wrong type.
+
+The \texttt{clear} word removes all elements from the stack.
+
+Lets review the words we've seen until now.
+
+\begin{tabularx}{12cm}{|l|l|l|X|}
+\hline
+Vocabulary&
+Word&
+Stack effect&
+Description\tabularnewline
+\hline
+\texttt{stdio}&
+\texttt{print}&
+\texttt{( string -{}- )}&
+Write a string to the console, with a new line.\tabularnewline
+\hline
+\texttt{stdio}&
+\texttt{write}&
+\texttt{( string -{}- )}&
+Write a string to the console, without a new line.\tabularnewline
+\hline
+\texttt{stdio}&
+\texttt{read}&
+\texttt{( -{}- string )}&
+Read a line of input from the console.\tabularnewline
+\hline
+\texttt{prettyprint}&
+\texttt{.s}&
+\texttt{( -{}- )}&
+Print stack contents.\tabularnewline
+\hline
+\texttt{prettyprint}&
+\texttt{.}&
+\texttt{( value -{}- )}&
+Print value at top of stack in parsable form.\tabularnewline
+\hline
+\texttt{stack}&
+\texttt{clear}&
+\texttt{( ...~-{}- )}&
+Clear stack contents.\tabularnewline
+\hline
+\end{tabularx}
+
+\sidebar{
+In Factor, the stack takes the place of local variables found in other languages. Factor still supports variables, but they are usually used for different purposes. Like most other languages, Factor heap-allocates objects, and passes object references by value. However, we don't worry about this until mutable state is introduced.
+}
+
+\subsection{Arithmetic}
+
+\chapkeywords{+ - {*} / neg pred succ}
+
+The usual arithmetic operators \texttt{+ - {*} /} all take two parameters
+from the stack, and push one result back. Where the order of operands
+matters (\texttt{-} and \texttt{/}), the operands are taken in the natural order. For example:
+
+\begin{alltt}
+\textbf{ok} 10 17 + .
+\textbf{27}
+\textbf{ok} 111 234 - .
+\textbf{-123}
+\textbf{ok} 333 3 / .
+\textbf{111}
+\end{alltt}
+
+The \texttt{neg} unary operator negates the number at the top of the stack (that is, multiplies it by -1). Two unary operators \texttt{pred} and \texttt{succ} subtract 1 and add 1, respectively, to the number at the top of the stack.
+
+This type of arithmetic is called \emph{postfix}, because the operator
+follows the operands. Contrast this with \emph{infix} notation used
+in many other languages, so-called because the operator is in-between
+the two operands.
+
+More complicated infix expressions can be translated into postfix
+by translating the inner-most parts first. Grouping parentheses are
+never necessary.
+
+Here is the postfix translation of $(2 + 3) {*} 6$:
+
+\begin{alltt}
+\textbf{ok} 2 3 + 6 {*}
+\textbf{30}
+\end{alltt}
+
+Here is the postfix translation of $2 + (3 {*} 6)$:
+
+\begin{alltt}
+\textbf{ok} 2 3 6 {*} +
+\textbf{20}
+\end{alltt}
+
+As a simple example demonstrating postfix arithmetic, consider a word, presumably for an aircraft navigation system, that takes the flight time, the aircraft
+velocity, and the tailwind velocity, and returns the distance travelled.
+If the parameters are given on the stack in that order, all we do
+is add the top two elements (aircraft velocity, tailwind velocity)
+and multiply it by the element underneath (flight time). So the definition
+looks like this:
+
+\begin{alltt}
+\textbf{ok} : distance ( time aircraft tailwind -{}- distance ) + {*} ;
+\textbf{ok} 2 900 36 distance .
+\textbf{1872}
+\end{alltt}
+
+Note that we are not using any distance or time units here. To extend this example to work with units, we make the assumption that for the purposes of computation, all distances are
+in meters, and all time intervals are in seconds. Then, we can define words
+for converting from kilometers to meters, and hours and minutes to
+seconds:
+
+\begin{alltt}
+\textbf{ok} : kilometers 1000 {*} ;
+\textbf{ok} : minutes 60 {*} ;
+\textbf{ok} : hours 60 {*} 60 {*} ;
+2 kilometers .
+\emph{2000}
+10 minutes .
+\emph{600}
+2 hours .
+\emph{7200}
+\end{alltt}
+
+The implementation of \texttt{km/hour} is a bit more complex. We would like it to convert kilometers per hour to meters per second. To get the desired result, we first have to convert to kilometers per second, then divide this by the number of seconds in one hour.
+
+\begin{alltt}
+\textbf{ok} : km/hour kilometers 1 hours / ;
+\textbf{ok} 2 hours 900 km/hour 36 km/hour distance .
+\textbf{1872000}
+\end{alltt}
+
+\subsection{Shuffle words}
+
+\chapkeywords{drop dup swap over nip dupd rot -rot tuck pick 2drop 2dup 3drop 3dup}
+
+Lets try writing a word to compute the cube of a number.
+Three numbers on the stack can be multiplied together using \texttt{{*}
+{*}}:
+
+\begin{alltt}
+2 4 8 {*} {*} .
+\emph{64}
+\end{alltt}
+
+However, the stack effect of \texttt{{*} {*}} is \texttt{( a b c -{}-
+a{*}b{*}c )}. We would like to write a word that takes \emph{one} input
+only, and multiplies it by itself three times. To achieve this, we need to make two copies of the top stack element, and then execute \texttt{{*} {*}}. As it happens, there is a word \texttt{dup ( x -{}-
+x x )} for precisely this purpose. Now, we are able to define the
+\texttt{cube} word:
+
+\begin{alltt}
+: cube dup dup {*} {*} ;
+10 cube .
+\emph{1000}
+-2 cube .
+\emph{-8}
+\end{alltt}
+
+The \texttt{dup} word is just one of the several so-called \emph{shuffle words}. Shuffle words are used to solve the problem of composing two words whose stack effects don't quite {}``match up''.
+
+Lets take a look at the four most-frequently used shuffle words:
+
+\texttt{drop ( x -{}- )} Discard the top stack element. Used when
+a word returns a value that is not needed.
+
+\texttt{dup ( x -{}- x x )} Duplicate the top stack element. Used
+when a value is required as input for more than one word.
+
+\texttt{swap ( x y -{}- y x )} Swap top two stack elements. Used when
+a word expects parameters in a different order.
+
+\texttt{over ( x y -{}- x y x )} Bring the second stack element {}``over''
+the top element.
+
+The remaining shuffle words are not used nearly as often, but are nonetheless handy in certian situations:
+
+\texttt{nip ( x y -{}- y )} Remove the second stack element.
+
+\texttt{dupd ( x y -{}- x x y )} Duplicate the second stack element.
+
+\texttt{rot ( x y z -{}- y z x )} Rotate top three stack elements
+to the left.
+
+\texttt{-rot ( x y z -{}- z x y )} Rotate top three stack elements
+to the right.
+
+\texttt{tuck ( x y -{}- y x y )} Tuck the top stack element under
+the second stack element.
+
+\texttt{pick ( x y z -{}- x y z x )} ``Pick'' the third stack element.
+
+\texttt{2drop ( x y -{}- )} Discard the top two stack elements.
+
+\texttt{2dup ( x y -{}- x y x y )} Duplicate the top two stack elements. A frequent use for this word is when two values have to be compared using something like \texttt{=} or \texttt{<} before being passed to another word.
+
+\texttt{3drop ( x y z -{}- )} Discard the top three stack elements.
+
+\texttt{3dup ( x y z -{}- x y z x y z )} Duplicate the top three stack elements.
+
+You should try all these words out and become familiar with them. Push some numbers on the stack,
+execute a shuffle word, and look at how the stack contents was changed using
+\texttt{.s}. Compare the stack contents with the stack effects above.
+
+Try to avoid as much as possible the complex shuffle words such as \texttt{rot} and \texttt{2dup}. They make data flow harder to understand. If you find yourself using too many shuffle words, or you're writing
+a stack effect comment in the middle of a colon definition to keep track of stack contents, it is
+a good sign that the word should probably be factored into two or
+more smaller words.
+
+A good rule of thumb is that each word should take at most a couple of sentences to describe; if it is so complex that you have to write more than that in a documentation comment, the word should be split up.
+
+Effective factoring is like riding a bicycle -- once you ``get it'', it becomes second nature.
+
+\subsection{Source files}
+
+\subsection{Exploring the library}
+
+\section{Working with data}
+
+\subsection{Lists and cons cells}
+
+\chapkeywords{cons car cdr uncons}
+
+A \emph{cons cell} is an ordered pair of values. The first value is called the \emph{car},
+the second is called the \emph{cdr}.
+
+The \texttt{cons} word takes two values from the stack, and pushes a cons cell containing both values:
+
+\begin{alltt}
+\textbf{ok} "fish" "chips" cons .
+\textbf{{[} "fish" | "chips" {]}}
+\end{alltt}
+
+Recall that \texttt{.}~prints objects in a form that can be parsed back in. This suggests that there is a literal syntax for cons cells. The difference between the literal syntax and calling \texttt{cons} is two-fold; \texttt{cons} can be used to make a cons cell whose components are computed values, and not literals, and \texttt{cons} allocates a new cons cell each time it is called, whereas a literal is allocated once.
+
+The \texttt{car} and \texttt{cdr} words push the constituents of a cons cell at the top of the stack.
+
+\begin{alltt}
+\textbf{ok} 5 "blind mice" cons car .
+\textbf{5}
+\textbf{ok} "peanut butter" "jelly" cons cdr .
+\textbf{"jelly"}
+\end{alltt}
+
+The \texttt{uncons} word pushes both the car and cdr of the cons cell at once:
+
+\begin{alltt}
+\textbf{ok} {[} "potatoes" | "gravy" {]} uncons .s
+\textbf{\{ "potatoes" "gravy" \}}
+\end{alltt}
+
+Lists of values are represented with nested cons cells. The car is the first element of the list; the cdr is the rest of the list. The following example demonstrates this, along with the literal syntax used to print lists:
+
+\begin{alltt}
+\textbf{ok} {[} 1 2 3 4 {]} car .
+\textbf{1}
+\textbf{ok} {[} 1 2 3 4 {]} cdr .
+\textbf{{[} 2 3 4 {]}}
+\textbf{ok} {[} 1 2 3 4 {]} cdr cdr .
+\textbf{{[} 3 4 {]}}
+\end{alltt}
+
+Note that taking the cdr of a list of three elements gives a list of two elements; taking the cdr of a list of two elements returns a list of one element. So what is the cdr of a list of one element? It is the special value \texttt{f}:
+
+\begin{alltt}
+\textbf{ok} {[} "snowpeas" {]} cdr .
+\textbf{f}
+\end{alltt}
+
+The special value \texttt{f} represents the empty list. Hence you can see how cons cells and \texttt{f} allow lists of values to be constructed. If you are used to other languages, this might seem counter-intuitive at first, however the utility of this construction will come into play when we consider recursive words later in this chapter.
+
+One thing worth mentioning is the concept of an \emph{improper list}. An improper list is one where the cdr of the last cons cell is not \texttt{f}. Improper lists are input with the following syntax:
+
+\begin{verbatim}
+[ 1 2 3 | 4 ]
+\end{verbatim}
+
+Improper lists are rarely used, but it helps to be aware of their existence. Lists that are not improper lists are sometimes called \emph{proper lists}.
+
+\subsection{Operations on lists}
+
+The \texttt{append} word appends two lists at the top of the stack:
+
+\begin{alltt}
+\textbf{ok} {[} 1 2 3 {]} {[} 4 5 6 {]} append .
+\textbf{{[} 1 2 3 4 5 6 {]}}
+\textbf{ok} {[} 1 2 3 {]} dup {[} 4 5 6 {]} append .s
+\textbf{\{ {[} 1 2 3 {]} {[} 1 2 3 4 5 6 {]} \}}
+\end{alltt}
+
+Interestingly, only the first parameter has to be a list. if the second parameter
+is an improper list, or just a list at all, \texttt{append} returns an improper list:
+
+\begin{alltt}
+\textbf{ok} {[} 1 2 3 {]} 4 append .
+\textbf{{[} 1 2 3 | 4 {]}}
+\end{alltt}
+
+\subsection{Debugging}
+
+\subsection{Conditional execution}
+
+Until now, all code examples we've considered have been linear in nature; each word is executed in turn, left to right. To perform useful computations, we need the ability the execute different code depending on circumstances.
+
+The simplest style of a conditional form in Factor is the following:
+
+\begin{alltt}
+\emph{condition} {[}
+ \emph{to execute if true}
+{] [}
+ \emph{to execute if false}
+{]} ifte
+\end{alltt}
+
+The condition should be some piece of code that leaves a truth value on the stack. What is a truth value? In Factor, there is no special boolean data type
+-- instead, the special value \texttt{f} we've already seen to represent empty lists also represents falsity. Every other object represents boolean truth.
+
+Lets look at a simple example of a word that
+
+\subsection{Recursion}
+
+\subsection{Combinators}
+
+\subsection{The interpreter}
+
+\subsection{Recursive combinators}
+
+\subsection{Unit testing}
+
+\section{All about numbers}
+
+A brief introduction to arithmetic in Factor was given in the first chapter. Most of the time, the simple features outlined there suffice, and if math is not your thing, you can skim (or skip!) this chapter. For the true mathematician, Factor's numerical capability goes far beyond simple arithmetic.
+
+Factor's numbers more closely model the mathematical concept of a number than other languages. Where possible, exact answers are given -- for example, adding or multiplying two integers never results in overflow, and dividing two integers yields a fraction rather than a truncated result. Complex numbers are supported, allowing many functions to be computed with parameters that would raise errors or return ``not a number'' in other languages.
+
+\subsection{Integers}
+
+\chapkeywords{integer?~BIN: OCT: HEX: .b .o .h}
+
+The simplest type of number is the integer. Integers come in two varieties -- \emph{fixnums} and \emph{bignums}. As their names suggest, a fixnum is a fixed-width quantity\footnote{Fixnums range in size from $-2^{w-3}-1$ to $2^{w-3}$, where $w$ is the word size of your processor (for example, 32 bits). Because fixnums automatically grow to bignums, usually you do not have to worry about details like this.}, and is a bit quicker to manipulate than an arbitrary-precision bignum.
+
+The predicate word \texttt{integer?}~tests if the top of the stack is an integer. If this returns true, then exactly one of \texttt{fixnum?}~or \texttt{bignum?}~would return true for that object. Usually, your code does not have to worry if it is dealing with fixnums or bignums.
+
+Unlike some languages where the programmer has to declare storage size explicitly and worry about overflow, integer operations automatically return bignums if the result would be too big to fit in a fixnum. Here is an example where multiplying two fixnums returns a bignum:
+
+\begin{alltt}
+\textbf{ok} 134217728 fixnum? .
+\textbf{t}
+\textbf{ok} 128 fixnum? .
+\textbf{t}
+\textbf{ok} 134217728 128 * .
+\textbf{17179869184}
+\textbf{ok} 134217728 128 * bignum? .
+\textbf{t}
+\end{alltt}
+
+Integers can be entered using a different base. By default, all number entry is in base 10, however this can be changed by prefixing integer literals with one of the parsing words \texttt{BIN:}, \texttt{OCT:}, or \texttt{HEX:}. For example:
+
+\begin{alltt}
+\textbf{ok} BIN: 1110 BIN: 1 + .
+\textbf{15}
+\textbf{ok} HEX: deadbeef 2 * .
+\textbf{7471857118}
+\end{alltt}
+
+The word \texttt{.} prints numbers in decimal, regardless of how they were input. A set of words in the \texttt{prettyprint} vocabulary is provided for print integers using another base.
+
+\begin{alltt}
+\textbf{ok} 1234 .h
+\textbf{4d2}
+\textbf{ok} 1234 .o
+\textbf{2232}
+\textbf{ok} 1234 .b
+\textbf{10011010010}
+\end{alltt}
+
+\subsection{Rational numbers}
+
+\chapkeywords{rational?~numerator denominator}
+
+If we add, subtract or multiply any two integers, the result is always an integer. However, this is not the case with division. When dividing a numerator by a denominator where the numerator is not a integer multiple of the denominator, a ratio is returned instead.
+
+\begin{alltt}
+1210 11 / .
+\emph{110}
+100 330 / .
+\emph{10/33}
+\end{alltt}
+
+Ratios are printed and can be input literally in the form of the second example. Ratios are always reduced to lowest terms by factoring out the greatest common divisor of the numerator and denominator. A ratio with a denominator of 1 becomes an integer. Trying to create a ratio with a denominator of 0 raises an error.
+
+The predicate word \texttt{ratio?}~tests if the top of the stack is a ratio. The predicate word \texttt{rational?}~returns true if and only if one of \texttt{integer?}~or \texttt{ratio?}~would return true for that object. So in Factor terms, a ``ratio'' is a rational number whose denominator is not equal to 1.
+
+Ratios behave just like any other number -- all numerical operations work as expected, and in fact they use the formulas for adding, subtracting and multiplying fractions that you learned in high school.
+
+\begin{alltt}
+\textbf{ok} 1/2 1/3 + .
+\textbf{5/6}
+\textbf{ok} 100 6 / 3 * .
+\textbf{50}
+\end{alltt}
+
+Ratios can be deconstructed into their numerator and denominator components using the \texttt{numerator} and \texttt{denominator} words. The numerator and denominator are both integers, and furthermore the denominator is always positive. When applied to integers, the numerator is the integer itself, and the denominator is 1.
+
+\begin{alltt}
+\textbf{ok} 75/33 numerator .
+\textbf{25}
+\textbf{ok} 75/33 denominator .
+\textbf{11}
+\textbf{ok} 12 numerator .
+\textbf{12}
+\end{alltt}
+
+\subsection{Floating point numbers}
+
+\chapkeywords{float?~>float /f}
+
+Rational numbers represent \emph{exact} quantities. On the other hand, a floating point number is an \emph{approximation}. While rationals can grow to any required precision, floating point numbers are fixed-width, and manipulating them is usually faster than manipulating ratios or bignums (but slower than manipulating fixnums). Floating point literals are often used to represent irrational numbers, which have no exact representation as a ratio of two integers. Floating point literals are input with a decimal point.
+
+\begin{alltt}
+\textbf{ok} 1.23 1.5 + .
+\textbf{1.73}
+\end{alltt}
+
+The predicate word \texttt{float?}~tests if the top of the stack is a floating point number. The predicate word \texttt{real?}~returns true if and only if one of \texttt{rational?}~or \texttt{float?}~would return true for that object.
+
+Floating point numbers are \emph{contagious} -- introducing a floating point number in a computation ensures the result is also floating point.
+
+\begin{alltt}
+\textbf{ok} 5/4 1/2 + .
+\textbf{7/4}
+\textbf{ok} 5/4 0.5 + .
+\textbf{1.75}
+\end{alltt}
+
+Apart from contaigion, there are two ways of obtaining a floating point result from a computation; the word \texttt{>float ( n -{}- f )} converts a rational number into its floating point approximation, and the word \texttt{/f ( x y -{}- x/y )} returns the floating point approximation of a quotient of two numbers.
+
+\begin{alltt}
+\textbf{ok} 7 4 / >float .
+\textbf{1.75}
+\textbf{ok} 7 4 /f .
+\textbf{1.75}
+\end{alltt}
+
+Indeed, the word \texttt{/f} could be defined as follows:
+
+\begin{alltt}
+: /f / >float ;
+\end{alltt}
+
+However, the actual definition is slightly more efficient, since it computes the floating point result directly.
+
+\subsection{Complex numbers}
+
+\chapkeywords{i -i \#\{ complex?~real imaginary >rect rect> arg abs >polar polar>}
+
+Complex numbers arise as solutions to quadratic equations whose graph does not intersect the x axis. For example, the equation $x^2 + 1 = 0$ has no solution for real $x$, because there is no real number that is a square root of -1. However, in the field of complex numbers, this equation has a well-known solution:
+
+\begin{alltt}
+\textbf{ok} -1 sqrt .
+\textbf{\#\{ 0 1 \}}
+\end{alltt}
+
+The literal syntax for a complex number is \texttt{\#\{ re im \}}, where \texttt{re} is the real part and \texttt{im} is the imaginary part. For example, the literal \texttt{\#\{ 1/2 1/3 \}} corresponds to the complex number $1/2 + 1/3i$.
+
+The words \texttt{i} an \texttt{-i} push the literals \texttt{\#\{ 0 1 \}} and \texttt{\#\{ 0 -1 \}}, respectively.
+
+The predicate word \texttt{complex?} tests if the top of the stack is a complex number. Note that unlike math, where all real numbers are also complex numbers, Factor only considers a number to be a complex number if its imaginary part is non-zero.
+
+Complex numbers can be deconstructed into their real and imaginary components using the \texttt{real} and \texttt{imaginary} words. Both components can be pushed at once using the word \texttt{>rect ( z -{}- re im )}.
+
+\begin{alltt}
+\textbf{ok} -1 sqrt real .
+\textbf{0}
+\textbf{ok} -1 sqrt imaginary .
+\textbf{1}
+\textbf{ok} -1 sqrt sqrt >rect .s
+\textbf{\{ 0.7071067811865476 0.7071067811865475 \}}
+\end{alltt}
+
+A complex number can be constructed from a real and imaginary component on the stack using the word \texttt{rect> ( re im -{}- z )}.
+
+\begin{alltt}
+\textbf{ok} 1/3 5 rect> .
+\textbf{\#\{ 1/3 5 \}}
+\end{alltt}
+
+Complex numbers are stored in \emph{rectangular form} as a real/imaginary component pair (this is where the names \texttt{>rect} and \texttt{rect>} come from). An alternative complex number representation is \emph{polar form}, consisting of an absolute value and argument. The absolute value and argument can be computed using the words \texttt{abs} and \texttt{arg}, and both can be pushed at once using \texttt{>polar ( z -{}- abs arg )}.
+
+\begin{alltt}
+\textbf{ok} 5.3 abs .
+\textbf{5.3}
+\textbf{ok} i arg .
+\textbf{1.570796326794897}
+\textbf{ok} \#\{ 4 5 \} >polar .s
+\textbf{\{ 6.403124237432849 0.8960553845713439 \}}
+\end{alltt}
+
+A new complex number can be created from an absolute value and argument using \texttt{polar> ( abs arg -{}- z )}.
+
+\begin{alltt}
+\textbf{ok} 1 pi polar> .
+\textbf{\#\{ -1.0 1.224606353822377e-16 \}}
+\end{alltt}
+
+\subsection{Transcedential functions}
+
+\chapkeywords{\^{} exp log sin cos tan asin acos atan sec cosec cot asec acosec acot sinh cosh tanh asinh acosh atanh sech cosech coth asech acosech acoth}
+
+The \texttt{math} vocabulary provides a rich library of mathematical functions that covers exponentiation, logarithms, trigonometry, and hyperbolic functions. All functions accept and return complex number arguments where appropriate. These functions all return floating point values, or complex numbers whose real and imaginary components are floating point values.
+
+\texttt{\^{} ( x y -- x\^{}y )} raises \texttt{x} to the power of \texttt{y}. In the cases of \texttt{y} being equal to $1/2$, -1, or 2, respectively, the words \texttt{sqrt}, \texttt{recip} and \texttt{sq} can be used instead.
+
+\begin{alltt}
+\textbf{ok} 2 4 \^ .
+\textbf{16.0}
+\textbf{ok} i i \^ .
+\textbf{0.2078795763507619}
+\end{alltt}
+
+All remaining functions have a stack effect \texttt{( x -{}- y )}, it won't be repeated for brevity.
+
+\texttt{exp} raises the number $e$ to a specified power. The number $e$ can be pushed on the stack with the \texttt{e} word, so \texttt{exp} could have been defined as follows:
+
+\begin{alltt}
+: exp ( x -- e^x ) e swap \^ ;
+\end{alltt}
+
+However, it is actually defined otherwise, for efficiency.\footnote{In fact, the word \texttt{\^{}} is actually defined in terms of \texttt{exp}, to correctly handle complex number arguments.}
+
+\texttt{log} computes the natural (base $e$) logarithm. This is the inverse of the \texttt{exp} function.
+
+\begin{alltt}
+\textbf{ok} -1 log .
+\textbf{\#\{ 0.0 3.141592653589793 \}}
+\textbf{ok} e log .
+\textbf{1.0}
+\end{alltt}
+
+\texttt{sin}, \texttt{cos} and \texttt{tan} are the familiar trigonometric functions, and \texttt{asin}, \texttt{acos} and \texttt{atan} are their inverses.
+
+The reciprocals of the sine, cosine and tangent are defined as \texttt{sec}, \texttt{cosec} and \texttt{cot}, respectively. Their inverses are \texttt{asec}, \texttt{acosec} and \texttt{acot}.
+
+\texttt{sinh}, \texttt{cosh} and \texttt{tanh} are the hyperbolic functions, and \texttt{asinh}, \texttt{acosh} and \texttt{atanh} are their inverses.
+
+Similarly, the reciprocals of the hyperbolic functions are defined as \texttt{sech}, \texttt{cosech} and \texttt{coth}, respectively. Their inverses are \texttt{asech}, \texttt{acosech} and \texttt{acoth}.
+
+\subsection{Modular arithmetic}
+
+\chapkeywords{/i mod /mod gcd}
+
+In addition to the standard division operator \texttt{/}, there are a few related functions that are useful when working with integers.
+
+\texttt{/i ( x y -{}- x/y )} performs a truncating integer division. It could have been defined as follows:
+
+\begin{alltt}
+: /i / >integer ;
+\end{alltt}
+
+However, the actual definition is a bit more efficient than that.
+
+\texttt{mod ( x y -{}- x\%y )} computes the remainder of dividing \texttt{x} by \texttt{y}. If the result is 0, then \texttt{x} is a multiple of \texttt{y}.
+
+\texttt{/mod ( x y -{}- x/y x\%y )} pushes both the quotient and remainder.
+
+\begin{alltt}
+\textbf{ok} 100 3 mod .
+\textbf{1}
+\textbf{ok} -546 34 mod .
+\textbf{-2}
+\end{alltt}
+
+\texttt{gcd ( x y -{}- z )} pushes the greatest common divisor of two integers; that is, the largest number that both integers could be divided by and still yield integers as results. This word is used behind the scenes to reduce rational numbers to lowest terms when doing ratio arithmetic.
+
+\subsection{Bitwise operations}
+
+\chapkeywords{bitand bitor bitxor bitnot shift}
+
+There are two ways of looking at an integer -- as a mathematical entity, or as a string of bits. The latter representation faciliates the so-called \emph{bitwise operations}.
+
+\texttt{bitand ( x y -{}- x\&y )} returns a new integer where each bit is set if and only if the corresponding bit is set in both $x$ and $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-and with a mask switches off all flags that are not explicitly set in the mask.
+
+\begin{alltt}
+BIN: 101 BIN: 10 bitand .b
+\emph{0}
+BIN: 110 BIN: 10 bitand .b
+\emph{10}
+\end{alltt}
+
+\texttt{bitor ( x y -{}- x|y )} returns a new integer where each bit is set if and only if the corresponding bit is set in at least one of $x$ or $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-or with a mask switches on all flags that are set in the mask.
+
+\begin{alltt}
+BIN: 101 BIN: 10 bitor .b
+\emph{111}
+BIN: 110 BIN: 10 bitor .b
+\emph{110}
+\end{alltt}
+
+\texttt{bitxor ( x y -{}- x\^{}y )} returns a new integer where each bit is set if and only if the corresponding bit is set in exactly one of $x$ or $y$. If you're considering an integer as a sequence of bit flags, taking the bitwise-xor with a mask toggles on all flags that are set in the mask.
+
+\begin{alltt}
+BIN: 101 BIN: 10 bitxor .b
+\emph{111}
+BIN: 110 BIN: 10 bitxor .b
+\emph{100}
+\end{alltt}
+
+\texttt{bitnot ( x -{}- y )} returns the bitwise complement of the input; that is, each bit in the input number is flipped. This is actually equivalent to negating a number, and subtracting one. So indeed, \texttt{bitnot} could have been defined as thus:
+
+\begin{alltt}
+: bitnot neg pred ;
+\end{alltt}
+
+\texttt{shift ( x n -{}- y )} returns a new integer consisting of the bits of the first integer, shifted to the left by $n$ positions. If $n$ is negative, the bits are shifted to the right instead, and bits that ``fall off'' are discarded.
+
+\begin{alltt}
+BIN: 101 5 shift .b
+\emph{10100000}
+BIN: 11111 -2 shift .b
+\emph{111}
+\end{alltt}
+
+The attentive reader will notice that shifting to the left is equivalent to multiplying by a power of two, and shifting to the right is equivalent to performing a truncating division by a power of two.
+
+\end{document}
projects / factor.git / commitdiff