Forth v4.4 Function Glossary (E-O)

This glossary provides detailed definitions for the general purpose words (Forth functions) available in the v4.4 Forth kernel. Separate glossaries define the assembler and C debugging words available. A separate page lists all the Forth V4.4 Functions that Disable Interrupts.

For help in understanding the notation used in the following function definitions, consult the description of stack symbols, abbreviations and naming conventions.

This glossary is split into three web pages, for words beginning with the following characters (in ASCII alphabetical) order:

ELSE ( -- )

Used in a colon definition to mark the beginning of the "else portion" of an IF … ELSE … ENDIF conditional structure (ENDIF and THEN are synonyms). Use as:

flag IF   words to execute if flag is true
ELSE       words to execute if flag is false
ENDIF

If the flag passed to IF is true, when ELSE is encountered control is passed to the word following ENDIF. If the flag passed to IF is FALSE, control is immediately passed to the word following ELSE.

Attributes: C, I

EMIT ( char -- )

Displays char by sending it via the serial I/O port. EMIT is a vectored routine that executes the routine whose xcfa is installed in the user variable UEMIT. The default installed routine called is EMIT1 which sends the character via the primary serial port (supported by the 68HC11's hardware UART). EMIT2 may be installed in UEMIT by USE.SERIAL2 or SERIAL2.AT.STARTUP; EMIT2 sends the character via the secondary serial port (supported by QED Forth's software UART and using pins PA3 and PA4).

See also EMIT1 and EMIT2

Attributes: M, U

EMIT1 ( char -- )

Displays a character by sending it via the primary serial port (serial1) associated with the 68HC11's on-chip hardware UART. Before sending the character, EMIT1 waits (if necessary) for the previous character to be sent, and executes PAUSE while waiting. The most significant byte of the input data stack cell is ignored. EMIT1 is the default EMIT routine installed in the UEMIT user variable after the special cleanup mode is invoked or if SERIAL1.AT.STARTUP has been executed. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, EMIT1 does not GET or RELEASE the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT1 GETs and RELEASEs the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, EMIT1 GETs but does not RELEASE the SERIAL1.RESOURCE.

See also EMIT, UEMIT, EMIT2, SERIAL.ACCESS
Pronunciation: "emit-one"
Attributes: M

EMIT2 ( char -- )

Writes the specified ascii character to the output buffer of the secondary serial port (serial2) for subsequent transmission. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). If the serial2 transmitter is idle (and if the serial2 port and its interrupts have been properly initialized) then the character is transmitted immediately. Otherwise the character will be transmitted after the prior characters in the output buffer are transmitted. If the 80 character output buffer is full when EMIT2 is executed, EMIT2 PAUSEs and waits until room becomes available in the buffer (as a result of a character being sent out). The most significant byte of the input data stack cell is ignored. EMIT2 can be made the default EMIT routine installed in the UEMIT user variable after each reset or restart by executing SERIAL2.AT.STARTUP. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, EMIT2 does not GET or RELEASE the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT2 GETs and RELEASEs the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, EMIT2 GETs but does not RELEASE the SERIAL2.RESOURCE.

See also EMIT, UEMIT, EMIT1, SERIAL.ACCESS
Pronunciation: "emit-two"
Attributes: M

ENABLE.DOWNLOAD ( -- )

If the download map is set, this function does nothing. If the standard map is set, this command prepares for a code download by copying pages 4, 5, and 6 to RAM, then setting the download map. When combined with ALL.TO.FLASH, this function ensures that an application program up to 96 Kbytes long compiled on pages 4, 5, and 6 is properly transferred to flash after a download. Usage: When paired with the ALL.TO.FLASH command, this function simplifies the loading of a Forth program. Place the ENABLE.DOWNLOAD command at the top of the first file to be loaded, and place ALL.TO.FLASH at the end of the last file to be loaded. This ensures proper compilation of code into RAM pages 4, 5 and 6 in the download map, followed by transfer to flash and setting of the standard map. It is also possible to put ENABLE.DOWNLOAD at the top of each source code file, and ALL.TO.FLASH at the bottom of each source file. This technique ensures proper compilation of any given source code file during the development process. Of course, this command may also be typed at the QED-Forth prompt before code is downloaded.

ENABLE.INTERRUPTS ( -- )

Clears the interrupt mask bit (the "I bit") in the condition code register to globally enable interrupts.

END-CODE ( sys -- | balances CODE )

Terminates an assembly code definition which started with CODE. Executes SMUDGE so that the header created by CODE can be found in the dictionary. Checks to make sure that no extra items were left on the stack during the definition process. Stores the contents of CURRENT into CONTEXT so that ASSEMBLER is no longer the search vocabulary.
Pronunciation: "end-code"
Synonym for: END.CODE

END.CODE ( sys -- | balances CODE )

Terminates an assembly code definition which started with CODE. Executes SMUDGE so that the header created by CODE can be found in the dictionary. Checks to make sure that no extra items were left on the stack during the definition process. Stores the contents of CURRENT into CONTEXT so that ASSEMBLER is no longer the search vocabulary.

Pronunciation: "end-code"
Synonym for: END-CODE

ENDCASE ( n -- )

Used inside a colon definition to mark the end of a CASE statement which implements a multi-decision control structure. Use as:

n1 CASE
   n2 OF words to be executed if n1 = n2       ENDOF
   n3 OF words to be executed if n1 = n3       ENDOF
   n4 OF words to be executed if n1 = n4       ENDOF
   words to be executed if n1 doesn't equal n2 or n3 or n4
ENDCASE

An error is issued if CASE and ENDCASE are not properly paired in a definition.

See also CASE, OF, ENDOF, RANGE.OF, and URANGE.OF
Pronunciation: "end-case"
Attributes: C, I

ENDIF ( -- )

Synonym for THEN. Used inside a colon definition to mark the end of an

  IF ... ELSE ... ENDIF

or IF … ENDIF

conditional structure. The word following ENDIF is executed after the IF or ELSE (if present) part of the conditional executes. An error is issued if ENDIF is not paired with IF or ELSE in a colon definition.
Pronunciation: "end-if"
Attributes: C, I

ENDIFTRUE ( -- )

Marks the end of a conditional structure that is used outside a colon definition. Use as:

flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

or

flag  IFTRUE ....  ENDIFTRUE

The execution mode conditional structure can be used to conditionally compile portions of source code. Note that IFTRUE/OTHERWISE/ENDIFTRUE statements can not be nested.

See also IFTRUE and OTHERWISE
Pronunciation: "end-if-true"

ENDOF ( -- )

Used inside a CASE … ENDCASE structure to mark the end of a conditional statement that starts with OF or RANGE.OF or URANGE.OF. If the OF portion of the case statement is true, ENDOF branches to the word after ENDCASE. An error is issued if OF and ENDOF are not properly paired.

See also CASE, ENDCASE, OF, RANGE.OF, and URANGE.OF
Pronunciation: "end-of"
Attributes: C, I

ERASE ( xaddr\u -- | u = byte count )

Stores a zero byte in each of u consecutive bytes beginning at xaddr. The specified region may cross page boundaries. Does nothing if u = 0.

EVALUATE ( x$addr -- )

Interprets the counted string located at x$addr. Use as:

" <words to be executed>" EVALUATE

The string need not end with a space. EVALUATE provides one method of compiling a reference to a word that has not yet been defined. For example,

: EARLY.WORD
   ...
   " INITIALIZE.EVERYTHING" EVALUATE
   ...
;

Even though the routine INITIALIZE.EVERYTHING has not yet been defined, EARLY.WORD will call it if INITIALIZE.EVERYTHING has been defined by the time EARLY.WORD is finally executed at runtime. Note that EVALUATE must search the dictionary at runtime to be able to execute INITIALIZE.EVERYTHING. For a more efficient means of implementing forward references.

Implementation detail: EVALUATE saves the contents of the input stream variables UTIB, #TIB, >IN, and BLK, then sets these variables to reference the specified x$addr, then calls INTERPRET, and finally restores the original values to the input stream variables.

See also REDEFINE

EXECUTE ( xcfa -- )

Executes (calls) the routine whose executable machine instructions begin at the specified code field xaddress. The xcfa can be on any page.

EXIT ( -- )

Specifies a termination point in a definition. EXIT is an immediate word that compiles code that, when later executed, clears the locals off the return stack (if present), and pops the top value off the return stack and returns control to the calling word. When compiled into a definition, EXIT causes the word to terminate at that point when the word is later executed. An unchecked (and usually severe) error occurs if the return stack does not hold a valid return address (for example, if EXIT is used between >R and R> or inside a DO…LOOP or FOR…NEXT loop). To exit a definition from inside a single DO…LOOP, execute UNLOOP (which removes and drops 2 items from the rstack) to discard the loop index and limit from the return stack before calling EXIT. One UNLOOP is needed for each nested DO… LOOP. To exit a definition from inside a FOR…NEXT loop, call R>DROP to discard the loop index before calling EXIT. One R>DROP is needed for each nested FOR…NEXT.

Attributes: C, I

EXPECT ( xaddr\+n -- )

Receives a string of characters from the serial port and stores them in a buffer in memory starting at xaddr. Terminates when +n characters have been received or a carriage return occurs, whichever occurs first. Characters are echoed via the serial port. The carriage return is neither saved in the buffer nor echoed. Tab characters are echoed; however, they are saved in the buffer as TAB.WIDTH spaces. The backspace or delete character (ascii 8 or 127) removes the most recently received character from the buffer unless there are no characters in the buffer. Null characters (ascii 0) and linefeeds (ascii 10) are ignored. XON and XOFF characters are ignored except that they cause the XMIT.DISABLE flag in the user area to be set if XOFF is received or cleared if XON is received. Character case is not altered. The user variable SPAN is set equal to the number of characters received (but not including the terminating carriage return, if present). EXPECT is called by QUERY to accept serial input to the TIB.

Attributes: M

F! ( r\xaddr -- )

Stores a floating point number at xaddr. A synonym for 2!.
Pronunciation: "f-store"

F* ( r1\r2 -- r3 )

Multiplies floating point number r1 by r2 giving r3.
Pronunciation: "f-star"
Attributes: S

F** ( r1\r2 -- r3 )

r3 equals r1 raised to the r2 power; i.e., r3 = r1^r2. Overflows if r1 is negative.
Pronunciation: "f-star-star"
Attributes: S

F*/COUNTER ( -- xaddr )

A user variable that holds a 16 bit counter that is incremented with each call to F* or F/. Used by the BENCHMARK: and (BENCHMARK:) routines.
Pronunciation: "f-star-slash-counter"
Attributes: U

F+ ( r1\r2 -- r3 )

Adds floating point number r2 to r1 giving the sum r3.
Pronunciation: "f-plus"
Attributes: S

F+COUNTER ( -- xaddr )

A user variable that holds a 16 bit counter that is incremented with each call to F+ or F-. Used by the BENCHMARK: and (BENCHMARK:) routines.
Pronunciation: "f-plus-counter"
Attributes: U

F- ( r1\r2 -- r3 )

Subtracts floating point number r2 from r1 giving the difference r3.
Pronunciation: "f-minus"
Attributes: S

F. ( r -- )

Displays r using the default format as specified by the most recent execution of FIXED FLOATING or SCIENTIFIC. FLOATING is the default format after executing FP.DEFAULTS or after a cold restart.

See also F>FIXED$, F>SCIENTIFIC$, and F>FLOATING$
Pronunciation: "f-dot"
Attributes: M, S

F.OVER.N ( r\w -- r\w\r )

Copies the floating point value r located under the top data stack cell to the top of the data stack.
Pronunciation: "f-over-n"

F/ ( r1\r2 -- r3 )

Divides floating point number r1 by r2 giving the result r3.
Pronunciation: "f-slash"
Attributes: S

F0< ( r -- flag )

Flag is TRUE if floating point number r is less than zero, FALSE otherwise.
Pronunciation: "f-zero-less-than"

F0<= ( r -- flag )

Flag is TRUE if floating point number r is less than or equal to 0, FALSE otherwise.
Pronunciation: "f-zero-less-than-or-equal"

F0<> ( r -- flag )

Flag is TRUE if the floating point number is not equal to zero, and FALSE otherwise.
Pronunciation: "f-zero-not-equal"

F0= ( r -- flag )

Flag is TRUE if the floating point number equals zero and FALSE otherwise.
Pronunciation: "f-zero-equal"

F0> ( r -- flag )

If floating point number r is greater than zero, flag equals TRUE; otherwise, flag equals FALSE.
Pronunciation: "f-zero-greater-than"

F0>= ( r -- flag )

Flag is TRUE if floating point number r is greater than or equal to 0, FALSE otherwise.
Pronunciation: "f-zero-greater-than-or-equal"

F2* ( r1 -- r2 )

Floating point number r2 equals r1 * 2.
Pronunciation: "f-two-star"
Attributes: S

F2/ ( r1 -- r2 )

Floating point number r2 equals r1 divided by 2.
Pronunciation: "f-two-slash"
Attributes: S

F2DROP ( r1\r2 -- )

Drops two floating point numbers (4 cells) from the data stack.
Pronunciation: "f-two-drop"

F2DUP ( r1\r2 -- r1\r2\r1\r2 )

Duplicates the top two floating point numbers on the data stack.
Pronunciation: "f-two-dupe"

F< ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than r2, FALSE otherwise.
Pronunciation: "f-less-than"

F<= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than or equal to r2.
Pronunciation: "f-less-than-or-equal"

F<> ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are not equal and FALSE otherwise.
Pronunciation: "f-not-equal"

F= ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are equal and FALSE otherwise.
Pronunciation: "f-equal"

F> ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than r2, FALSE otherwise.
Pronunciation: "f-greater-than"

F>= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than or equal to r2.
Pronunciation: "f-greater-than-or-equal"

F>FIXED$ ( r -- x$addr\flag )

Converts r to a counted ascii string starting at x$addr in FIXED format. If the conversion is successful, flag is TRUE. If r cannot be represented as an ascii string in FIXED format (i.e., if the values of LEFT.PLACES and RIGHT.PLACES are inappropriate) then x$addr contains the string "won'tfit" and flag is false. The FIXED format is composed of (an optional) sign, LEFT.PLACES digits, a decimal point, RIGHT.PLACES digits, and a trailing space:

-xxx.yyy

If the NO.SPACES flag is false (the default condition), the field size equals LEFT.PLACES + RIGHT.PLACES + 3 and numbers are decimal aligned. The size of the string is clamped to a maximum of 32 characters. Setting TRAILING.ZEROS true displays all trailing zeros to the right of the decimal point to a maximum of RIGHT.PLACES.
Pronunciation: "f-to-fixed-string"
Attributes: S

F>FLOATING$ ( r -- x$addr\true )

Converts r to an ascii string at x$addr using FLOATING format which selects FIXED format unless the number can be displayed with greater resolution using scientific notation, in which case SCIENTIFIC format is used (using F>FIXED$ and F>SCIENTIFIC$). If FILL.FIELD if OFF (the default condition), the string is displayed using the minimum possible field size, and numbers are not decimal aligned. If FILL.FIELD is ON, the field size of the string is always equal to the scientific field size, which is MANTISSA.PLACES + 8, and numbers are decimal aligned for neat display of tabular data. The string includes a trailing space unless NO.SPACES is true. The flag on top of the stack is always true because any valid floating point number can be represented in the FLOATING format.
Pronunciation: "f-to-floating-string"
Attributes: S

F>R ( r -- )

Return Stack: ( R: – r )

Transfers the top floating point number on the data stack to the return stack.
Pronunciation: "f-to-r"
Attributes: C

F>SCIENTIFIC$ ( r -- x$addr\true )

Converts r into a text string at x$addr using SCIENTIFIC format. The format is: (an optional) sign, single digit, decimal point, MANTISSA.PLACES digits, E, exponent sign, 2-digit exponent, and a trailing space:

-1.xxxxE-yy

The field size is equal to MANTISSA.PLACES + 8. The string includes a trailing space unless NO.SPACES is true. The flag on top of the stack is always true because any valid floating point number can be represented in the SCIENTIFIC format.
Pronunciation: "f-to-scientific-string"
Attributes: S

F@ ( xaddr -- r )

Fetches a floating point number from xaddr. A synonym for 2@.
Pronunciation: "f-fetch"

FABS ( r1 -- r2 )

r2 is the absolute value of r1. If floating point number r1 is negative, applies FNEGATE to r1 giving the positive number r2; otherwise, r2 = r1.
Pronunciation: "f-abs"
Attributes: S

FACOS ( r1 -- r2 )

r2 is the arc-cosine of r1. r2 is expressed in radians.
Pronunciation: "f-a-cos"
Attributes: S

FALN ( r1 -- r2 )

r2 equals the natural anti-log of r1; i.e., r2 = e^r1.
Pronunciation: "f-a-l-n"
Attributes: S

FALOG10 ( r1 -- r2 )

r2 equals the base 10 anti-log of r1; i.e., r2 = 10^r1.
Pronunciation: "f-a-log-ten"
Attributes: S

FALOG2 ( r1 -- r2 )

r2 equals the base 2 anti-log of r1; i.e., r2 = 2^r1.
Pronunciation: "f-a-log-two"
Attributes: S

FALSE ( -- flag | flag = 0 )

Puts a boolean false flag equal to 0 on the data stack .

FASIN ( r1 -- r2 )

r2 is the arcsine of r1. r2 is expressed in radians.
Pronunciation: "f-a-sine"
Attributes: S

FATAN ( r1 -- r2 )

r2 is the arctangent of r1. r2 is expressed in radians.
Pronunciation: "f-a-tan"
Attributes: S

FCONSTANT ( r <name> -- )

Removes the next <name> from the input stream and defines a child word called <name> which when executed leaves the floating point value r on the data stack. r is stored in the definitions area of the dictionary. <name> is referred to as an "fconstant". Use as:

r FCONSTANT <name>

Pronunciation: "f-constant"
Attributes: D

FCOS ( r1 -- r2 )

r2 is the cosine of r1. r1 is expressed in radians.
Pronunciation: "f-cos"
Attributes: S

FDROP ( r -- )

Drops a floating point number (two cells) from the data stack.
Pronunciation: "f-drop"

FDUP ( r -- r\r )

Duplicates the top floating point number (two cells) on the data stack.
Pronunciation: "f-dupe"

FDUP>R ( r -- r )

Return Stack: ( R: – r )

Copies the top floating point number on the data stack to the return stack.
Pronunciation: "f-dup-to-r"
Attributes: C

FFT ( matrix.xpfa -- )

Computes the FFT (Fast Fourier Transform) of the complex floating point data in the source matrix specified by matrix.xpfa and stores the transformed result in the source matrix. The source matrix must be dimensioned to have 2 rows with 1 column per input data point. The number of columns must be a power of 2. Row#0 holds the floating point number representing the real part of each data point, and row#1 holds the floating point number representing the imaginary part of each data point (i.e., the part of the complex number that is multiplied by the imaginary operator which is the square root of -1). Each data point typically indicates a complex value of the input in the time or spatial domain. FFT transforms the input into a complex waveform in the frequency domain and stores the results in the source matrix. The maximum number of complex data points (columns) that can be transformed is 8192. To perform the inverse FFT, use IFFT.

Interpretation of results:

Assume that the input waveform spans T seconds. Then column#0 of the transformed signal corresponds to a frequency of 0, column #1 corresponds to a frequency of 1/T, column#2 corresponds to 2/T, etc. up to a maximum frequency of (plus or minus) N/2T where N is the number of points (columns) in the input waveform. After the midway point (N/2), the frequencies are negative. That is, the last point at column# N-1 corresponds to a frequency of -1/T, the next to last point at column# N-2 corresponds to -2/T, etc. If a given frequency component has a magnitude of A in the time domain, it is transformed into a spike with magnitude A*N in the frequency domain.
Pronunciation: "f-f-t"
Attributes: S

FIELD ( u <name> -- )

Defines a field constant <name> which when executed adds u to the extended address on the top of the data stack. <name>'s stack picture is ( xaddr – xaddr + u ). It is recommended that <name> begin with a + to suggest its runtime behavior of adding the offset u to the top data stack item. FIELD is the low level word called by all of the words that create members in structures.

See also MEMBER→ 

Attributes: D

FILL ( xaddr\u\b -- | u = byte count, b = fill value )

The specified byte b is stored in each of u consecutive addresses beginning at xaddr. The specified region may cross page boundaries. Does nothing if u = 0.

See also FILL.MANY

FILL.ARRAY ( array.xpfa\char -- )

Stores char into each byte of the specified array.

FILL.FIELD ( -- xaddr )

A user variable that contains a flag. If the flag is true, floating point numbers printed in FLOATING format are padded with spaces to yield a constant field width irrespective of whether the number is printed in scientific notation or fixed notation, and numbers printed in fixed notation are decimal aligned. This leads to neat printouts of tabular data. If the flag is false, the field width is not padded out.

See also F>FLOATING$

Attributes: U

FILL.MANY ( xaddr\d\b -- | d = byte count, b = fill value )

The specified byte b is stored in each of d consecutive addresses beginning at xaddr. The specified region may cross page boundaries. Does nothing if d = 0.

FIND ( <name> -- [ xcfa\flag ] or [ 0 ] )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word. FIND first searches the CONTEXT vocabulary. Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary. If the word is not found in the dictionary, FIND leaves a 0 on the stack. If the word is found, FIND leaves the word's extended code field address under a flag on the stack. The flag is +1 if the word is immediate and -1 if the word is not immediate. An error occurs if the input stream is exhausted while WORD executes. A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary. This prevents the interpreter from going on an infinite search through a corrupted dictionary. Find also invokes a COLD restart if POCKET is not in common memory.

FINT ( r1 -- r2 )

If the absolute value of r1 is less than 2^31, r2 is the floating point representation of the integer part (truncated toward zero) of r1. For these numbers, FINT is the equivalent of DINT DFLOT. If the absolute value of r1 exceeds 2^31, FINT returns r2 = r1 and sets the OVERFLOW flag.
Pronunciation: "f-int"

FIRST ( -- xaddr )

Returns the extended address of the lower boundary of the block buffers; that is, the address of the first byte of the first block buffer. Equivalent to UFIRST X@ . Initialized by BLOCK.BUFFERS.

Attributes: U

FIXED ( -- )

Sets the default printing format used by F. to fixed. Numbers are decimal aligned, and RIGHT.PLACES and LEFT.PLACES determine the field width.

See also F>FIXED$

FIXED. ( r -- )

Prints r using FIXED format. Does not change the default printing format.

See also F>FIXED$
Pronunciation: "fixed-dot"
Attributes: M, S

FIXX ( r -- n )

Rounds r to the nearest integer n. OVERFLOW is set if needed.

See also DFIXX

Attributes: S

FLN ( r1 -- r2 )

r2 is the natural logarithm of r1.
Pronunciation: "f-l-n"
Attributes: S

FLOATING ( -- )

Sets the default printing format used by F. to floating. The floating format uses FIXED format if the number can be represented with the same or more significant digits as it would if it were represented in SCIENTIFIC format. Otherwise, it uses SCIENTIFIC format.

See also F>FLOATING$

FLOATING. ( r -- )

Prints r using FLOATING format.

See also F>FLOATING$
Pronunciation: "floating-dot"
Attributes: M, S

FLOG10 ( r1 -- r2 )

r2 is the base 10 logarithm of r1.
Pronunciation: "f-log-ten"
Attributes: S

FLOG2 ( r1 -- r2 )

r2 is the base 2 logarithm of r1.
Pronunciation: "f-log-two"
Attributes: S

FLOOR ( r1 -- r2 )

r2 is the floating point representation of the greatest integer less than or equal to r1.

Attributes: S

FLOT ( n -- r )

Converts the 16 bit integer n to its floating point representation r.

See also DFLOT
Pronunciation: "float"
Attributes: S

FMAX ( r1\r2 -- [r1] or [r2] )

Retains the greater of r1 and r2.
Pronunciation: "f-max"

FMIN ( r1\r2 -- [r1] or [r2] )

Retains the lesser of r1 and r2.
Pronunciation: "f-min"

FNEGATE ( r1 -- r2 )

r2 is the negative of r1.
Pronunciation: "f-negate"

FNUMBER ( x$addr -- [r\-1] or [0] )

Attempts to convert the space-delimited counted ascii string at x$addr into a valid floating point number r. Returns r under a true flag if the conversion is successful; otherwise returns a false flag. x$addr is the address of the text string's count byte. The string at x$addr must end with a blank; the blank may or may not be included in the count. Strings parsed by the commands BL WORD obey this rule.

See also NUMBER
Pronunciation: "f-number"
Attributes: S

FOR ( u1 -- )

Return Stack: ( R: – u1 )

Used inside a colon definition to mark the beginning of a count-down loop structure that is terminated by NEXT. Sets up loop index u1 on the return stack. Use as:

u1     FOR  <words to be executed u1+1 times>
   NEXT

0 FOR…NEXT executes 1 time, 1 FOR…NEXT executes 2 times, 65,535 FOR…NEXT executes 65,536 times, etc. Because the loop index is maintained on the return stack, caution must be exercised when using the operators >R and R> inside a loop. FOR…NEXT loops may be nested as long as each FOR is matched with a corresponding NEXT in the same definition as FOR; otherwise, an error is issued. FOR … NEXT loops execute faster than DO … LOOP constructs. The word I may be used inside a FOR NEXT loop. J K I' and LEAVE may not be used in a FOR NEXT loop.

Attributes: C, I

FORGET ( <name> -- )

Removes <name> from the input stream and searches for it in the CURRENT vocabulary. If <name> is found, deletes it from the dictionary and removes all words defined after <name> by adjusting DP, NP, and the xhandle of the CURRENT vocabulary. An error occurs if <name> is not found. FORGET does not de-allocate space in the variable area (VP is not adjusted). Use of ANEW for dictionary cleanup avoids this problem. Likewise, heap space is not de-allocated by FORGET; use of ON.FORGET solves this problem. When a word is about to be forgotten, FORGET checks if its name is ON.FORGET. Words with the name ON.FORGET are executed before being forgotten. This allows cleanup of heap items or other cleanup actions. A warning is issued if execution of FORGET leaves any of the pointers DP, NP, or VP pointing to non-RAM locations. Use this word with caution; it is possible to FORGET the entire operating system!

FORTH ( -- )

Specifies FORTH as the vocabulary to be searched first during dictionary searches. Implementation detail: stores the 32-bit xhandle of the FORTH vocabulary into the user variable CONTEXT.

FOVER ( r1\r2 -- r1\r2\r1 )

Places a copy of r1 on top of the data stack.
Pronunciation: "f-over"

FP&STRING.POP ( -- )

Return Stack: ( R: 15 cells – )

Pops off the return stack the values of the scratchpad user variables placed there by FP&STRING.PUSH and restores the popped values to the user area. Also restores PAD to the value it had before FP&STRING.PUSH executed. FP&STRING.PUSH and FP&STRING.POP are intended to be used in interrupt service routines that call floating point operations and/or floating point string conversion and/or integer string conversion operations. Execution time is approximately 113 microseconds.

See also FP&STRING.PUSH
Pronunciation: "f-p-and-string-pop"
Attributes: S

FP&STRING.PUSH ( xaddr -- | xaddr is temporary PAD )

Return Stack: ( R: – 15 cells )

Pushes onto the return stack the values of the scratchpad user variables that are modified by words that call the basic floating point operators F+ F- F* and F/ or by words that perform floating point or integer string conversion. Also installs the specified xaddr as the value of PAD. The saved items are later removed from the return stack and restored to the user area by FP&STRING.POP. FP&STRING.PUSH is intended to be used in interrupt service routines that call floating point or number/string conversion operations. FP&STRING.PUSH should be executed by the interrupt service routine before the first floating point or conversion function is called to save the scratchpad values on the return stack and to establish a temporary PAD. Executing FP&STRING.POP at the end of the interrupt service routine restores the scratchpad variables and PAD to their prior values. Using FP&STRING.PUSH and FP&STRING.POP prevents conflicts when both the foreground (i.e., non-interrupt-invoked) program and the interrupt service routine call floating point and/or string conversion operations; if the interrupt routine does not save and restore the scratchpad variables, it may corrupt a floating point or conversion operation in the foreground program. Integer and floating point string conversion use the 32 bytes below PAD for string generation, so establishing a new PAD address prevents conflicts between foreground and interrupt-invoked number conversion routines. Execution time is approximately 113 microseconds. Note that the S attribute indicates which words modify scratchpad variables. If FP&STRING.PUSH is called inside an interrupt service routine, there is no need to call FP.PUSH, since FP&STRING.PUSH saves all of the variables that FP.PUSH saves, plus additional variables.

Example of use: Assume that a foreground program is performing a matrix inversion and printing the results. This involves floating point additions and multiplications as well as number-to-string conversion. The following simple interrupt service routine would function correctly:

   FVARIABLE    LATEST.DATA
<xaddr in ram>   XCONSTANT   TEMP.PAD.XADDR
<another xaddr in ram>   XCONSTANT   STRING.DESTINATION
: INTERRUPT.SERVICE   ( -- )
   TEMP.PAD.XADDR  FP&STRING.PUSH
   LATEST.DATA F@ 2.0 F*
   F>SCIENTIFIC$ DROP   ( xaddr\cnt -- )
   >R STRING.DESTINATION R> CMOVE
   FP&STRING.POP   ;

This service routine saves the scratchpad variables on the return stack, establishes a temporary PAD, multiplies the contents of LATEST.DATA by 2.0 and converts the result to an ascii string in scientific format (this modifies the scratchpad values), moves the string to STRING.DESTINATION, and restores the scratchpad values and the original PAD before terminating so that the foreground program can proceed. Even if the foreground matrix inversion program is in the middle of a floating point or string conversion operation when an interrupt occurs, the operation is not corrupted. Note that local variables should not be used inside interrupt service routines (see LOCALS{ ).

See also FP.PUSH
Pronunciation: "f-p-and-string-push"

FP.DEFAULTS ( -- )

Initializes floating point user variables to default values. Sets the number base to DECIMAL, makes FLOATING the default print format, sets LEFT.PLACES = 4, RIGHT.PLACES = 3, MANTISSA.PLACES = 3, sets TRAILING.ZEROS, NO.SPACES, and FILL.FIELD false, and initializes MAX#DIMENSIONS to 4.
Pronunciation: "f-p-defaults"
Attributes: S

FP.ERROR ( -- xaddr )

A user variable containing a 16-bit error flag. Set by many floating point operations and by OVERFLOW and UNDERFLOW. Can be checked after any floating point operation to detect an underflow or overflow error. Contents of 0 indicates no error, 1 indicates underflow, and -1 indicates overflow.
Pronunciation: "f-p-error"
Attributes: U

FP.POP ( -- )

Return Stack: ( R: w1\w2\w3\w4\w5 – )

Pops off the return stack the values of the 5 scratchpad user variables placed there by FP.PUSH and restores the popped values to the user area. FP.PUSH and FP.POP are intended to be used in interrupt service routines that call floating point operations. Execution time is approximately 50 microseconds.

See also FP.PUSH
Pronunciation: "f-p-pop"
Attributes: S

FP.PUSH ( -- )

Return Stack: ( R: – w1\w2\w3\w4\w5 )

Pushes onto the return stack the values of the 5 scratchpad user variables that are modified by all words that call the basic floating point operators F+ F- F* and F/. The items are later removed from the return stack and restored to the user area by FP.POP. FP.PUSH is intended to be used in interrupt service routines that call floating point operations. FP.PUSH should be executed by the interrupt service routine before the first floating point function is called to save the scratchpad values on the return stack. Executing FP.POP at the end of the interrupt service routine restores the scratchpad variables to their prior values. Using FP.PUSH and FP.POP prevents conflicts when both the foreground (i.e., non-interrupt-invoked) program and the interrupt service routine call floating point operations; if the interrupt routine does not save and restore the scratchpad variables, it may corrupt a floating point operation in the foreground program. FP.PUSH saves the contents of four headerless scratchpad variables as well as the contents of FP.ERROR. Execution time is approximately 50 microseconds. Note that the S attribute indicates which words modify scratchpad variables.

Example of use:

Assume that a foreground program is performing a matrix inversion which involves floating point additions and multiplications. The following simple interrupt service routine would function correctly:

FVARIABLE    LATEST.DATA
: INTERRUPT.SERVICE   ( -- )
   FP.PUSH   \ save fp scratchpad user variables
   LATEST.DATA F@ 2.0 F*   LATEST.DATA F!
   FP.POP   \ restore fp scratchpad user variables
;

Even if the foreground matrix inversion program is in the middle of a floating point operation when an interrupt occurs, the floating point operation is not corrupted. INTERRUPT.SERVICE saves the fp scratchpad values, performs the F* (which modifies the scratchpad values) and then restores the original scratchpad values before terminating so that the foreground program can proceed. Note that local variables should not be used inside interrupt service routines (see LOCALS{ ).

See also FP&STRING.PUSH
Pronunciation: "f-p-push"

FPICK ( r\wn-1\...w1\w0\+n -- r\wn-1\...\w1\w0\r | 0 <= +n <= 255 )

Copies the floating point number whose most significant cell is the nth item on the stack (0-based, not including n) to the top of the stack. An unchecked error occurs if there are fewer than +n+2 cells on the data stack. 0 FPICK is equivalent to FDUP, 1 FPICK is equivalent to X.OVER.N, 2 FPICK is equivalent to FOVER.
Pronunciation: "f-pick"

FR> ( -- r )

Return Stack: ( R: r – )

Transfers the top floating point number on the return stack to the data stack.
Pronunciation: "f-r-from"
Attributes: C

FR>DROP ( -- )

Return Stack: ( R: r – )

Removes the top floating point number from the return stack.
Pronunciation: "f-r-from-drop"
Attributes: C

FR@ ( -- r )

Return Stack: ( R: r – r )

Copies the top floating point number on the return stack to the data stack.
Pronunciation: "f-r-fetch"
Attributes: C

FRAME.DROP ( [+n bytes]\+n -- )

Drops +n bytes (in addition to +n) from the data stack. If +n is odd, +n is incremented first so that an integer number of two-byte cells is dropped. FRAME.DROP is usually used to drop items placed on the stack by STACK.FRAME.

See also STACK.FRAME

FRANDOM ( -- r | 1.0 <= r < 2.0 )

r is a pseudo-random floating point number greater than or equal to 1.0 and less than 2.0.

See also RANDOM# and RANDOM.GAUSSIAN
Pronunciation: "f-random"

FREE.HANDLE ( -- xaddr )

A variable that holds the 16-bit address of the next available handle in the current heap. xaddr is equal to CURRENT.HEAP - 12. Initialized by IS.HEAP.

FROM.HEAP ( d -- [xhandle] or [0\0] | d = number of bytes )

If d bytes are available in the heap, allocates them and returns a 32-bit xhandle whose contents equal the base xaddress of the allocated heap item. Adjusts d upward so that it is an even multiple of 4, and allocates the heap item so that its base address is an even multiple of 4. Returns 0\0 if there is not enough heap space to perform the allocation, or if the allocated handle is within 5 bytes of the bottom of CURRENT.HEAP's page (handles must be on the same page as CURRENT.HEAP).

FROT ( r1\r2\r3 -- r2\r3\r1 )

Rotates the top three floating point numbers on the data stack.
Pronunciation: "f-rote"

FRTI ( r1 -- r2 )

Rounds r1 to the nearest integer and returns the result r2. OVERFLOW is set if necessary.
Pronunciation: "f-round-to-integer"
Attributes: S

FSCALE ( r1\n -- r2 )

Adds the signed integer n to the (base 2) exponent of r1 to compute r2. This provides a fast way of multiplying r1 by a power of 2 (if n is positive) or dividing r1 by a power of 2 (if n is negative). OVERFLOW is set if necessary.
Pronunciation: "f-scale"
Attributes: S

FSIN ( r1 -- r2 )

r2 is the sine of r1. r1 is expressed in radians.
Pronunciation: "f-sine"
Attributes: S

FSQRT ( r1 -- r2 )

r2 is the square root of r1. r2 is zero if r1 is negative.
Pronunciation: "f-square-root"
Attributes: S

FSWAP ( r1\r2 -- r2\r1 )

Exchanges the top two floating point numbers on the stack.
Pronunciation: "f-swap"

FTAN ( r1 -- r2 )

r2 is the tangent of r1. r1 is expressed in radians.
Pronunciation: "f-tan"
Attributes: S

FVARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child word called <name>, and VALLOTs 2 cells in the variable area. When <name> is executed, it leaves the extended address xaddr of the two cells reserved in the variable area to hold <name>'s contents. <name> is referred to as an "fvariable". Use as:

FVARIABLE <name>

Pronunciation: "f-variable"
Attributes: D

F^N ( r1\n -- r2 )

Raises r1 to the nth power and returns the result r2; r2 = r1^n.
Pronunciation: "f-to-the-n"
Attributes: S

GARRAY.XPFA ( -- xpfa )

Returns the extended parameter field address that specifies the graphics data array. This otherwise unnamed array is dimensioned by INIT.DISPLAY if a graphics display has been specified using IS.DISPLAY. UPDATE.DISPLAY.LINE and UPDATE.DISPLAY write the contents of this array to the graphics display. DISPLAY.BUFFER returns the xaddr of the first element in this array if a graphics display is in use. Graphics extension routines are supplied in source code form to augment the kernel; these routines provide examples of how to access information in the graphics array.
Pronunciation: "g-array-x-p-f-a"

GET ( xresource -- )

Used in a multitasking system to gain access to a shared resource. PAUSEs until the resource variable whose address is xresource is available, and then GETs the resource by storing the task id (i.e., the STATUS xaddr) of the requesting task into the xresource. 0\0 in xresource indicates that the resource is available, and a non-zero value that is not equal to the requesting task's id indicates that another task controls the resource. To ensure that the state of the resource is correctly determined, GET disables interrupts for 27 to 57 cycles (6.75 to 14.25 microseconds).

See also ?GET, RELEASE, and RESOURCE.VARIABLE:

Attributes: M

H.INSTANCE: ( u <name> -- | u = size of heap item )

Creates a heap instance. Removes <name> from the input stream, creates a header for <name> in the dictionary, and allots and erases a 6-byte parameter field associated with <name> in the variable area. The definition of HEAP.STRUCTURE.PF has a description of the contents of the parameter field. Does not allocate space in the heap; this is done when the command ALLOCATED is executed. When <name> is executed, its stack picture is picture is

( -- [xaddr] or [0\0] )

where xaddr is the base address of the item in the heap, and where 0\0 is returned if heap space has not been ALLOCATED. The size u of the item in the heap is stored in the code field of <name> for later use by the word SIZE.OF. Typical use:

size.of.heap.item  H.INSTANCE:  <name>
SIZE.OF <name>   ' <name>   ALLOCATED
 <name>    ( -- base.xaddr.of.heap.item )

Pronunciation: "h-instance"
Attributes: D

HALT ( -- )

An infinite loop whose action is to put the calling task ASLEEP and execute PAUSE. Typically used to terminate a task action that is not an infinite loop.

Attributes: M

HANDLE.PTR ( -- xaddr )

A variable that holds the 16-bit address of the next available location that can be allocated as a handle in the current heap. xaddr is equal to CURRENT.HEAP - 10. Initialized by IS.HEAP.
Pronunciation: "handle-pointer"

HAS.PFA ( -- )

Sets the "has-pfa" bit in the header of the most recently defined word in the CURRENT vocabulary. If set, this bit indicates that the word has a parameter field. HAS.PFA is executed by <DBUILDS and <VBUILDS and by defining words including VARIABLE CONSTANT INTEGER: and their double number counterparts and synonyms. The word ' (tick) checks the has-pfa bit when calculating the parameter field address of a word. ?HAS.PFA can be used to determine whether the has-pfa bit is set.
Pronunciation: "has-p-f-a"

HEAP.PTR ( -- xaddr )

A variable that holds the extended address of the next available byte in the current heap. xaddr equals CURRENT.HEAP - 8. Initialized by IS.HEAP.
Pronunciation: "heap-pointer"

HEAP.STRUCTURE.PF ( -- u | u = minimum size of a heap parameter field )

Places on the stack the minimum number of bytes needed to allocate a parameter field for a heap item (u = 6 bytes). HEAP.STRUCTURE.PF is a structure defined as:

STRUCTURE.BEGIN: HEAP.STRUCTURE.PF
   PAGE-> +HEAP.PAGE      \ page of current.heap and heap.handle

      HNDL-> +HEAP.HANDLE      \ contains base addr of heap item

   ADDR-> +CURRENT.HEAP   \ specifies which heap the item is in
STRUCTURE.END

See H.INSTANCE:, +HEAP.PAGE, +HEAP.HANDLE, and +CURRENT.HEAP.
Pronunciation: "heap-structure-p-f"

HERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the definitions area. Equivalent to DP X@

Attributes: U

HEX ( -- )

Sets the numeric conversion base to sixteen by storing decimal 16 into the user variable BASE.

HNDL-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a 16-bit field in the structure that will hold a handle (a handle is an address where another address is stored). Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "handle"
Attributes: D

HOLD ( char -- )

Inserts char into the numeric output string to the left of the prior character in the string and decrements the headerless pointer #PTR. HOLD is used between <# and #> commands to create a pictured numeric string.

Attributes: S

I ( -- w )

Return Stack: ( R: w – w )

Places a copy of the current (innermost) loop index on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... I ...  LOOP

or

DO ... I ... +LOOP

or

FOR ... I ...  NEXT

Pronunciation: "i"
Attributes: C

I' ( -- w1 )

Return Stack: ( R: w1\w2 – w1\w2 )

Used inside a DO…LOOP or DO…+LOOP structure. Places a copy of the current (innermost) loop limit on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... I' ...  LOOP

Pronunciation: "i-prime"
Attributes: C

I+ ( n1 -- n2 | n2 = n1 + I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Adds the current (innermost) loop index I to n1 and places the result n2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... n1 I+ ...  LOOP

Pronunciation: "i-plus"
Attributes: C

I- ( n1 -- n2 | n2 = n1 - I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Subtracts the current (innermost) loop index I from n1 and places the result n2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... n1 I- ...  LOOP

Pronunciation: "i-minus"
Attributes: C

IC1.ID ( -- n )

Returns the interrupt identity code for input capture 1 which is associated with port bit PA2. Used as an argument for ATTACH.
Pronunciation: "i-c-one-i-d"

IC2.ID ( -- n )

Returns the interrupt identity code for input capture 2 which is associated with port bit PA1. Used as an argument for ATTACH.
Pronunciation: "i-c-two-i-d"

IC3.ID ( -- n )

Returns the interrupt identity code for input capture 3 which is associated with port bit PA0. Used as an argument for ATTACH.
Pronunciation: "i-c-three-i-d"

IC4/OC5.ID ( -- n )

Returns the interrupt identity code for input capture 4/ output compare 5. This interrupt can control the action of port bit PA3. Note that the optional secondary serial port uses IC4/OC5 and PA3. Used as an argument for ATTACH.
Pronunciation: "i-c-4-or-o-c-5-i-d"

ID. ( xnfa -- )

Prints the name of the routine associated with the extended name field address xnfa. Letters not saved in the header are printed as ___ . The name is followed by a space. If the word is smudged (for example, if an error occurred during compilation of the word), a ~ is printed before the first letter in the name. An unchecked error occurs if xnfa is not a valid name field address.
Pronunciation: "i-d-dot"
Attributes: M

IF ( flag -- )

Used inside a colon definition to mark the beginning of a conditional structure. If flag is FALSE execution continues after the subsequent ELSE or ENDIF (THEN and ENDIF are synonyms) . If flag is TRUE execution continues with the word immediately following IF, and when ELSE is encountered (if present), control is transferred to the word following ENDIF. Use as:

flag    IF        words to execute if flag is true
   ENDIF

or as:

flag    IF        words to execute if flag is true
   ELSE    words to execute if flag is false
   ENDIF

Attributes: C, I

IFFT ( matrix.xpfa -- )

Computes the inverse Fast Fourier Transform of the frequency domain waveform in the source matrix specified by matrix.xpfa and stores the transformed result in the source matrix. The source matrix must be dimensioned to have 2 rows and 1 column per input data point. The number of columns must be a power of 2, with the maximum number of columns equal to 8192. Row#0 holds the floating point number representing the real part of each data point, and row#1 holds the floating point number representing the imaginary part of each data point. Each data point typically indicates the complex value of the input in the frequency domain. IFFT transforms the input into a complex waveform in the time or spatial domain and stores the results in the source matrix specified by matrix.xpfa.

See also FFT
Pronunciation: "inverse-f-f-t"
Attributes: S

IFTRUE ( flag -- )

Marks the start of the "true" portion of a conditional structure that is used in execution mode outside a colon definition. Use as:

 flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and OTHERWISE is executed, and the code between OTHERWISE and ENDIFTRUE is skipped. If the flag is false, the code between IFTRUE and OTHERWISE is skipped and execution continues with the words following OTHERWISE. Another valid syntax is:

flag  IFTRUE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and ENDIFTRUE is executed. If the flag is false, the code between IFTRUE and ENDIFTRUE is skipped. IFTRUE is analogous to IF but it is used outside of a colon definition. The execution mode conditional structure can be used to conditionally compile portions of source code. An unchecked error occurs if IFTRUE is used without a corresponding ENDIFTRUE. Note that IFTRUE/OTHERWISE/ENDIFTRUE statements can not be nested.
Pronunciation: "if-true"

ILLEGAL.OPCODE.ID ( -- n )

Returns the interrupt identity code for the illegal opcode interrupt. Used as an argument for ATTACH.
Pronunciation: "illegal-opcode-i-d"

IMMEDIATE ( -- )

Sets the "immediate bit" in the header of the most recently defined word to indicate that it should be executed immediately even in compilation mode. The command ?IMMEDIATE may be used to determine the status of the immediate bit for a given word.

INFINITY ( -- r )

Pushes the largest representable floating point number onto the data stack.

INIT.DISPLAY ( -- )

Initializes the liquid crystal display (LCD) interface. If a graphics-style display has been specified by IS.DISPLAY, initializes the DISPLAY.HEAP and dimensions GARRAY.XPFA to point to an appropriately sized array in that heap. The base address of this array is returned by DISPLAY.BUFFER. If a character-style (alphanumeric) display has been specified by IS.DISPLAY, then the display buffer is located in the system RAM and the DISPLAY.HEAP and GARRAY.XPFA are not initialized. If the dimensions specified by IS.HEAP call for a graphics array that is larger than the available ROOM in the DISPLAY.HEAP, then INIT.DISPLAY will not dimension the array;

Also see the glossary entry of DISPLAY.HEAP for further details. INIT.DISPLAY calls CLEAR.DISPLAY to clear the DISPLAY.BUFFER and write the blank data (ascii blanks for character displays, binary zeros for graphics displays) to the LCD display. Homes the cursor to the start of line 0, and leaves the display enabled with the cursor off and not blinking. Intermittently disables interrupts for 28 cycles (7 microseconds) per byte transmitted to the display.

See also CLEAR.DISPLAY

INIT.ELAPSED.TIME ( -- )

Initializes the system variable TIMESLICE.COUNT to 0\0.

INIT.RS485 ( -- )

Calls INIT.PIA to configure the peripheral interface adapter (PIA) so that it is consistent with operation of the RS485 circuitry, and then sets the RS485 transceiver to receive mode. Recall that INIT.PIA expects to find two flags on the stack: the first flag is true if PPA is to be an output, and the top flag on the stack is true if upper PPC is to be an output. INIT.RS485 sets the first flag to leave the data direction of PPA unchanged, and sets the top flag on the stack to TRUE to configure upper PPC as an output. PPC bit 4 controls the direction of the RS485 data transfer: when bit 4 of PPC is high, the RS485 port is in transmit mode, and when bit 4 of PPC is low, the RS485 port is in receive mode. (Make sure that the onboard RS485/RS232 jumper is properly set before attempting to use the RS485 interface).

See also INIT.PIA, RS485.RECEIVE, and RS485.TRANSMIT
Pronunciation: "init-R-S-four-eighty-five"

INIT.SERIAL2 ( -- )

Initializes the secondary serial port (serial2) which is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). Clears the resource variable SERIAL2.RESOURCE to 0\0, initializes PARITY to OFF, initializes the transmit and receive buffers (80 characters each, located in the reserved system RAM), initializes the data directions of PA3 and PA4 as input and output, respectively, and locally enables the required interrupts associated with PA3 and PA4. Does not globally enable interrupts. The programmer must separately execute the BAUD2 command (to set the baud rate) and execute ENABLE.INTERRUPTS (to globally enable interrupts) before using the serial2 port.

See also USE.SERIAL2 and DISABLE.SERIAL2
Pronunciation: "init-serial-two"

INIT.SPI ( -- )

Configures and enables the serial peripheral interface (SPI) so that it can transfer data to and from the on-board battery-backed real-time clock. The SPI uses bits 2-5 of PORTD. Initializes the 68HC11 as the SPI "master" with 2 MHz data transfer, with valid data present/sampled on the falling trailing edge of the SPI clock. Initializes the contents of PORTD.DIRECTION to be compatible with being the master of the SPI (that is, PD2/MISO = input, PD3/MOSI = output, PD4/SCK = output, PD5/SS = output). Also initializes the resource variable SPI.RESOURCE to 0\0.

See also SPI.OFF
Pronunciation: "init-S-P-I"

INIT.VITAL.IRQS.ON.COLD ( -- )

Undoes the effect of the NO.VITAL.IRQ.INIT command, and causes subsequent cold restarts to perform the default action of checking the interrupt vectors for the COP, clock monitor, illegal opcode and OC2 interrupts and initializing them if they do not contain the standard interrupt service vectors. Implementation detail: sets location AE1B in EEPROM to 0xFF.
Pronunciation: "init-vital-i-r-qs-on-cold"

INPUT.STRING ( <text> -- x$addr | x$addr = PAD )

Inputs a character string <text> to the PAD buffer, terminating when CHARS/LINE characters are received or a carriage return is received, whichever comes first. Leaves the address of the counted string on the stack. Appends a blank (not included in the count) to the end of the string.

Attributes: M

INSTALL.MULTITASKER ( -- )

Installs the timeslice multitasker timer by initializing the interrupt vector of the output compare 2 (OC2) timer. This command is automatically executed upon a COLD restart (unless the command NO.VITAL.IRQ.INIT has been executed) and by the command START.TIMESLICER. Because the interrupt vector is in non-volatile EEPROM, it is usually not necessary to invoke this command unless the OC2 interrupt vector has been modified.

INSTALL.REGISTER.INITS ( byte1\byte2\byte3\byte4 -- | byte1=OPTION, byte2=TMSK2,

                 byte3=BPROT, byte4 = BAUD )

Compiles a 7-byte sequence into the EEPROM that specifies the contents to be loaded into the "protected registers" plus the BAUD register after subsequent resets. The protected registers are those that must be initialized within 64 machine cycles after a reset; after that their contents cannot be changed. They are INIT, OPTION, TMSK2, and BPROT. The BAUD register controls the BAUD rate of the primary serial communications interface (serial1), and is included so that a user-specified baud rate can be set upon every restart. The INIT register controls the location of the on-chip RAM and the registers. This value is set to B8H (on-chip RAM at 0xB000, and registers at 0x8000); other values are not compatible with QED-Forth. The contents of the other 4 registers may be specified by the user. Once INSTALL.REGISTER.INITS is executed, subsequent resets will cause B8H to be stored in INIT, byte1 in OPTION, byte2 in TMSK2, byte3 in BPROT, and byte4 in BAUD. To undo the effects of this word and return to the default contents of the protected registers use the DEFAULT.REGISTER.INITS command; consult its glossary entry for a list of the default values for each of the registers.

Implementation detail: INSTALL.REGISTER.INITS writes the pattern 0x13 at location 0xAE06 in the EEPROM. The five bytes following the pattern contain the specified contents of INIT (=B8H), OPTION, TMSK2, BPROT, and BAUD, respectively.

INT-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a 16-bit field in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "integer"
Attributes: D

INT.FLOOR ( r -- n )

n is the greatest integer less than or equal to r. OVERFLOW is set if needed.

Attributes: S

INT.PART ( r -- n )

n is the integer part of r. OVERFLOW is set if needed. (This function used to be named INT in QED-Forth versions up to V3.01.)
Pronunciation: "int"
Attributes: S

INTEGER: ( <name> -- )

Defines a 16-bit self-fetching variable. Removes <name> from the input stream and creates a child word (a self-fetching variable) called <name> and VALLOTs 2 bytes in the variable area as the parameter field where the self-fetching variable's value is stored. When <name> is executed it leaves its value (a 16-bit integer) on the stack. Thus <name> behaves like a constant when executed. Unlike a constant, its parameter field is in the variable area and so can always be modified. The TO command is used to store a value into the self-fetching variable. In general, code using self-fetching variables runs faster than does similar code that uses standard variables. Use as:

INTEGER: <name>         <value>  TO  <name>

Pronunciation: "integer-colon"
Attributes: D

INTERPRET ( -- )

Interprets the input stream as designated by BLK and >IN until the input stream is exhausted. If BLK = 0, the input stream is taken from the terminal input buffer and INTERPRET interprets a single line of input which was read into the TIB by QUERY. If BLK does not equal 0, INTERPRET interprets the specified block. INTERPRET repeatedly calls WORD (which gets the next word from the input stream) until the input stream is exhausted at the end of the current line or block.

See also BLK, >IN, BLOCK, WORD, LOAD, QUERY, and QUIT

INTS-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 integers in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "integers"
Attributes: D

INVERTED ( matrix.xpfa1\matrix.xpfa2 -- )

Inverts the source matrix specified by matrix.xpfa1 and stores the result into the destination matrix specified by matrix.xpfa2. An error occurs if the source matrix is not square. matrix.xpfa2 may equal matrix.xpfa1.

Attributes: S

IRQ.ID ( -- n )

Returns the interrupt identity code for the external interrupt request interrupt. Used as an argument for ATTACH.
Pronunciation: "i-r-q-i-d"

IS.DISPLAY ( #rows\#cols\text.mode?\char.display?\hitachi? -- )

Based on the specified number of rows, number of columns, and flags that indicate text or graphics mode, character versus graphics display, and Hitachi versus Toshiba graphics controller chip, this routine saves the display configuration in EEPROM so that the LCD display is properly initialized upon subsequent restarts and resets by the INIT.DISPLAY routine which is automatically executed at startup. The encoded information is accessible via the routines CHARS/DISPLAY.LINE and LINES/DISPLAY. When IS.DISPLAY is executed, #rows and #cols should be expressed as the number of 8x6- or 8x8-pixel characters that the screen can accommodate. The standard width font for Toshiba graphics displays is set by hardware inputs on the display module to either 6 or 8 pixels wide. The standard width font for Hitachi graphics displays is 8 pixels in graphics mode, and can be set by software to either 6 pixels or 8 pixels wide in text mode. The allowed values of numRows are 2, 4, 8 or 16 lines per display. The allowed values of numCols are 8, 12, 16, 20, 24, 30, and 40 characters or bytes per line. The text.mode? flag selects between text mode (if the flag is true) and graphics mode (if the flag is false) for graphics displays; character displays always operate in text mode. The character.display? flag selects between a strictly alphanumeric character display if the flag is true, and a graphics display if the flag is false. The hitachi? flag specifies the type of controller that drives the graphics display module. If the hitachi? flag is true, a Hitachi 61830 controller chip is assumed; if the hitachi? flag is false, we assume a Toshiba 6963 graphics controller chip. NOTE that if a graphics display is specified (char.display? is false) but the text mode is specified (text.mode? is true), the data buffer created by INIT.DISPLAY in the DISPLAY.HEAP will be too small to accommodate graphical data. Thus if you want to use both the text and graphics modes of a graphics display, declare a graphics mode display (i.e., with a false text.mode? flag), and use the DISPLAY.OPTIONS routine to convert to and from text mode. Then the dimensioned buffer will be large enough for either character or graphical data. The following routines specify the most commonly used displays:

DECIMAL

: 4X20.CHARACTER 4 20 -1 -1 -1 IS.DISPLAY ;

: 128X240.HITACHI.GRAPHICS 16 30 0 0 -1 IS.DISPLAY ;

: 128X240.HITACHI.TEXT 16 40 -1 0 -1 IS.DISPLAY ;

: 128X240.TOSHIBA.GRAPHICS 16 40 0 0 0 IS.DISPLAY ;

: 128X240.TOSHIBA.TEXT 16 40 -1 0 0 IS.DISPLAY ;

: 128X128.HITACHI.GRAPHICS 16 16 0 0 -1 IS.DISPLAY ;

: 128X128.HITACHI.TEXT 16 20 -1 0 -1 IS.DISPLAY ;

The 4x20 character display is the default type that is established by the "special cleanup mode". Remember to execute INIT.DISPLAY after executing IS.DISPLAY the first time. Note that because IS.DISPLAY saves the configuration information in EEPROM, you need not execute IS.DISPLAY each time the board starts up. INIT.DISPLAY is automatically executed each time the QED Board starts up.

Implementation detail: This routine encodes the configuration information in a single byte that is saved at location AE1EH in EEPROM.

IS.DISPLAY.ADDRESS ( addr -- )

Configures a graphics display so that the next data write will occur at the specified RamAddress in the display RAM. This routine can be used in conjunction with (UPDATE.DISPLAY) to write data to the "off-screen" RAM that is typically present on a graphics display module. Then modifying the "home address" (upper left location) of the display allows scrolling of data across the display; consult the source code of the graphics extension source code file for more details. IsDisplayAddress() has no effect if a character display is installed.

See also PUT.CURSOR

IS.HEAP ( xaddr1\xaddr2 -- | xaddr1 = start, xaddr2 = end )

Initializes the heap control variables to set up a heap starting at xaddr1 and ending 1 byte below xaddr2. All of the bytes between xaddr1 and xaddr2 must be modifiable RAM. The size of the heap and of individual heap items is limited only by available memory. If the specified heap size (xaddr2 - xaddr1) is greater than or equal to 16 bytes, IS.HEAP initializes CURRENT.HEAP to xaddr2, initializes START.HEAP and HEAP.PTR to xaddr1, and initializes HANDLE.PTR and FREE.HANDLE to indicate that there are no allocated heap items. If the specified heap size (xaddr2 - xaddr1) is less than 16 bytes, only the user variable CURRENT.HEAP is initialized, and the heap control variables that are stored in the heap itself (START.HEAP, HEAP.PTR, HANDLE.PTR and FREE.HANDLE) are not initialized. This allows tasks to share a heap that has already been initialized without disturbing the values of the heap control variables. Caution: sharing a heap among tasks may lead to hard-to-diagnose multitasking failures. Consult the chapters on multitasking and re-entrant coding in the Software Manual when designing multitasking programs.
Pronunciation: "is-heap"

IS.IDENTITY ( matrix.xpfa -- )

Stores 1.0 in all the elements of the specified matrix that have row# equal to col# (i.e., in the diagonal elements), and stores 0.0 in all the other elements. The matrix need not be square.

Attributes: S

IS.TRACE.ACTION ( xcfa -- )

Installs the action referenced by the extended code field address xcfa as the first action to be performed by the trace routine. If a colon or code definition is compiled with TRACE ON, a call to the trace routine is compiled before each call to subsidiary words in the definition. The first thing that the trace routine does is to execute the code whose xcfa has been stored in the headerless user variable TRACE.ACTION by IS.TRACE.ACTION. The default action (set upon COLD restart) is NO.OP. The action must have no net effect on the data or return stacks, and must be compiled while TRACE is OFF; if trace is ON while the trace action is being defined, an infinite loop of calls to the trace routine is initiated. The word DEFAULT.TRACE.ACTION installs NO.OP (a do-nothing word) as the trace action.

Example of use: assume that a complex program contains a mysterious bug, and the programmer is trying to locate it. Further assume that the programmer knows that the bug causes a particular variable called THE.VARIABLE to be set equal to 0. One way to locate the problem would be to compile the program with TRACE ON and then execute the entire program with DEBUG ON. The disadvantage of this is that a great deal of traced output must be examined. A more efficient method is to write a word that tests the variable in question and, if it equals 0 (which signals that the bug has just occurred), turns DEBUG ON:

: CHECK.FOR.ERROR     THE.VARIABLE  @  IF  DEBUG  ON  THEN ;

This word is then installed as the trace action by executing:

CFA.FOR   CHECK.FOR.ERROR   IS.TRACE.ACTION

Now the program is compiled with TRACE ON, and executed with DEBUG initially OFF so that the program runs at near full speed and no traced output is written to the screen. As soon as the bug manifests itself, however, the trace action word turns DEBUG ON which initiates the printout of all trace information. This shows the programmer where the bug is occurring in the program.

See also BREAK, DEBUG, DUMP.REGISTERS, and SINGLE.STEP

IXN+ ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 + I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Adds the current (innermost) loop index I, interpreted as a signed integer in the range -32,768 to +32,767, to xaddr1 and places the result xaddr2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... addr1  IXN+ ...  LOOP

See XN+
Pronunciation: "i-x-n-plus"
Attributes: C

IXN- ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 - I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Subtracts the current (innermost) loop index I, interpreted as a signed integer in the range -32,768 to +32,767, from xaddr1 and places the result xaddr2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ...xaddr1  IXN- ...  LOOP

See XN-
Pronunciation: "i-x-n-minus"
Attributes: C

IXU+ ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 + I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Adds the current (innermost) loop index I, interpreted as an unsigned integer in the range 0 to +65,535, to xaddr1 and places the result xaddr2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... xaddr1  IXU+ ...  LOOP

See XU+
Pronunciation: "i-x-u-plus"
Attributes: C

IXU- ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 - I )

Return Stack: ( R: w1 – w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure. Subtracts the current (innermost) loop index I, interpreted as an unsigned integer in the range 0 to +65,535, from xaddr1 and places the result xaddr2 on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R). Typical use:

DO ... xaddr1  IXU- ...  LOOP

See XU-
Pronunciation: "i-x-u-minus"
Attributes: C

I\J ( -- w1\w2 | w1 = I, w2 = J )

Return Stack: ( R: w3\w2\w4\w1 – w3\w2\w4\w1 )

Used inside nested DO…LOOP or DO…+LOOP. Places on the data stack a copy of the loop index for the current (innermost) loop under a copy of the loop index for the next outer loop. Equivalent to I J. May not be used if additional items have been placed on the return stack (for example, using >R). May not be used in FOR…NEXT loops. Typical use:

DO
   DO  ... I\J ...
   LOOP
LOOP

Pronunciation: "i-under-j"
Attributes: C

J ( -- w1 )

Return Stack: ( R: w2\w1\w3\w4 – w2\w1\w3\w4 )

Used inside nested DO…LOOP or DO…+LOOP. Places on the data stack a copy of the loop index for the next outer loop (i.e., the index of the loop nested 1 level below the loop in which J is invoked). Cannot be used if additional items have been placed on the return stack (for example, using >R). Cannot be used in FOR…NEXT loops. Typical use:

DO
   DO  ... J ...
   LOOP
LOOP

Attributes: C

J\I ( -- w1\w2 | w1 = J , w2 = I )

Return Stack: ( R: w3\w1\w4\w2 – w3\w1\w4\w2 )

Used inside nested DO…LOOP or DO…+LOOP. Places on the data stack a copy of the loop index for the next outer loop under a copy of the loop index for the current (innermost) loop. Equivalent to J I. Cannot be used if additional items have been placed on the return stack (for example, using >R). Cannot be used in FOR…NEXT loops. Typical use:

DO
   DO  ... J\I ...
   LOOP
LOOP

Pronunciation: "j-under-i"
Attributes: C

K ( -- w1 )

Return Stack: ( R: w2\w1\w3\w4\w5\w6 – w2\w1\w3\w4\w5\w6 )

Used inside nested DO…LOOP or DO…+LOOP. Places on the data stack a copy of the loop index for the second outer loop (i.e., the index of the loop nested 2 levels below the loop in which K is invoked). Cannot be used if additional items have been placed on the return stack (for example, using >R). Cannot be used in FOR…NEXT loops. I and J are the indexes of the inner loops. Typical use:

DO
   DO
      DO  ... K ...
      LOOP
   LOOP
LOOP

Attributes: C

KEY ( -- char )

Waits (if necessary) for receipt of a character from the serial port and places the character on the data stack. KEY is a vectored routine that executes the routine whose xcfa is stored in the headerless user variable UKEY. The default installed routine called is KEY1 which receives the character from the primary serial port (supported by the 68HC11's hardware UART). KEY2 may be installed in UKEY by USE.SERIAL2 or SERIAL2.AT.STARTUP; KEY2 receives the character from the secondary serial port (supported by QED Forth's software UART and using pins PA3 and PA4).

See also KEY1 and KEY2
Attributes: M, U

KEY1 ( -- char )

Waits (if necessary) for receipt of a character from the primary serial port (serial1) and places the received character on the data stack. KEY1 does not echo the character. The serial1 port is associated with the 68HC11's on-chip hardware UART. KEY1 is the default KEY routine installed in the UKEY user variable if SERIAL1.AT.STARTUP has been executed (and after the special cleanup mode is invoked). If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, KEY1 does not GET or RELEASE the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, KEY1 GETs and RELEASEs the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, KEY1 GETs but does not RELEASE the SERIAL1.RESOURCE.

See also KEY, UKEY, KEY2, and SERIAL.ACCESS
Pronunciation: "key-one"
Attributes: M

KEY2 ( -- char )

Waits (if necessary) for receipt of a character from the secondary serial (serial2) port, removes the character from the serial2 input buffer and places the received character on the data stack. Received characters are stored in an 80 (decimal) byte circular buffer. If more than 80 characters are received between calls to KEY2, the oldest characters are lost and only the 80 most recent characters may be read. Each invocation of KEY2 fetches the next character in the buffer. If no characters have been received KEY2 waits, executing PAUSE, until a character is received.

The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). KEY2 does not echo the received character. KEY2 can be made the default KEY routine installed in the UKEY user variable after each reset or restart by executing SERIAL2.AT.STARTUP. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, KEY2 does not GET or RELEASE the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, KEY2 GETs and RELEASEs the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, KEY2 GETs but doesn't RELEASE the SERIAL2.RESOURCE.

See also ?KEY2, #INPUT.CHARS, KEY, UKEY, KEY1, and SERIAL.ACCESS
Pronunciation: "key-two"
Attributes: M

KEYPAD ( -- n | 0 <= n <= 39 )

Scans keypad or touchscreen having up to 8 rows and 5 columns and waits for a keypress. PAUSEs while waiting. Waits until the key is released, then returns the key number on the data stack. Disables interrupts for 12 microseconds each time a row is scanned. The keymap is as follows:

39   35   31   27   23
38   34   30   26   22
37   33   29   25   21
36   32   28   24   20
19   15   11    7     3
18   14   10    6     2
17   13    9     5     1
16   12    8     4     0

Note that the behavior with respect to 4-row by 5-column keypads is unchanged, so legacy 20-key hardware operates as it did under prior kernel versions. The support for keys 20 through 39 enables the use of larger keypads on the Handheld product.

See also ?KEYPAD and ?KEYPRESS

KILL ( xtask.id -- )

Puts the task referenced by xtask.id ASLEEP and removes it from the round robin multitasking loop. The task to be killed must be installed in the round robin loop. If it isn't, or if a task attempts to KILL itself, the results are unpredictable. Aborts if xtask.id is not in common ram.

L.INVERTED ( matrix.xpfa1\matrix.xpfa2 -- )

Inverts a lower triangular matrix specified by matrix.xpfa1 and puts the inverse in the destination matrix.xpfa2. Ignores the upper half of the source matrix so it doesn't matter if the elements are not truly zero.

Attributes: S

LATEST ( -- xnfa )

Returns the extended name field address of the last word defined in the CURRENT vocabulary.

Attributes: U

LEAST.SQUARES ( X.matrix.xpfa\ Y.matrix.xpfa

      \ C.matrix.xpfa\ Sample.Variance.matrix.xpfa
      \ [Weight.matrix.xpfa] or [0\0] \ [Y.model.xpfa] or [0\0]
      \ [Y.err.matrix.xpfa]   or [0\0] \ [Covar.matrix.xpfa] or [0\0] -- )

Performs general linear least squares data analysis by solving an overdetermined set of simultaneous equations in which instances of independent variables (or functions of independent variables), x, are related to instances of dependent variables (or functions of dependent variables), y, by a set of linear coefficients, c. The overdetermined system of equations is represented in matrix form as

Y = X C

Consult the software manual for a detailed example of use.

Although the matrix of dependent variables, Y, is usually only a single column, this routine can also do a number of least squares problems simultaneously, for different dependent variables or functions of dependent variables, each contained in a different column of Y. Y contains a row for each instance of the Y variable(s). X is the design matrix, a user-supplied matrix that includes a column for each independent variable or function of independent variable(s). Each row of X and Y corresponds to a single "trial", "instance", or "measurement".

C is the matrix designated by the user to contain the primary result returned by this routine, the coefficients. It contains a row for each column of X and a column for each column of Y. Most problems require only a single dependent variable so C is generally a single-column matrix.

Optionally an input matrix of weights that is parallel to the Y matrix may be included. The weights should be inversely proportional to the expected variances on the instances of Y. Weights are considered to be relative; their absolute magnitudes are ignored and only their relative proportions are used by LEAST.SQUARES. Internally to LEAST.SQUARES the user's weight matrix is normalized so that the column-averaged weight is unity, that is, the sum of weights in each column is made equal to the number of instances (rows) in the column. Uniform weighting is assumed if a weight matrix is not included.

LEAST.SQUARES computes values of the coefficient matrix C that minimizes the observed sample variance of the data points from the fitted model. Observed sample variance is defined as the weighted sum of squares of the differences between the Y data and the modeled Y, divided by the number of degrees of freedom in order to get a variance per instance. For each column of Y the observed sample variance is

Sample.Error^2 =  ∑ wi (yi - yimodel )^2 /(n-m)

where wi are the normalized weights, yi are the input y values (i.e., the contents of the Y matrix), yimodel are the predicted values of the dependent variable(s) computed from Y = X C, and (n-m) is the number of degrees of freedom in the optimization, equal to the number of instances (rows of X or Y) minus the number of coefficients determined (columns of X or rows of C). The routine reports a value for observed sample variance for each column of Y in the user's Sample.Variance.matrix. If the user provides appropriate matrix.xpfas LEAST.SQUARES also reports the predicted Y values in Y.model.matrix, the residuals or errors on Y, (Y-Ymodel), in Y.err.matrix, and the variance-covariance matrix for the determined coefficients in Covar.matrix.

If the user provides no weights, or for uniform weighting, or for all weight columns equal to one another, the returned variance-covariance matrix provides the relative covariances of the coefficients in any of the columns of the coefficient matrix, C. There are two ways to compute the actual variances and covariances for a particular column of C. If coefficient variances are to be determined using the actual deviations of the model from the best fit then the covariance matrix should be multiplied by the observed sample variance for the corresponding column of Y, found in Sample.Variance.matrix. Alternatively, if the coefficient variances are to be determined a priori from the expected experimental or measurement errors then the covariance matrix should be multiplied by the experimenter's expected variances on the Y values. After being scaled with the observed sample variance or the a priori measurement variances, the diagonal elements of the variance-covariance matrix are the variances on the coefficients of C, and their square roots are the expected errors on the coefficients.

For weights that differ from column to column the covariance matrix returned is that for only the first column of C, corresponding to the first column of Y or W.

The user's X, Y, C, and Weight matrices are not modified.

Attributes: S

LEAVE ( -- )

Return Stack: ( R: w1\w2 – | discards limit & index )

Forces the immediate termination of a DO…LOOP or DO…+LOOP structure. Discards the loop control parameters from the return stack and transfers control to the word following LOOP or +LOOP. An error is issued if LEAVE is used outside a DO…LOOP or DO…+LOOP structure. LEAVE cannot be used inside a CASE statement which is inside a DO LOOP or DO +LOOP structure. An unchecked error occurs if extra items are on the return stack when LEAVE executes (for example, items put on the return stack by >R). Use as:

w1 w2    DO    ...
      flag  IF  LEAVE ENDIF
      ...
   LOOP

See DO, LOOP and +LOOP.

Attributes: C, I

LEFT.PLACES ( -- xaddr )

A user variable that holds the number of digits to be displayed to the left of the decimal point when a floating point number is displayed in FIXED format.

See also F>FIXED$

Attributes: U

LIMIT ( -- xaddr )

Returns the extended address of the upper boundary+1 of the block buffers; that is, the address one greater than the last byte in the last buffer. Initialized by BLOCK.BUFFERS. Equivalent to ULIMIT X@
Pronunciation: "paren-limit"
Attributes: U

LINES/DISPLAY ( -- n )

Returns the number of lines in the LCD display. For character displays and for graphics displays being operated in "text mode", the result n equals the number of character lines (rows) in the display (the allowed values are 2, 4, 8 or 16 lines per display). For graphics displays being operated in "graphics mode", the result n equals the number of horizontal pixels on the display (which in turn is 8 times the number of character lines on the display). The type of display and the display mode (text mode vs. graphics mode) are determined by the most recent execution of DISPLAY.OPTIONS or INIT.DISPLAY (which implements the configuration specified by IS.DISPLAY). The default value of n after executing the "special cleanup mode" is 4, corresponding to the default 4-line by 20-character display. The result returned by this routine is used by BUFFER.POSITION, PUT.CURSOR, UPDATE.DISPLAY, and UPDATE.DISPLAY.LINE.
Pronunciation: "lines-per-display"

LINK ( xnfa1\xnfa2 -- )

Sets the link field in the name of the word referenced by name field address xnfa2 to point to the name referenced by xnfa1. In other words, it changes the way that backward-linked name list or vocabulary is searched so that the name associated with xnfa1 is encountered just after the name associated with xnfa2 (consult FIND). LINK can be used in several interesting ways. For example, if xnfa1 = xnfa2, LINK designates the associated name as the bottom name in a linked list, effectively "sealing" the linked name list or vocabulary. For example, to define a new sealed vocabulary, execute

VOCABULARY NEW.VOCAB
NEW.VOCAB DEFINITIONS   FORTH
\ new definitions now go into NEW.VOCAB,
\ but FORTH words can be accessed in the definitions
: #1.WORD   ....   ;
: #2.WORD   ....   ;
\ define as many words as needed in NEW.VOCAB
NFA.FOR  #1.WORD  XDUP  LINK   \ seal the vocabulary

Make sure that xnfa2 is in modifiable RAM memory when LINK is executed. Alternatively, instead of sealing the vocabulary by making #1.WORD the bottom name, we could execute

NFA.FOR  FORTH    NFA.FOR  #1.WORD    LINK

to link #1.WORD to FORTH which is the very first (bottom) name in the QED-Forth name list. This has the advantage of keeping the vocabulary's contents small while allowing FORTH to be recognized from within the new vocabulary. This allows graceful exit to the main FORTH vocabulary after executing NEW.VOCAB DEFINITIONS.

LINK_FILE_IO ( -- )

This function (present in kernel versions starting with V4.05) links in the Forth headers of the Memory Interface Board’s ATA Flash Card Software Package into the linked list of Forth names. Consult the MIB/ATA Flash Card Users Manual for information on how to use this function. Because the Memory Interface Board has been obsoleted by the Compact Flash Wildcard and its associated kernel extension software, this function is typically not used.

LITERAL ( -- w )

Compile Time: ( w – )

If QED-Forth is in execution mode when LITERAL is invoked, LITERAL does nothing. If QED-Forth is in compilation mode, LITERAL removes w from the stack and compiles it into the dictionary along with code that, when later executed, pushes w to the stack. LITERAL can be used within a colon definition to compile a numeric value into the definition. For example,

: <name>    ( -- n )
   [ CHARS/LINE @ ] LITERAL
;

This compiles as a literal the value of CHARS/LINE that exists when the definition is compiled. When <name> is later executed, this value will be placed on the stack.

Attributes: I

LN(2) ( -- r )

Places the floating point representation of the natural logarithm of 2 (0.69314) on the stack.
Pronunciation: "l-n-of-two"

LOAD.MATRIX ( xpfa <text> -- | expects numbers in input stream )

Repeatedly calls NEXT.NUMBER to get as many numbers as needed to fill the matrix specified by xpfa. The first row is filled first (starting at the left, i.e., at the first column), then the next row, etc. Carriage returns and tabs can be used to format the numbers if desired. The numbers can be valid integers or floating point numbers; NEXT.WORD automatically converts the integers to their floating point equivalents using FLOT. Non-numeric text in the input is ignored until the matrix is filled, but be careful: any valid number encountered by LOAD.MATRIX will be converted and placed in the matrix, even if it is within parentheses or after a comment delimiter such as \. Integers are converted according to the current number base. Use as

MATRIX: MAT.A 2 3 ' MAT.A DIMMED \ def & dimension

' MAT.A LOAD.MATRIX 99 3 4.2 5.3 8 3 \ init matrix

Attributes: M, S

LOCALS{ ( [...] -- | items are removed to initialize the local variables )

Return Stack: ( R: – […] | stack frame is placed on return stack,removed by ; )

Used within a colon definition to begin a command sequence that defines from 1 to 16 local variables. The syntax of the simplest type of local statement is:

LOCALS{ <name.1> <name.2>... <name.n> }

The names between LOCALS{ and the terminating } are given temporary headers that remain effective for the duration of the current definition. If the first 2 characters in the name of a local are d& or D& (suggesting a 32-bit double number value) or f& or F& (suggesting a 32-bit floating point value) or x& or X& (suggesting a 32-bit extended address) then the local is defined as a 32-bit quantity. All other local variables are defined as 16-bit quantities. At runtime (when the definition containing the LOCALS{ command is executed) the code compiled by LOCALS{ initializes the values of each of the named local variables to a corresponding item on the data stack. The top item is removed from the data stack and loaded into <name.1>, the next item on the data stack is removed and loaded into <name.2>, etc. A single cell is removed from the stack for each 16-bit local, and two cells are removed from the stack for each 32-bit local. Each local variable behaves just like a self-fetching variable. When executed, the local leaves its value on the stack. Its value can be initialized or modified by placing the desired value on the stack and invoking the TO operator followed by the name of the local variable.

An alternative syntax for the locals declaration is:

LOCALS{ <name.1> <name.2> ... | <name.a> <name.b> ... }

where the locals defined between LOCALS{ and the | (bar) are initialized to the values on the data stack as explained above, and the locals defined between the | and the terminating } are left uninitialized. If certain local variables are to be initialized by a TO statement later in the definition, it is better to define them as uninitialized locals to save execution time. If none of the locals need to be initialized, the syntax:

LOCALS{  | <name.a> <name.b> ... }

is acceptable. Locals can be used in recursive definitions; each execution of the word allocates a new frame on the return stack where the values of the locals are kept.

Usage rules: The locals command sequence,

LOCALS{ ... | ... }

may occupy multiple lines in the source code; however, no comments may appear between LOCALS{ and }. If using a disk block for input, the command must reside in a single block. To avoid problems with non-uniquely named local variables the convention of using names beginning with & is recommended. Only one

LOCALS{ ... | ... }

command sequence is allowed per definition and within the declaration only one | is allowed. The LOCALS{ declaration must not be inside a conditional structure such as an IF … ELSE … ENDIF structure. The number of local variables defined must be greater than 0 and less than or equal to 16. The local variable names defined in the body of a word are forgotten after the definition is finished. Colon definitions using locals should not call CREATE or other defining words and should not manipulate CURRENT. Locals cannot be used between <DBUILDS or <VBUILDS and DOES> in a defining word. Locals should not be used in interrupt service routines or in code called by interrupt service routines.
Pronunciation: "locals-start"
Attributes: C, D, I

LOG10(2) ( -- r )

Pushes the base-10 logarithm of 2 onto the data stack.
Pronunciation: "log-ten-of-two"

LOG2 ( u -- n )

n is the integer part of the base 2 logarithm of u.
Pronunciation: "log-two"

LOOP ( -- )

Return Stack: ( R: w1\w2 – [w1\w2] or [] | drops w1,w2 when loop terminates )

LOOP increments the loop index on the return stack by one. If the index then equals the loop limit, the loop parameters are removed from the return stack and execution continues at the word following LOOP. Otherwise, execution continues at the word following DO. See DO for examples.

Use as:

w1 w2    DO    words to be executed (w1 - w2 - 1) times
   LOOP

An error is issued if DO and LOOP are not paired within a definition.

See also DO  +LOOP  I  J  I'  K  LEAVE

Attributes: C, I

LU.BACKSUBSTITUTION ( residue.matrix.xpfa\matrix.xpfa\index.array.xpfa -- )

Used in conjunction with LU.DECOMPOSITION to solve a set of simultaneous equations. This solution method is very efficient when solving a system of equations with multiple right hand sides (i.e., multiple residues). residue.matrix.xpfa specifies a column matrix containing the right hand side of the system of equations, matrix.xpfa specifies a matrix containing the LU decomposition of the coefficient matrix, and index.array.xpfa specifies an array that was dimensioned and initialized by LU.DECOMPOSITION. LU.BACKSUBSTITUTION replaces residue.matrix.xpfa with the solution of the equation (i.e., with the values of the unknown quantities). For application information and an example, consult LU.DECOMPOSITION. See LU.DECOMPOSITION
Pronunciation: "l-u-back-substitution"
Attributes: S

LU.DECOMPOSITION ( index.array.xpfa\matrix.xpfa -- n | n = determinant's.sign )

Finds the LU ("lower/upper") decomposition of the source matrix specified by matrix.xpfa and stores the decomposed matrix back into the source matrix. Also calculates the sign n of the determinant of the source matrix which can be passed to ?DETERMINANT to find the determinant of the source matrix. Dimensions and initializes the array associated with index.array.xpfa to contain values that are then used by LU.BACKSUBSTITUTION.

Application: Sometimes it is necessary to solve several systems of equations, each having the same left hand sides but with different right hand sides, or residue matrices. The system of equations is represented by the matrix equation

AX=B

where X is a column matrix of unknowns, A is a matrix of coefficients, and B is a column matrix known as the "residue matrix" that represents the right hand side of the equations. A second set of equations with a different residue matrix could be represented as

AX' = C

where C is the residue matrix and X' is the matrix of unknowns that solves the equation. These sets of equations are most efficiently solved by finding the LU decomposition of A using the word LU.Decomposition. "LU" refers to "lower/upper", a decomposition method that minimizes the propagation of round-off error. Now the matrix equations can be expressed as

LU(A) X= B
LU(A) X'= C

where LU(A) is the decomposition of the A matrix. These equations can be solved for the unknown matrix X with a minimum of computation using the word LU.BACKSUBSTITUTION. To solve a given equation for several residue matrices, LU(A) needs only to be computed once. LU.BACKSUBSTITUTION can then solve each residue matrix to get each solution matrix with minimal additional work.

Example of use:

ARRAY: INDEX.ARRAY \ define this temporary array

MATRIX: A <initialize A here> \ define & init coefficients

MATRIX: B <initialize B here> \ define & init residue #1

MATRIX: C <initialize C here> \ define & init residue #2

' INDEX.ARRAY ' A LU.DECOMPOSITION

      \ replace A with its LU decomposition

DROP \ drop the determinant sign

' B ' A ' INDEX.ARRAY LU.BACKSUBSTITUTION

   \ for residue matrix B, find the unknowns X
   \ and place them in B

CR ." The answer to AX = B is " ' B M. \ print solution

' C ' A ' INDEX.ARRAY LU.BACKSUBSTITUTION

      \ for residue matrix C, find the
      \ unknowns X' and place them in C

CR ." The answer to AX' = C is " ' C M. \ print solution
Pronunciation: "l-u-decomposition"
Attributes: S

M* ( n1\n2 -- d )

Multiply signed single precision integers n1 and n2 producing signed double precision product d.
Pronunciation: "m-star"

M*MT ( matrix.xpfa1\matrix.xpfa2 -- )

Multiplies the source matrix.xpfa1 by its transpose to form the specified destination matrix.xpfa2. The name of the routine suggests the order of the operands.

See also MT*M
Pronunciation: "m-star-m-transpose"
Attributes: S

M. ( matrix.xpfa -- )

Prints the contents of the matrix specified by matrix.xpfa using the default printing format (FIXED, FLOATING, or SCIENTIFIC). The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained. Printed elements are delimited with spaces and with carriage returns and continuance marks (…). Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE. M. calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also PAUSE.ON.KEY
Pronunciation: "m-dot"
Attributes: M, S

M.. ( matrix.xpfa -- )

Prints the name of the matrix specified by matrix.xpfa followed by a display of its contents as performed by M.

See also M.
Pronunciation: "m-dot-dot"
Attributes: M, S

M.PARTIAL ( low.row#\high.row#\low.col#\high.col#\matrix.xpfa -- )

Prints a portion of the matrix specified by low.row# through high.row#, inclusive and low.col# through high.col#, inclusive, using the default print format (FIXED, FLOATING, or SCIENTIFIC). The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained. Printed elements are delimited with spaces and with carriage returns and continuance marks (…). Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE.

Typical use: Assume that MAT.A is dimensioned to have 8 rows and 9 columns. The following command prints the last 5 elements in each of the first 3 rows:

0 2  4 8  ' MAT.A   M.PARTIAL

M.PARTIAL calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also PAUSE.ON.KEY
Pronunciation: "m-dot-partial"
Attributes: M, S

M/MOD ( d1\n1 -- n2\d2 | n2 = remainder, d2 = quotient )

Divides double number d1 by integer n1 giving integer remainder n2 and double number quotient d2. Uses signed math. Division by zero (n1 = 0) yields n2 = 0XFFFF and d2 = FFFF0XFFFF.
Pronunciation: "m-slash-mod"

MAILBOX: ( <name> -- )

Removes the next <name> from the input stream, defines a child word called <name>, and VALLOTs 2 cells in the variable area. When <name> is executed, it leaves the extended address xaddr of the reserved cells that hold the mailbox's contents. <name> is referred to as a "mailbox". Use as:

MAILBOX: <name>

Mailboxes are used in multitasked systems to share information between tasks and to synchronize tasks to one another. If the mailbox's contents equal 0\0, the mailbox is empty; it contains a message if its contents are non-zero. Before its first use, the mailbox must be initialized to 0\0. After initialization to 0\0, the only operators that should access the mailbox are SEND ?SEND RECEIVE and ?RECEIVE. Consult the multitasking chapter for applications information and examples.

Attributes: D

MANTISSA.PLACES ( -- xaddr )

A user variable that holds the number of digits to be displayed in the mantissa when a floating point number is displayed in SCIENTIFIC format.

See also F>FLOATING$

Attributes: U

MATRIX ( <text> -- | expects name and numbers in input stream )

Expects the first word in the input stream following MATRIX to be the name of a dimensioned matrix. Skips the word following the matrix name (typically and then repeatedly calls NEXT.NUMBER to get as many numbers as needed to fill the matrix. The first row is filled first (starting at the left, i.e., at the first column), then the next row, etc. Carriage returns and tabs can be used to format the numbers if desired. The numbers can be valid integers or floating point numbers; NEXT.WORD automatically converts the integers to their floating point equivalents using FLOT. Non-numeric text in the input is ignored until the matrix is filled, but be careful: any valid number encountered by MATRIX will be converted and placed in the matrix, even if it is within parentheses or after a comment delimiter such as \. Integers are converted according to the current number base. Use as

MATRIX: MAT.A 2 3 ' MAT.A DIMMED \ define and dimension

MATRIX MAT.A = 99 3 4.2 5.3 8 \ initialize matrix

Attributes: M, S

MATRIX* ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Performs a matrix multiplication of the two source matrices specified by matrix.xpfa1 and matrix.xpfa2, and dimensions and places the result in the destination specified by matrix.xpfa3. If matrix1 has p rows and m columns, and matrix2 has m rows and n columns, then matrix 3 will be dimensioned to have p rows and n columns. The number of columns in matrix1 must equal the number of rows in matrix2. If DEBUG is ON, aborts if the dimensions of the two sources are incompatible. The destination may be one of the sources.
Pronunciation: "matrix-star"
Attributes: S

MATRIX+ ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Adds each element of the source1 matrix specified by matrix.xpfa1 to the corresponding element of the source2 matrix specified by matrix.xpfa2 and stores the result in the corresponding element in the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if source1 and source2 dimensions are incompatible.
Pronunciation: "matrix-plus"
Attributes: S

MATRIX- ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Subtracts each element of the source2 matrix specified by matrix.xpfa2 from the corresponding element of the source1 matrix specified by matrix.xpfa1 and stores the result in the corresponding element in the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if source1 and source2 dimensions are incompatible.
Pronunciation: "matrix-minus"
Attributes: S

MATRIX->V ( matrix.xpfa -- xvaddr\sep\d.#el )

Converts a matrix specified by matrix.xpfa into the equivalent vector representation specified by xvaddr1\sep\d.#el.

Note: xvaddr is the base address of the vector, sep is the element separation expressed as a multiple of 4 bytes (e.g., sep=1 means a vector of contiguous floating point numbers, sep=2 means elements are separated by 8 bytes, etc.) and d.#el a double number that specifies the number of elements in the vector. Note that xvaddr must be 4-byte aligned (i.e., must be an even multiple of 4). The heap manager and array and matrix dimensioning words automatically perform the required 4-byte alignment.
Pronunciation: "matrix-to-v"

MATRIX.ELEMENT* ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Multiplies each element of the source1 matrix specified by matrix.xpfa1 by the corresponding element of the source2 matrix specified by matrix.xpfa2 and stores the result in the corresponding element in the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if source1 and source2 dimensions are incompatible. This operation should not be confused with a "matrix multiplication".

See also MATRIX*

Pronunciation: "matrix-element-star"
Attributes: S

MATRIX.ELEMENT/ ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Divides each element of the source1 matrix specified by matrix.xpfa1 by the corresponding element of the source2 matrix specified by matrix.xpfa2 and stores the result in the corresponding element in the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if source1 and source2 dimensions are incompatible.
Pronunciation: "matrix-element-divide"
Attributes: S

MATRIX.MAX ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Performs FMAX on each pair of corresponding elements in the source matrices specified by matrix.xpfa1 and matrix.xpfa2, and places the result in the corresponding element of the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if the dimensions of the two sources are incompatible.

MATRIX.MIN ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Performs FMIN on each pair of corresponding elements in the source matrices specified by matrix.xpfa1 and matrix.xpfa2, and places the result in the corresponding element of the destination specified by matrix.xpfa3. Dimensions the destination to have the proper dimensions. The destination may be one of the sources. If DEBUG is ON, aborts if the dimensions of the two sources are incompatible.

MATRIX.PF ( -- u | u = size of a matrix parameter field )

Places on the stack the number of bytes in a matrix parameter field (u = 14 bytes). Typically used to define a stack-based temporary matrix within a definition; temporary matrices defined in this manner preserve re-entrancy (consult the chapter on Designing Re-entrant Code in the Software Manual). For example:

: MATRIX.FUNCTION
   LOCALS{ .... | x&temp.matrix.pfa }
   MATRIX.PF PF.STACK.FRAME   TO  x&temp.matrix.pfa
   3 4 x&temp.matrix.pfa DIMMED   \ dimension as 3X4
   ....         \ use the temp matrix
   x&temp.matrix.pfa DELETED      \ delete from heap
   MATRIX.PF FRAME.DROP      \ drop temp pf off stack
;

See ARRAY.PF, PF.STACK.FRAME and FRAME.DROP.
Pronunciation: "matrix-p-f"

MATRIX.SUM ( matrix.xpfa -- r )

r is the sum of all of the elements in the specified matrix.

Attributes: S

MATRIX.VARIANCE ( matrix.xpfa -- r )

Finds the variance r of the specified matrix. The variance is defined as the sum of the squares of all of the elements.

Attributes: S

MATRIX: ( <name> -- )

Removes <name> from input stream and defines <name> as a matrix. VALLOTs and clears a parameter field for <name> in the variable area; the size of the parameter field is MATRIX.PF bytes. When executed, <name> returns the extended element address given the indices; its stack picture is:

( row#\col# -- xaddr )

The element address is also returned by the command

row# col# ' <name> M[]

MATRIX: does not allocate heap space.

See also DIMMED
Pronunciation: "matrix-colon"
Attributes: D

MAX ( n1\n2 -- [n1] or [n2] )

Retains the greater of the two signed integers n1 and n2, and drops the other. Also

See also UMAX

MAX#DIMENSIONS ( -- xaddr )

A user variable that holds the maximum allowable number of array dimensions. It is used to allocate space for the parameter field when an array is first defined using ARRAY:. It is also used later to compute the size of the parameter fields. The default value is 4, and the minimum value of MAX#DIMENSIONS is 2.

CAUTION: Decide on the maximum number of dimensions that will be used in the entire application program and maintain this value in MAX#DIMENSIONS throughout compilation. Unpredictable results and crashes may occur if arrays are defined (using ARRAY:) while MAX#DIMENSIONS is small, and then dimensioned or operated on when MAX#DIMENSIONS is larger.
Pronunciation: "max-number-of-dimensions"
Attributes: U

MEMBER-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 bytes in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "member"
Attributes: D

MICROSEC.DELAY ( u -- )

Enters a software timing loop for u microseconds. At 16MHz, it can time to within 2 microseconds resolution for 16 ≤ u ≤ 65535 microseconds. Note that the elapsed time will be increased by the duration of any interrupt routines that are serviced while MICROSEC.DELAY is running. Consequently, this routine does not guarantee accurate timing when the timesliced multitasker is running.
Pronunciation: "microsecond-delay"

MIN ( n1\n2 -- [n1] or [n2] )

Retains the lesser of two signed integers n1 and n2, and drops the other.

See also UMIN

MOD ( n1\n2 -- n3 | n3 = remainder of n1/n2 )

Divides n1 by n2, giving the remainder n3. The sign of n3 is the same as that of n1. If n2 is zero the result is indeterminant.

See also UMOD

MOVE ( xaddr1\xaddr2\u -- | xaddr1=src, xaddr2=dest, u = count )

If u is greater than 0, copies u consecutive 16-bit cells (i.e., 2*u consecutive bytes) from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries. If the source and destination regions overlap and xaddr1 < xaddr2, MOVE starts at high memory and moves toward low memory to avoid propagation of the moved contents. MOVE always moves the contents in such a way as to avoid memory propagation. Speed is approximately 38 microseconds per cell.

See also MOVE.MANY

MOVE.IN.PAGE ( addr1\addr2\u\page -- | addr1=src, addr2=dest, u = count )

If u is greater than 0, copies u consecutive 16-bit cells (i.e., 2*u consecutive bytes) starting at addr1 to the destination addresses starting at addr2 on the specified page. If the source and destination regions overlap and addr1 < addr2, MOVE.IN.PAGE starts at high memory and moves toward low memory to avoid propagation of the moved contents. MOVE.IN.PAGE always moves the contents in such a way as to avoid memory propagation. Speed is approximately 15 microseconds per cell.
Pronunciation: "move-in-page"

MOVE.MANY ( xaddr1\xaddr2\d -- | xaddr1=src, xaddr2=dest, d = count )

If 32-bit count d is greater than 0, copies d consecutive 16-bit cells (i.e., 2*d consecutive bytes) from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries. If the source and destination regions overlap and xaddr1 < xaddr2, MOVE.MANY starts at high memory and moves toward low memory to avoid propagation of the moved contents. MOVE.MANY always moves the contents in such a way as to avoid memory propagation. Speed is approximately 38 microseconds per cell.

MT*M ( matrix.xpfa1\matrix.xpfa2 -- )

Multiplies the transpose of the source (matrix.xpfa1) by the source matrix to make the destination matrix matrix.xpfa2. The name of the routine suggests the order of the operands. The destination and the source may be the same.

See also M*MT
Pronunciation: "m-transpose-star-m"
Attributes: S

M[] ( row#\col#\matrix.xpfa -- xaddr )

Places on the stack the extended address xaddr of the element with the specified row# and column# in the matrix specified by matrix.xpfa. When using matrices this is faster than []. If DEBUG is on, ABORTs if the indices are invalid. Use as:

row# column#  ' <matrix.name>  M[]

Pronunciation: "m-brackets"

M[]! ( r\row#\col#\matrix.xpfa -- )

Stores r to the element at row#, column# in the specified matrix. Equivalent to M[] F!.
Pronunciation: "m-brackets-store"

M[]@ ( row#\col#\matrix.xpfa -- r )

Fetches r from the element at row#, column# in the specified matrix. Equivalent to M[] F@.
Pronunciation: "m-brackets-fetch"

NDROP ( wn\...\w1\+n -- | 0 <= +n <= 127 )

Drops +n cells in addition to +n itself from the data stack. +n is a single cell value within the range 0…127. 1 NDROP is equivalent to DROP, 2 NDROP is equivalent to 2DROP.
Pronunciation: "n-drop"

NEEDED ( +n -- )

If DEBUG is true and there are fewer than +n cell units on the data stack (excluding +n), ABORTs the current word and issues a "Data stack underflow" error message.

NEGATE ( n1 -- n2 )

Replaces n1 with its two's complement n2. The two's complement of n1 is computed by inverting each of the bits in n1 and adding 1 to the result.

NEXT ( -- )

Return Stack: ( R: u – [u] or [] | drops index when loop terminates )

Used inside a colon definition to mark the end of a count-down loop structure that is begun by FOR. If the current loop index is zero, discards the index and terminates the loop, continuing execution with the word following NEXT. If the loop index is not 0, NEXT decrements the index by 1 and continues looping by transferring control to the word after FOR. Use as:

u1     FOR  <words to be executed u1+1 times>
   NEXT

0 FOR…NEXT executes 1 time, 1 FOR…NEXT executes 2 times, 65,535 FOR…NEXT executes 65,536 times, etc. FOR…NEXT loops may be nested as long as each FOR is matched with a corresponding NEXT in the same definition as FOR. An error is issued if FOR is not properly paired with NEXT inside a definition. FOR … NEXT loops execute faster than DO … LOOP constructs. The word I may be used inside a FOR NEXT loop. J K I' and LEAVE may not be used in a FOR NEXT loop.

Attributes: C, I

NEXT.NUMBER ( <text> -- r )

Accepts text from the input stream, reading in new lines if necessary, until a space-delimited string representing a valid floating point or integer number is encountered. The floating point representation r of the number is placed on the stack. Integers are converted according to the current number BASE.

See also ASK.FNUMBER and ASK.NUMBER

Attributes: M, S

NEXT.TASK ( -- xaddr )

User variable that contains the 16-bit task identifier (i.e., the base address of the task's user area) of the next task in the round-robin task list.

Attributes: U

NEXT.WORD ( <name> -- addr )

Removes <name> from the input stream, inputting a new line if necessary to get it, leaves the text string in POCKET, and returns the 16-bit address of POCKET (which is in common memory) on the stack.

NFA.FOR ( -- xnfa )

Compile Time: ( <name> – )

Removes <name> from the input stream and returns <name>'s extended name field address xnfa. xnfa is the address of the count byte in <name>'s header. If in execution mode, leaves the xnfa on the stack. If in compilation mode, compiles the xnfa as a 2-cell literal in the current definition; the xnfa is pushed to the stack when the definition later executes. An error occurs if no <name> is given or if <name> cannot be found in the dictionary.
Pronunciation: "n-f-a-for"
Attributes: I

NFA>CFA ( xnfa -- xcfa )

Given the extended name field address xnfa of a header in the dictionary, returns the extended code field address xcfa of the word. xcfa is the first byte of executable machine code associated with the definition. An unchecked error occurs if xnfa is not a valid name field address.

See also NFA.FOR
Pronunciation: "n-f-a-to-c-f-a"

NFA>LFA ( xnfa -- xaddr )

Given the extended name field address xnfa of a header in the dictionary, returns the "link field address" which is the extended xaddr in the header that contains the 3-byte link offset. The link offset consists of a page offset and an address offset which link the specified header to the previous header in the linked list of names. The page offset is a single signed byte stored at xaddr and the address offset is a 16-bit signed offset stored at xaddr+1. Adding the signed address and page offsets to the xnfa yields the xnfa of the previous word in the linked name list.

See also NFA.FOR
Pronunciation: "n-f-a-to-l-f-a"

NFA>PFA ( xnfa -- [xpfa] or [0\0] )

Given the extended name field address xnfa of a header in the dictionary, returns the extended parameter field address xpfa of the word. Returns 0\0 if the word has no pfa (see ?HAS.PFA). An unchecked error occurs if xnfa is not a valid name field address.

See also NFA.FOR
Pronunciation: "n-f-a-to-p-f-a"

NHERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the names area. Equivalent to NP X@
Pronunciation: "n-here"
Attributes: U

NIP ( w1\w2 -- w2 )

Drops the cell below the top cell on the data stack. NIP is equivalent to SWAP DROP.

NO.AUTOSTART ( -- )

Undoes the effect of the AUTOSTART and PRIORITY.AUTOSTART commands and attempts to ensure that the standard QED-Forth interpreter will be entered after subsequent resets. Implementation detail: Erases the 0x1357 pattern at location 0xAE00 (put there by AUTOSTART) in EEPROM, and erases the 0x1357 pattern at location 0x7FFA\4 (put there by PRIORITY.AUTOSTART) in paged memory. Note that the priority.autostart vector at 0x7FFA\4 cannot be erased if the memory is write-protected when NO.AUTOSTART is executed. NO.AUTOSTART is invoked by the special cleanup mode.

NO.OP ( -- )

Does nothing. Used for redefining forward reference words.

See also REDEFINE
Pronunciation: "no-op"

NO.SPACES ( -- xaddr )

A user variable that contains a flag. If the flag is true, leading and trailing spaces are not printed when a floating point number is displayed. If true, the spaces are printed.

See also F>FIXED$, F>FLOATING$, and F>SCIENTIFIC$

Attributes: U

NO.VITAL.IRQ.INIT ( -- )

Writes a pattern into EEPROM so that subsequent cold restarts will not initialize the COP, clock monitor, illegal opcode, and OC2 interrupt vectors. This option is provided for programmers interested in installing their own interrupt service routines in any of these four vectors. Can be undone by INIT.VITAL.IRQS.ON.COLD. Implementation detail: Initializes location 0xAE1B in EEPROM to contain the pattern 0x13.
Pronunciation: "no-vital-i-r-q-init"

NOT ( w -- flag )

flag is the boolean inverse of w. That is, if w = 0, the flag is TRUE. If w is non-zero, the flag is FALSE.

NP ( -- xaddr )

User variable that contains the 32-bit pointer to the names area of the dictionary. The contents of NP are placed on the stack by NHERE and are modified by NALLOT. The command NP X@ is equivalent to NHERE; it yields the xaddr of the next available location in the names area. The command NP @ is equivalent to NPAGE; it yields the page of the names area.
Pronunciation: "n-p"
Attributes: U

NPAGE ( -- page )

Returns the page of the names area in the dictionary. Equivalent to NP @
Pronunciation: "n-page"
Attributes: U

NUMBER ( x$addr -- [n\1] or [d\2] or [0] )

Converts the string whose first character is at x$addr+1 into an integer or double number in the current number base, unless the number starts with 0x or 0X, in which case hexadecimal base is used. If the number can be represented as a 16 bit signed integer, leaves it on the stack under a 1 flag. If it is convertible but cannot be represented as a 16 bit number, leaves its 32 bit representation on the stack under a 2 flag. If a non-convertible character is encountered in the string or if the string does not end with a space, leaves a 0 on the stack. x$addr must end with a space; its count is not used by NUMBER. Except for a leading 0x or 0X or + or - character and isolated embedded commas, no other punctuation is allowed in the numeric string. If a leading 0x or 0X is present, no + or – is allowed in the string. Also

See also FNUMBER

Attributes: S

OC1.ID ( -- n )

Returns the interrupt identity code for output compare 1. This interrupt can control the action of port bits PA3-PA7. Used as an argument for ATTACH.
Pronunciation: "o-c-one-i-d"

OC2.ID ( -- n )

Returns the interrupt identity code for output compare 2. This interrupt can control the action of port bit PA6. Used as an argument for ATTACH. Note that the OC2 interrupt is used by the timeslice multitasker; if you wish to use it for another purpose, make sure that you do not need any of the services of the timeslicer or elapsed-time clock.
Pronunciation: "o-c-two-i-d"

OC3.ID ( -- n )

Returns the interrupt identity code for output compare 3. This interrupt can control the action of port bit PA5. Used as an argument for ATTACH.
Pronunciation: "o-c-three-i-d"

OC4.ID ( -- n )

Returns the interrupt identity code for output compare 4. This interrupt can control the action of port bit PA4. Used as an argument for ATTACH. Note that OC4 and PA4 are used by the optional secondary serial port supported by the QED-Forth software UART; if you are not using the secondary serial port, you may use freely use OC4 and PA4.
Pronunciation: "o-c-four-i-d"

OF ( n1\n2 -- [n1] or [] )

Used inside a CASE … ENDCASE structure to mark the beginning of a conditional statement. If n1 = n2 then n1 and n2 are dropped and execution continues with the words between OF and ENDOF and then skips to the word after ENDCASE. If n1 does not equal n2, then n2 is dropped and execution continues after the next ENDOF. Use as:

n1 CASE
   n2 OF    words to be executed if n1 = n2    ENDOF
   n3 OF    words to be executed if n1 = n3    ENDOF
   words to be executed if n1 doesn't equal n2 or n3
ENDCASE

An error is issued if OF and ENDOF are not properly paired.

Attributes: C, I

OFF ( xaddr -- )

Stores 0 (FALSE) at xaddr.

OFFSET ( -- xaddr )

A user variable that holds the 32-bit difference between the 32-bit physical block number in mass memory and the 16-bit file block number. Used by BUFFER and BLOCK. Set equal to 0\0 by IS.RAMDISK.

Attributes: U

ON ( xaddr -- )

Stores -1 (TRUE) at xaddr.

ON.FORGET ( -- )

Any word named ON.FORGET is executed by FORGET or ANEW before being forgotten. The programmer can define a word with the name ON.FORGET to de-allocate a heap item when the associated data structure is forgotten. This prevents cluttering the heap with memory allocated to forgotten structures during debugging sessions. Typical use:

MATRIX: MAT.A
: DIM.MATRICES  3 3 ' MAT.A  DIMMED ;
: ON.FORGET
   ' MAT.A  DELETED
   ...other cleanup code...
;

If this code is later forgotten, MAT.A is deleted, thus freeing its space in the heap. If the ON.FORGET word had not been included, the definition of MAT.A would have been forgotten, but its heap space would still be allocated. Note that when this definition is compiled, the message

ON.FORGET isn't unique

will be issued. The non-uniqueness does not affect the performance of the word.

ONE ( -- r )

Pushes the floating point number 1.0 onto the data stack.

OR ( w1\w2 -- w3 )

Performs a logical bit-wise inclusive-or of two 16-bit numbers w1 and w2 to produce the result w3.

OR.TYPE.OF: ( u1\u2\u3 -- u1\max{u2,u3}\u1 )

Used inside a variant field declaration started by TYPE.OF: and terminated by TYPE.END within a structure definition. Indicates that the following structure fields are a variant of the fields that followed TYPE.OF: An OR.TYPE.OF: variant should be used for variant fields which are loosely typed; i.e., during the life of the structure, the field content may change type. Also

See also TYPE.OF: for an example of use
Pronunciation: "or-type-of"
Attributes: D

OTHERWISE ( -- )

Marks the start of the "else" portion of a conditional structure that is used in execution mode. Use as:

flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and OTHERWISE is executed, and the code between OTHERWISE and ENDIFTRUE is skipped. If the flag is false, the code between IFTRUE and OTHERWISE is skipped and execution continues with the words following OTHERWISE. OTHERWISE is analogous to ELSE but it is used outside of a colon definition. The execution mode conditional structure can be used to conditionally compile portions of source code. An unchecked error occurs if OTHERWISE is used outside of IFTRUE and ENDIFTRUE. Note that IFTRUE/OTHERWISE/ENDIFTRUE statements can not be nested.

OVER ( w1\w2 -- w1\w2\w1 )

Places a copy of w1 on top of the stack.

OVERFLOW ( -- )

Sets the user variable FP.ERROR to -1 to indicate an overflow error.