Contents
Introduction
Chapter 1
 SETTING UP THE ACE
Chapter 2
 SETTING UP THE ACE
Chapter 3
 LOADING PROGRAMS FROM TAPE
Chapter 4
 DEFINING NEW WORDS
Chapter 5
 SIMPLE ARITHMETIC
Chapter 6
 DEFINING NEW ARITHMETIC WORDS
Chapter 7
 ALTERING WORD DEFINITIONS
Chapter 8
 WORDS THAT ARE REALLY NUMBERS
Chapter 9
 MAKING DECISIONS
Chapter 10
 REPEATING
Chapter 11
 SOUND
Chapter 12
 THE CHARACTER SET
Chapter 13
 PLOTTING GRAPHS
Chapter 14
 SAVING PROGRAMS ON TAPE
Chapter 15
 FRACTIONS AND DECIMAL POINTS
Chapter 16
 READING THE KEYBOARD
Chapter 17
 OTHER WAYS OF COUNTING
Chapter 18
 BOOLEAN OPERATIONS
Chapter 19
 MORE ADVANCED ARITHMETIC
Chapter 20
 INSIDE THE DICTIONARY
Chapter 21
 STRINGS AND ARRAYS
Chapter 22
 VOCABULARIES
Chapter 23
 INSIDE COLON DEFINITIONS
Chapter 24
 HOW THE MEMORY IS LAID OUT
Chapter 25
 MACHINE CODE
Chapter 26
 EXTENDING THE ACE
Appendix A
 QUICK GUIDE FOR 'FORTH' ENTHUSIASTS
Appendix B
 ERRORS
Appendix C
 THE JUPITER ACE - FOR REFERENCE
Appendix D
 QUICK GUIDE FOR 'FORTH' ENTHUSIASTS
INDEX

Chapter 6

DEFINING NEW ARITHMETIC WORDS

Now you know about +, -, * and so on, you have quite a number of building blocks for defining new words. For instance, here is a word to double a number and print the answer:

: DOUBLE
  2 * .
;

So where's this number that DOUBLE doubles? Answer - it must already be on the stack when you use DOUBLE. If you want to double 23, you type

23 DOUBLE

We can follow the stack all through this:

DOUBLE dose —

. Prints 46

 On balance, then DOUBLE takes a number off the stack, and it's important to realise that FORTH words are quite entitled to do this. A word takes some numbers off the stack (these are its operands, the numbers it operates on) and leaves some on the stack when it has finished (these are its results), but there is nothing to say that the number of operands must match the number of results.
 For instance,

 + has two operands (the two numbers that it adds together) and one result (their sum).

 . has one operand (the number to be printed) and no results (because when the number has been printed it just gets thrown away).

DOUBLE has one operand (the number to be doubled) and no results.

/MOD has two operands (the two numbers to be divided) and two results (the remainder and quotient).

 You could think of the number 2 as having no operands, and one result (2).

All this explains more precisely our statement in Chapter 2 that you first gather together the numbers you're interested in, and then do the calculations. The 'numbers you're interested in' are the operands, and they are gathered together by being put on the stack.
 There are some more words that are just concerned with moving numbers about on the stack, the simplest three being SWAP, DUP (for duplicate) and DROP.

SWAP swaps round the top two numbers on the stack, so that it changes

(Of course, the actual cards will have numbers written on them instead of K and Q; but I don't know what the numbers are going to be so I've written K and Q instead.)

DUP duplicates the top of the stack - it makes an extra copy of it - changing

DROP takes one number off the top of the stack and throws it away, changing

But it only takes off one number, so for two or more it changes

 Here is a word SQ that works out the square of a number (the number multiplied by itself). It doesn't print out the answer, so it has one operand (the original number) and one result (its square), changing

↑ ↑

operand cardresult card

 Again, in real life the operand card will have a number written on it instead of K; and 'K*K' is just a symbolic way of showing that the result will be that number multiplied by itself.  The definition of SQ is

which you can test with examples like

6 SQ .

(Work out how the stack changes as SQ is obeyed.)  Rather than drawing pictures of cards all the time, we shall use a notation that sets it all on one line, replacing the card diagram

by the line (K — K*K)

↑ ↑

operandresult

 If a word has more than one operand or result then we list them all. For instance, for /MOD

(K,Q - remainder of K ÷ Q, quotient of K ÷ Q)

↑ ↑ ↑ ↑

operandtop operand result top result

second from topon stack second from top on stack

 When listing either the operands or the results, the top of the stack comes last. In cards, the change is from

lowest is listed first

top is listed last

It's essential to know exactly what operands each word expects to find on the stack, and what results it leaves at the end, so it's a good idea to build this information into the word definition itself. You do this using comments — anything enclosed in round brackets is a comment, there purely for your benefit, and ignored by the computer when it executes the word. Here is a definition of SQ that uses a comment to show how SQ affects the stack.

: SQ The computer ignores
  ( K - K*K) ← this line when it
DUP * executes SQ
;

 You can put comments in anywhere between the name of the new word and the semicolon, and they don't have to describe the stack — they can say anything you like to help you remember what you meant when you defined the word. The first round bracket, (, needs a space after it because it is itself a FORTH word (meaning 'here comes a comment'). Remember that you can't have a ) actually inside the comment, because it means 'end of comment'.
 One problem with comments is that they take up extra space in the computer's memory: so if you ever get ERROR 1 (which means the memory is full), the first thing to do is to start taking comments out. The usual method is to leave the comments in until you've got the word working properly. When you get round to saving words on tape (chapter 14) you'll often find it useful to save two versions: one with comments, just for reference, and one without, for actual use. When you type in examples from this manual, you'd as likely as not bother to include the comments at all -- after all, they're written down on paper in front of you. But with your own programs you'll definitely find comments useful.
 ( behaves rather like ." in that you can't use it outside a word definition. If you forget the ), you get ? Which gives you a chance to put it in.
 When you've typed in this new version of SQ, VLIST will show you that both SQs are still in the dictionary. Don't worry about this; the computer will always use the newest definition. The next chapter will tell you how to get rid of the old version. In summary, FORTH words take their operands from the top of the stack and leave their results on the stack.

DUP (K — K,K) duplicates the top number on the stack.

DROP (K — ) throws away the top number on the stack.

SWAP (K,Q Q,K) swaps the top two numbers on the stack.

  ( ( — ) (by which we show that it doesn't affect the stack) starts off a comment. The comment is ended by ).

  There are some more words to manipulate the stack, which I shall put here for reference.

OVER (K,Q — K,Q,K) brings a copy of the second from top to the top.

ROT (K,Q,J — Q,J,K) rotates the top three, bringing the third one down up to the top.

PICK (n — K) takes a number (we have written n for it) off the top, and makes a copy of the nth one down from the top of the stack in what remains, leaving this copy on the top. For instance, PICK changes

because J is the third one down in

by rotating the four cards

Exercises

1. Define a word to take a price including VAT off the stack, and return as result the VAT paid. (See Exercise 1 in the previous chapter. Check that it gives the right answer for £89.95.)

2. Convince yourself that the following are true:

1 PICK is the same as DUP
2 PICK is the same as OVER
1 ROLL does nothing
2 ROLL is the same as SWAP
3 ROLL is the same as ROT