% !TeX root = forth.tex % !TeX spellcheck = en_US \chapter{Glossary} % 6 \section{Core words} % 6.1 \wordlist{core} \begin{worddef}{0010}{!}[store] \item \stack{x a-addr}{} Store \param{x} at \param{a-addr}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0010 ! See \tref{core:,}{,}. \end{testing} \end{worddef} \begin{worddef}[num]{0030}{\num}[number-sign] \item \stack{ud_1}{ud_2} Divide \param{ud_1} by the number in \word{BASE} giving the quotient \param{ud_2} and the remainder \param{n}. (\param{n} is the least significant digit of \param{ud_1}.) Convert \param{n} to external form and add the resulting character to the beginning of the pictured numeric output string. An ambiguous condition exists if \word{num} executes outside of a \word{num-start} \word{num-end} delimited number conversion. \see \wref{core:num-end}{\num>}, \wref{core:numS}{\num{}S}, \wref{core:num-start}{<\num}. \begin{testing} % T.6.1.0030 # \texttt{\word{:} GP3 \word{num-start} 1 0 \word{num} \word{num} \word{num-end} \word{Sq} 01" S= \word{;}} \\ \test{GP3}{} \end{testing} \end{worddef} \begin{worddef}[num-end]{0040}{\num>}[number-sign-greater] \item \stack{xd}{c-addr u} Drop \param{xd}. Make the pictured numeric output string available as a character string. \param{c-addr} and \param{u} specify the resulting character string. A program may replace characters within the string. \see \wref{core:num}{\num}, \wref{core:numS}{\num{}S}, \wref{core:num-start}{<\num}. \begin{testing} % T.6.1.0040 #> See \tref{core:num}{\num}, \tref{core:numS}{\num{}S}, \tref{core:HOLD}{HOLD} and \tref{core:SIGN}{SIGN}. \end{testing} \end{worddef} \begin{worddef}[numS]{0050}{\num{}S}[number-sign-s] \item \stack{ud_1}{ud_2} Convert one digit of \param{ud_1} according to the rule for \word{num}. Continue conversion until the quotient is zero. \param{ud_2} is zero. An ambiguous condition exists if \word{numS} executes outside of a \word{num-start} \word{num-end} delimited number conversion. \see \wref{core:num}{\num}, \wref{core:num-end}{\num>}, \wref{core:num-start}{<\num}. \begin{testing} % T.6.1.0050 #S \ttfamily \texttt{\word{:} GP4 \word{num-start} 1 0 \word{numS} \word{num-end} \word{Sq} 1" S= \word{;}} \\ \test{GP4}{} \word{:} GP5 \\ \tab \word{BASE} \word{@} \\ \tab MAX-BASE \word{1+} 2 \word{DO} \tab[2] \word{bs} FOR EACH POSSIBLE BASE \\ \tab[2] \word{I} \word{BASE} \word{!} \tab[5.8] \word{bs} TBD: ASSUMES BASE WORKS \\ \tab[3] \word{I} 0 \word{num-start} \word{numS} \word{num-end} \word{Sq} 10" S= \word{AND} \\ \tab \word{LOOP} \\ \tab \word{SWAP} \word{BASE} \word{!} \word{;} \\ \test{GP5}{} \word{:} GP6 \\ \tab \word{BASE} \word{@} \word{toR} 2 \word{BASE} \word{!} \\ \tab MAX-UINT MAX-UINT \word{num-start} \word{numS} \word{num-end} \tab \word{bs} MAXIMUM UD TO BINARY \\ \tab \word{Rfrom} \word{BASE} \word{!} \tab[10.6] \word{bs} S: C-ADDR U \\ \tab \word{DUP} \#BITS-UD \word{=} \word{SWAP} \\ \tab 0 \word{DO} \tab[13.6] \word{bs} S: C-ADDR FLAG \\ \tab[2] \word{OVER} \word{C@} \word{[CHAR]} 1 \word{=} \word{AND} \tab[1.2] \word{bs} ALL ONES \\ \tab[2] \word{toR} \word{CHAR+} \word{Rfrom} \\ \tab \word{LOOP} \word{SWAP} \word{DROP} \word{;} \\ \test{GP6}{} \word{:} GP7 \\ \tab \word{BASE} \word{@} \word{toR} MAX-BASE \word{BASE} \word{!} \\ \tab \\ \tab A 0 \word{DO} \\ \tab[2] \word{I} 0 \word{num-start} \word{numS} \word{num-end} \\ \tab[2] 1 \word{=} \word{SWAP} \word{C@} \word{I} 30 \word{+} \word{=} \word{AND} \word{AND} \\ \tab \word{LOOP} \\ \tab MAX-BASE A \word{DO} \\ \tab[2] \word{I} 0 \word{num-start} \word{numS} \word{num-end} \\ \tab[2] 1 \word{=} \word{SWAP} \word{C@} 41 \word{I} A \word{-} \word{+} \word{=} \word{AND} \word{AND} \\ \tab \word{LOOP} \\ \tab \word{Rfrom} \word{BASE} \word{!} \word{;} \\ \test{GP7}{} \end{testing} \end{worddef} \pagebreak \begin{worddef}{0070}{'}[tick] \item \stack{"name"}{xt} Skip leading space delimiters. Parse \param{name} delimited by a space. Find \param{name} and return \param{xt}, the execution token for \param{name}. An ambiguous condition exists if \param{name} is not found. When interpreting, \texttt{' xyz EXECUTE} is equivalent to \texttt{xyz}. \see \xref[3.4 The Forth text interpreter]{usage:interpret}, \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:'}{}, \rref{core:POSTPONE}{POSTPONE}, \rref{core:[']}{[']}. \begin{rationale} % A.6.1.0070 ' Typical use: {\ldots} \word{'} \param{name}. Many Forth systems use a state-smart tick. Many do not. Forth-\snapshot\ follows the usage of Forth 94. \see \xref[A.3.4.3..2 Interpretation semantics]{rat:interpret}, \rref{core:FIND}{FIND}. \end{rationale} \begin{testing} % T.6.1.0070 ' \test{\word{:} GT1 123 \word{;} }{ } \\ \test{\word{'} GT1 \word{EXECUTE}}{123} \end{testing} \end{worddef} \begin{worddef}[p]{0080}{(}[paren] \compile Perform the execution semantics given below. \execute \stack{"ccc"}{} Parse \param{ccc} delimited by \texttt{)} (right parenthesis). \word{p} is an immediate word. The number of characters in \param{ccc} may be zero to the number of characters in the parse area. \see \xref[3.4.1 Parsing]{usage:parsing}, \xref[11.6.1.0080 (]{file:p}, \rref{core:p}{}. \begin{rationale} % A.6.1.0080 ( Typical use: {\ldots} \word{p} \param{ccc}\texttt{)} {\ldots} \end{rationale} \begin{testing} \word{bs} \textdf{There is no space either side of the ).}\\[\parskip] \test{\word{p} A comment)1234}{} \\ \test{\word{:} pc1 \word{p} A comment)1234 \word{;} pc1}{1234} \end{testing} \end{worddef} \begin{worddef}{0090}{*}[star] \item \stack{n_1|u_1 n_2|u_2}{n_3|u_3} Multiply \param{n_1|u_1} by \param{n_2|u_2} giving the product \param{n_3|u_3}. \begin{testing} % T.6.1.0090 * \test{ 0 0 \word{*}}{ 0} \tab[4] \word{bs} TEST IDENTITIE{\bs}S \\ \test{ 0 1 \word{*}}{ 0} \\ \test{ 1 0 \word{*}}{ 0} \\ \test{ 1 2 \word{*}}{ 2} \\ \test{ 2 1 \word{*}}{ 2} \\ \test{ 3 3 \word{*}}{ 9} \\ \test{-3 3 \word{*}}{-9} \\ \test{ 3 -3 \word{*}}{-9} \\ \test{-3 -3 \word{*}}{ 9} \test{MID-UINT+1 1 \word{RSHIFT} 2 \word{*} }{MID-UINT+1} \\ \test{MID-UINT+1 2 \word{RSHIFT} 4 \word{*} }{MID-UINT+1} \\ \test{MID-UINT+1 1 \word{RSHIFT} MID-UINT+1 \word{OR} 2 \word{*}}{MID-UINT+1} \\ \end{testing} \end{worddef} \begin{worddef}{0100}{*/}[star-slash] \item \stack{n_1 n_2 n_3}{n_4} Multiply \param{n_1} by \param{n_2} producing the intermediate double-cell result $d$. Divide $d$ by \param{n_3} giving the single-cell quotient \param{n_4}. An ambiguous condition exists if \param{n_3} is zero or if the quotient \param{n_4} lies outside the range of a signed number. If $d$ and \param{n_3} differ in sign, the implementation-defined result returned will be the same as that returned by either the phrase \word{toR} \word{M*} \word{Rfrom} \word{FM/MOD} \word{SWAP} \word{DROP} or the phrase \word{toR} \word{M*} \word{Rfrom} \word{SM/REM} \word{SWAP} \word{DROP}. \see \xref[3.2.2.1 Integer division]{usage:div}. \begin{testing} % T.6.1.0100 */ \ttfamily IFFLOORED \tab \word{:} T*/ T*/MOD \word{SWAP} \word{DROP} \word{;} \\ IFSYM \tab[2.8] \word{:} T*/ T*/MOD \word{SWAP} \word{DROP} \word{;} \test{ 0 2 1 \word{*/}}{ 0 2 1 T*/} \\ \test{ 1 2 1 \word{*/}}{ 1 2 1 T*/} \\ \test{ 2 2 1 \word{*/}}{ 2 2 1 T*/} \\ \test{ -1 2 1 \word{*/}}{ -1 2 1 T*/} \\ \test{ -2 2 1 \word{*/}}{ -2 2 1 T*/} \\ \test{ 0 2 -1 \word{*/}}{ 0 2 -1 T*/} \\ \test{ 1 2 -1 \word{*/}}{ 1 2 -1 T*/} \\ \test{ 2 2 -1 \word{*/}}{ 2 2 -1 T*/} \\ \test{ -1 2 -1 \word{*/}}{ -1 2 -1 T*/} \\ \test{ -2 2 -1 \word{*/}}{ -2 2 -1 T*/} \\ \test{ 2 2 2 \word{*/}}{ 2 2 2 T*/} \\ \test{ -1 2 -1 \word{*/}}{ -1 2 -1 T*/} \\ \test{ -2 2 -2 \word{*/}}{ -2 2 -2 T*/} \\ \test{ 7 2 3 \word{*/}}{ 7 2 3 T*/} \\ \test{ 7 2 -3 \word{*/}}{ 7 2 -3 T*/} \\ \test{ -7 2 3 \word{*/}}{ -7 2 3 T*/} \\ \test{ -7 2 -3 \word{*/}}{ -7 2 -3 T*/} \\ \test{MAX-INT 2 MAX-INT \word{*/}}{MAX-INT 2 MAX-INT T*/} \\ \test{MIN-INT 2 MIN-INT \word{*/}}{MIN-INT 2 MIN-INT T*/} \end{testing} \end{worddef} \pagebreak \begin{worddef}{0110}{*/MOD}[star-slash-mod] \item \stack{n_1 n_2 n_3}{n_4 n_5} Multiply \param{n_1} by \param{n_2} producing the intermediate double-cell result $d$. Divide $d$ by \param{n_3} producing the single-cell remainder \param{n_4} and the single-cell quotient \param{n_5}. An ambiguous condition exists if \param{n_3} is zero, or if the quotient \param{n_5} lies outside the range of a single-cell signed integer. If $d$ and \param{n_3} differ in sign, the implementation-defined result returned will be the same as that returned by either the phrase \word{toR} \word{M*} \word{Rfrom} \word{FM/MOD} or the phrase \word{toR} \word{M*} \word{Rfrom} \word{SM/REM}. \see \xref[3.2.2.1 Integer division]{usage:div}. \begin{testing} % T.6.1.0110 */MOD \ttfamily IFFLOORED \tab \word{:} T*/MOD \word{toR} \word{M*} \word{Rfrom} \word{FM/MOD} \word{;} \\ IFSYM \tab[2.8] \word{:} T*/MOD \word{toR} \word{M*} \word{Rfrom} \word{SM/REM} \word{;} \test{ 0 2 1 \word{*/MOD}}{ 0 2 1 T*/MOD} \\ \test{ 1 2 1 \word{*/MOD}}{ 1 2 1 T*/MOD} \\ \test{ 2 2 1 \word{*/MOD}}{ 2 2 1 T*/MOD} \\ \test{ -1 2 1 \word{*/MOD}}{ -1 2 1 T*/MOD} \\ \test{ -2 2 1 \word{*/MOD}}{ -2 2 1 T*/MOD} \\ \test{ 0 2 -1 \word{*/MOD}}{ 0 2 -1 T*/MOD} \\ \test{ 1 2 -1 \word{*/MOD}}{ 1 2 -1 T*/MOD} \\ \test{ 2 2 -1 \word{*/MOD}}{ 2 2 -1 T*/MOD} \\ \test{ -1 2 -1 \word{*/MOD}}{ -1 2 -1 T*/MOD} \\ \test{ -2 2 -1 \word{*/MOD}}{ -2 2 -1 T*/MOD} \\ \test{ 2 2 2 \word{*/MOD}}{ 2 2 2 T*/MOD} \\ \test{ -1 2 -1 \word{*/MOD}}{ -1 2 -1 T*/MOD} \\ \test{ -2 2 -2 \word{*/MOD}}{ -2 2 -2 T*/MOD} \\ \test{ 7 2 3 \word{*/MOD}}{ 7 2 3 T*/MOD} \\ \test{ 7 2 -3 \word{*/MOD}}{ 7 2 -3 T*/MOD} \\ \test{ -7 2 3 \word{*/MOD}}{ -7 2 3 T*/MOD} \\ \test{ -7 2 -3 \word{*/MOD}}{ -7 2 -3 T*/MOD} \\ \test{MAX-INT 2 MAX-INT \word{*/MOD}}{MAX-INT 2 MAX-INT T*/MOD} \\ \test{MIN-INT 2 MIN-INT \word{*/MOD}}{MIN-INT 2 MIN-INT T*/MOD} \end{testing} \end{worddef} \begin{worddef}{0120}{+}[plus] \item \stack{n_1|u_1 n_2|u_2}{n_3|u_3} Add \param{n_2|u_2} to \param{n_1|u_1}, giving the sum \param{n_3|u_3}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0120 + \test{ 0 5 \word{+}}{ 5} \\ \test{ 5 0 \word{+}}{ 5} \\ \test{ 0 -5 \word{+}}{ -5} \\ \test{ -5 0 \word{+}}{ -5} \\ \test{ 1 2 \word{+}}{ 3} \\ \test{ 1 -2 \word{+}}{ -1} \\ \test{ -1 2 \word{+}}{ 1} \\ \test{ -1 -2 \word{+}}{ -3} \\ \test{ -1 1 \word{+}}{ 0} \\ \test{MID-UINT 1 \word{+}}{MID-UINT+1} \end{testing} \end{worddef} \begin{worddef}{0130}{+!}[plus-store] \item \stack{n|u a-addr}{} Add \param{n|u} to the single-cell number at \param{a-addr}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0130 +! \test{ 0 1ST \word{!} }{ } \\ \test{ 1 1ST \word{+!} }{ } \\ \test{ 1ST \word{@} }{1} \\ \test{-1 1ST \word{+!} 1ST \word{@}}{0} \end{testing} \end{worddef} \begin{worddef}{0140}{+LOOP}[plus-loop] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{do-sys}{} Append the run-time semantics given below to the current definition. Resolve the destination of all unresolved occurrences of \word{LEAVE} between the location given by \param{do-sys} and the next location for a transfer of control, to execute the words following \word{+LOOP}. \runtime \stack{n}{} \stack[R]{loop-sys_1}{|loop-sys_2} An ambiguous condition exists if the loop control parameters are unavailable. Add \param{n} to the loop index. If the loop index did not cross the boundary between the loop limit minus one and the loop limit, continue execution at the beginning of the loop. Otherwise, discard the current loop control parameters and continue execution immediately following the loop. \see \wref{core:DO}{DO}, \wref{core:I}{I}, \wref{core:LEAVE}{LEAVE}, \rref{core:+LOOP}{}. \begin{rationale} % A.6.1.0140 +LOOP Typical use: \word{:} \texttt{X} ~{\ldots} limit first \word{DO} {\ldots} step \word{+LOOP} \word{;} \end{rationale} \begin{testing} % T.6.1.0140 +LOOP \ttfamily \test{\word{:} GD2 \word{DO} \word{I} -1 \word{+LOOP} \word{;}}{} \\ \test{ 1 4 GD2}{4 3 2 1} \\ \test{ -1 2 GD2}{2 1 0 -1} \\ \test{MID-UINT MID-UINT+1 GD2}{MID-UINT+1 MID-UINT} \word{VARIABLE} gditerations \\ \word{VARIABLE} gdincrement \word{:} gd7 \word{p} limit start increment -{}- ) \\ \tab gdincrement \word{!} \\ \tab 0 gditerations \word{!} \\ \tab \word{DO} \\ \tab[2] 1 gditerations \word{+!} \\ \tab[2] \word{I} \\ \tab[2] gditerations \word{@} 6 \word{=} \word{IF} \word{LEAVE} \word{THEN} \\ \tab[2] gdincrement \word{@} \\ \tab \word{+LOOP} gditerations \word{@} \\ \word{;} \test{ 4 4 -1 gd7}{ 4 1 } \\ \test{ 1 4 -1 gd7}{ 4 3 2 1 4 } \\ \test{ 4 1 -1 gd7}{ 1 0 -1 -2 -3 -4 6 } \\ \test{ 4 1 0 gd7}{ 1 1 1 1 1 1 6 } \\ \test{ 0 0 0 gd7}{ 0 0 0 0 0 0 6 } \\ \test{ 1 4 0 gd7}{ 4 4 4 4 4 4 6 } \\ \test{ 1 4 1 gd7}{ 4 5 6 7 8 9 6 } \\ \test{ 4 1 1 gd7}{ 1 2 3 3 } \\ \test{ 4 4 1 gd7}{ 4 5 6 7 8 9 6 } \\ \test{ 2 -1 -1 gd7}{-1 -2 -3 -4 -5 -6 6 } \\ \test{ -1 2 -1 gd7}{ 2 1 0 -1 4 } \\ \test{ 2 -1 0 gd7}{-1 -1 -1 -1 -1 -1 6 } \\ \test{ -1 2 0 gd7}{ 2 2 2 2 2 2 6 } \\ \test{ -1 2 1 gd7}{ 2 3 4 5 6 7 6 } \\ \test{ 2 -1 1 gd7}{-1 0 1 3 } \\ \test{ -20 30 -10 gd7}{30 20 10 0 -10 -20 6 } \\ \test{ -20 31 -10 gd7}{31 21 11 1 -9 -19 6 } \\ \test{ -20 29 -10 gd7}{29 19 9 -1 -11 5 } \word{bs} \textdf{With large and small increments} MAX-UINT 8 RSHIFT 1+ CONSTANT ustep \\ ustep NEGATE CONSTANT -ustep \\ MAX-INT 7 RSHIFT 1+ CONSTANT step \\ step NEGATE CONSTANT -step \word{VARIABLE} bump \test{ \word{:} gd8 bump \word{!} \word{DO} \word{1+} bump \word{@} \word{+LOOP} \word{;}}{} \test{ 0 MAX-UINT 0 ustep gd8}{256} \\ \test{ 0 0 MAX-UINT -ustep gd8}{256} \\ \test{ 0 MAX-INT MIN-INT step gd8}{256} \\ \test{ 0 MIN-INT MAX-INT -step gd8}{256} \end{testing} \end{worddef} \pagebreak \begin{worddef}{0150}{,}[comma] \item \stack{x}{} Reserve one cell of data space and store \param{x} in the cell. If the data-space pointer is aligned when \word{,} begins execution, it will remain aligned when \word{,} finishes execution. An ambiguous condition exists if the data-space pointer is not aligned prior to execution of \word{,}. \see \xref[3.3.3 Data space]{usage:dataspace}, \xref[3.3.3.1 Address alignment]{usage:aaddr}, \rref{core:,}{}. \begin{rationale} % A.6.1.0150 , The use of \word{,} (comma) for compiling execution tokens is not portable. See: \wref{core:COMPILE,}{COMPILE,}. \end{rationale} \begin{testing} % T.6.1.0150 , \ttfamily \word{HERE} 1 \word{,} \\ \word{HERE} 2 \word{,} \\ \word{CONSTANT} 2ND \\ \word{CONSTANT} 1ST \test{ 1ST 2ND \word{Uless}}{} \word{bs} HERE MUST GROW WITH ALLOT \\ \test{ 1ST \word{CELL+} }{2ND} \word{bs} {\ldots} BY ONE CELL \\ \test{ 1ST 1 \word{CELLS} \word{+} }{2ND} \\ \test{ 1ST \word{@} 2ND \word{@} }{1 2} \\ \test{ 5 1ST \word{!} }{ } \\ \test{ 1ST \word{@} 2ND \word{@} }{5 2} \\ \test{ 6 2ND \word{!} }{ } \\ \test{ 1ST \word{@} 2ND \word{@} }{5 6} \\ \test{ 1ST \word{2@}}{6 5} \\ \test{ 2 1 1ST \word{2!}}{ } \\ \test{ 1ST \word{2@}}{2 1} \\ \test{1S 1ST \word{!} 1ST \word{@} }{1S } \tab \word{bs} CAN STORE CELL-WIDE VALUE \end{testing} \end{worddef} \begin{worddef}{0160}{-}[minus] \item \stack{n_1|u_1 n_2|u_2}{n_3|u_3} Subtract \param{n_2|u_2} from \param{n_1|u_1}, giving the difference \param{n_3|u_3}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0160 - \test{ 0 5 \word{-}}{ -5} \\ \test{ 5 0 \word{-}}{ 5} \\ \test{ 0 -5 \word{-}}{ 5} \\ \test{ -5 0 \word{-}}{ -5} \\ \test{ 1 2 \word{-}}{ -1} \\ \test{ 1 -2 \word{-}}{ 3} \\ \test{ -1 2 \word{-}}{ -3} \\ \test{ -1 -2 \word{-}}{ 1} \\ \test{ 0 1 \word{-}}{ -1} \\ \test{MID-UINT+1 1 \word{-}}{MID-UINT} \end{testing} \end{worddef} \begin{worddef}[d]{0180}{.{}}[dot] \item \stack{n}{} Display \param{n} in free field format. \see \xref[3.2.1.2 Digit conversion]{usage:digits}, \xref[3.2.1.3 Free-field number display]{usage:dot}. \begin{testing} % T.6.1.0180 . See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \begin{worddef}[.q]{0190}{."}[dot-quote] \interpret Interpretation semantics for this word are undefined. \compile \stack{"ccc"}{} Parse \param{ccc} delimited by \texttt{"} (double-quote). Append the run-time semantics given below to the current definition. \runtime \stack{}{} Display \param{ccc}. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:.p}{.(}, \rref{core:.q}{}. \begin{rationale} % A.6.1.0190 ." Typical use: \word{:} \texttt{X} {\ldots} \word{.q} \emph{ccc}\texttt{"} {\ldots} \word{;} An implementation may define interpretation semantics for \word{.q} if desired. In one plausible implementation, interpreting \word{.q} would display the delimited message. In another plausible implementation, interpreting \word{.q} would compile code to display the message later. In still another plausible implementation, interpreting \word{.q} would be treated as an exception. Given this variation a Standard Program may not use \word{.q} while interpreting. Similarly, a Standard Program may not compile \word{POSTPONE} \word{.q} inside a new word, and then use that word while interpreting. \end{rationale} \begin{testing} % T.6.1.0190 ." \test{\word{:} pb1 \word{CR} \word{.q} You should see 2345: "\word{.q} 2345"\word{;} pb1}{} See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \enlargethispage{4ex} \begin{worddef}{0230}{/}[slash] \item \stack{n_1 n_2}{n_3} Divide \param{n_1} by \param{n_2}, giving the single-cell quotient \param{n_3}. An ambiguous condition exists if \param{n_2} is zero. If \param{n_1} and \param{n_2} differ in sign, the implementation-defined result returned will be the same as that returned by either the phrase \word{toR} \word{StoD} \word{Rfrom} \word{FM/MOD} \word{SWAP} \word{DROP} or the phrase \word{toR} \word{StoD} \word{Rfrom} \word{SM/REM} \word{SWAP} \word{DROP}. \see \xref[3.2.2.1 Integer division]{usage:div}. \begin{testing} % T.6.1.0230 / \ttfamily IFFLOORED \tab \word{:} T/ T/MOD \word{SWAP} \word{DROP} \word{;} \\ IFSYM \tab[2.8] \word{:} T/ T/MOD \word{SWAP} \word{DROP} \word{;} \test{ 0 1 \word{/}}{ 0 1 T/} \\ \test{ 1 1 \word{/}}{ 1 1 T/} \\ \test{ 2 1 \word{/}}{ 2 1 T/} \\ \test{ -1 1 \word{/}}{ -1 1 T/} \\ \test{ -2 1 \word{/}}{ -2 1 T/} \\ \test{ 0 -1 \word{/}}{ 0 -1 T/} \\ \test{ 1 -1 \word{/}}{ 1 -1 T/} \\ \test{ 2 -1 \word{/}}{ 2 -1 T/} \\ \test{ -1 -1 \word{/}}{ -1 -1 T/} \\ \test{ -2 -1 \word{/}}{ -2 -1 T/} \\ \test{ 2 2 \word{/}}{ 2 2 T/} \\ \test{ -1 -1 \word{/}}{ -1 -1 T/} \\ \test{ -2 -2 \word{/}}{ -2 -2 T/} \\ \test{ 7 3 \word{/}}{ 7 3 T/} \\ \test{ 7 -3 \word{/}}{ 7 -3 T/} \\ \test{ -7 3 \word{/}}{ -7 3 T/} \\ \test{ -7 -3 \word{/}}{ -7 -3 T/} \\ \test{MAX-INT 1 \word{/}}{MAX-INT 1 T/} \\ \test{MIN-INT 1 \word{/}}{MIN-INT 1 T/} \\ \test{MAX-INT MAX-INT \word{/}}{MAX-INT MAX-INT T/} \\ \test{MIN-INT MIN-INT \word{/}}{MIN-INT MIN-INT T/} \end{testing} \end{worddef} \begin{worddef}{0240}{/MOD}[slash-mod] \item \stack{n_1 n_2}{n_3 n_4} Divide \param{n_1} by \param{n_2}, giving the single-cell remainder \param{n_3} and the single-cell quotient \param{n_4}. An ambiguous condition exists if \param{n_2} is zero. If \param{n_1} and \param{n_2} differ in sign, the implementation-defined result returned will be the same as that returned by either the phrase \word{toR} \word{StoD} \word{Rfrom} \word{FM/MOD} or the phrase \word{toR} \word{StoD} \word{Rfrom} \word{SM/REM}. \see \xref[3.2.2.1 Integer division]{usage:div}. \begin{testing} % T.6.1.0240 /MOD \ttfamily IFFLOORED \tab \word{:} T/MOD \word{toR} \word{StoD} \word{Rfrom} \word{FM/MOD} \word{;} \\ IFSYM \tab[2.8] \word{:} T/MOD \word{toR} \word{StoD} \word{Rfrom} \word{SM/REM} \word{;} \test{ 0 1 \word{/MOD}}{ 0 1 T/MOD} \\ \test{ 1 1 \word{/MOD}}{ 1 1 T/MOD} \\ \test{ 2 1 \word{/MOD}}{ 2 1 T/MOD} \\ \test{ -1 1 \word{/MOD}}{ -1 1 T/MOD} \\ \test{ -2 1 \word{/MOD}}{ -2 1 T/MOD} \\ \test{ 0 -1 \word{/MOD}}{ 0 -1 T/MOD} \\ \test{ 1 -1 \word{/MOD}}{ 1 -1 T/MOD} \\ \test{ 2 -1 \word{/MOD}}{ 2 -1 T/MOD} \\ \test{ -1 -1 \word{/MOD}}{ -1 -1 T/MOD} \\ \test{ -2 -1 \word{/MOD}}{ -2 -1 T/MOD} \\ \test{ 2 2 \word{/MOD}}{ 2 2 T/MOD} \\ \test{ -1 -1 \word{/MOD}}{ -1 -1 T/MOD} \\ \test{ -2 -2 \word{/MOD}}{ -2 -2 T/MOD} \\ \test{ 7 3 \word{/MOD}}{ 7 3 T/MOD} \\ \test{ 7 -3 \word{/MOD}}{ 7 -3 T/MOD} \\ \test{ -7 3 \word{/MOD}}{ -7 3 T/MOD} \\ \test{ -7 -3 \word{/MOD}}{ -7 -3 T/MOD} \\ \test{MAX-INT 1 \word{/MOD}}{MAX-INT 1 T/MOD} \\ \test{MIN-INT 1 \word{/MOD}}{MIN-INT 1 T/MOD} \\ \test{MAX-INT MAX-INT \word{/MOD}}{MAX-INT MAX-INT T/MOD} \\ \test{MIN-INT MIN-INT \word{/MOD}}{MIN-INT MIN-INT T/MOD} \end{testing} \end{worddef} \begin{worddef}[0less]{0250}{0<}[zero-less] \item \stack{n}{flag} \param{flag} is true if and only if \param{n} is less than zero. \begin{testing} % T.6.1.0250 0< \test{ 0 \word{0less}}{} \\ \test{ -1 \word{0less}}{ } \\ \test{MIN-INT \word{0less}}{ } \\ \test{ 1 \word{0less}}{} \\ \test{MAX-INT \word{0less}}{} \end{testing} \end{worddef} \begin{worddef}{0270}{0=}[zero-equals] \item \stack{x}{flag} \param{flag} is true if and only if \param{x} is equal to zero. \begin{testing} % T.6.1.0270 0= \test{ 0 \word{0=}}{ } \\ \test{ 1 \word{0=}}{} \\ \test{ 2 \word{0=}}{} \\ \test{ -1 \word{0=}}{} \\ \test{MAX-UINT \word{0=}}{} \\ \test{MIN-INT \word{0=}}{} \\ \test{MAX-INT \word{0=}}{} \end{testing} \end{worddef} \begin{worddef}{0290}{1+}[one-plus] \item \stack{n_1|u_1}{n_2|u_2} Add one (1) to \param{n_1|u_1} giving the sum \param{n_2|u_2}. \begin{testing} % T.6.1.0290 1+ \test{ 0 \word{1+}}{ 1} \\ \test{ -1 \word{1+}}{ 0} \\ \test{ 1 \word{1+}}{ 2} \\ \test{MID-UINT \word{1+}}{MID-UINT+1} \end{testing} \end{worddef} \begin{worddef}{0300}{1-}[one-minus] \item \stack{n_1|u_1}{n_2|u_2} Subtract one (1) from \param{n_1|u_1} giving the difference \param{n_2|u_2}. \begin{testing} % T.6.1.0300 1- \test{ 2 \word{1-}}{ 1} \\ \test{ 1 \word{1-}}{ 0} \\ \test{ 0 \word{1-}}{ -1} \\ \test{MID-UINT+1 \word{1-}}{MID-UINT} \end{testing} \end{worddef} \begin{worddef}{0310}{2!}[two-store] \item \stack{x_1 x_2 a-addr}{} Store the cell pair \param{x_1 x_2} at \param{a-addr}, with \param{x_2} at \param{a-addr} and \param{x_1} at the next consecutive cell. It is equivalent to the sequence \word{SWAP} \word{OVER} \word{!} \word{CELL+} \word{!}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0310 2! See \tref{core:,}{,}. \end{testing} \end{worddef} \begin{worddef}{0320}{2*}[two-star] \item \stack{x_1}{x_2} \param{x_2} is the result of shifting \param{x_1} one bit toward the most-significant bit, filling the vacated least-significant bit with zero. \begin{testing} % T.6.1.0320 2* \test{ 0S \word{2*} }{ 0S} \\ \test{ 1 \word{2*} }{ 2} \\ \test{4000 \word{2*} }{8000} \\ \test{ 1S \word{2*} 1 \word{XOR}}{ 1S} \\ \test{ MSB \word{2*} }{ 0S} \end{testing} \end{worddef} \begin{worddef}{0330}{2/}[two-slash] \item \stack{x_1}{x_2} \param{x_2} is the result of shifting \param{x_1} one bit toward the least-significant bit, leaving the most-significant bit unchanged. \begin{testing} % T.6.1.0330 2/ \test{ 0S \word{2/}}{ 0S} \\ \test{ 1 \word{2/}}{ 0} \\ \test{ 4000 \word{2/}}{2000} \\ \test{ 1S \word{2/}}{ 1S} \word{bs} MSB PROPOGATED \\ \test{ 1S 1 \word{XOR} \word{2/}}{ 1S} \\ \test{MSB \word{2/} MSB \word{AND}}{ MSB} \end{testing} \end{worddef} \begin{worddef}{0350}{2@}[two-fetch] \item \stack{a-addr}{x_1 x_2} Fetch the cell pair \param{x_1 x_2} stored at \param{a-addr}. \param{x_2} is stored at \param{a-addr} and \param{x_1} at the next consecutive cell. It is equivalent to the sequence \word{DUP} \word{CELL+} \word{@} \word{SWAP} \word{@}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}, \wref{core:2!}{2!}. \begin{testing} % T.6.1.0350 2@ See \tref{core:,}{,}. \end{testing} \end{worddef} \begin{worddef}{0370}{2DROP}[two-drop] \item \stack{x_1 x_2}{} Drop cell pair \param{x_1 x_2} from the stack. \begin{testing} % T.6.1.0370 2DROP \test{1 2 \word{2DROP}}{} \end{testing} \end{worddef} \begin{worddef}{0380}{2DUP}[two-dupe] \item \stack{x_1 x_2}{x_1 x_2 x_1 x_2} Duplicate cell pair \param{x_1 x_2}. \begin{testing} % T.6.1.0380 2DUP \test{1 2 \word{2DUP}}{1 2 1 2} \end{testing} \end{worddef} \begin{worddef}{0400}{2OVER}[two-over] \item \stack{x_1 x_2 x_3 x_4}{x_1 x_2 x_3 x_4 x_1 x_2} Copy cell pair \param{x_1 x_2} to the top of the stack. \begin{testing} % T.6.1.0400 2OVER \test{1 2 3 4 \word{2OVER}}{1 2 3 4 1 2} \end{testing} \end{worddef} \begin{worddef}{0430}{2SWAP}[two-swap] \item \stack{x_1 x_2 x_3 x_4}{x_3 x_4 x_1 x_2} Exchange the top two cell pairs. \begin{testing} % T.6.1.0430 2SWAP \test{1 2 3 4 \word{2SWAP}}{3 4 1 2} \end{testing} \end{worddef} \begin{worddef}{0450}{:}[colon] \item \stack[C]{"name"}{colon-sys} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name}, called a ``colon definition''. Enter compilation state and start the current definition, producing \param{colon-sys}. Append the initiation semantics given below to the current definition. The execution semantics of \param{name} will be determined by the words compiled into the body of the definition. The current definition shall not be findable in the dictionary until it is ended (or until the execution of \word{DOES} in some systems). \init \stack{i*x}{i*x} \stack[R]{}{nest-sys} Save implementation-dependent information \param{nest-sys} about the calling definition. The stack effects \param{i*x} represent arguments to \param{name}. \execute[name] \stack{i*x}{j*x} Execute the definition \param{name}. The stack effects \param{i*x} and \param{j*x} represent arguments to and results from \param{name}, respectively. \see \xref[3.4 The Forth text interpreter]{usage:interpret}, \xref[3.4.1 Parsing]{usage:parsing}, \xref[3.4.5 Compilation]{usage:compilation}, \wref{core:DOES}{DOES>}, \wref{core:[}{[}, \wref{core:]}{]}, \wref{tools:;CODE}{;CODE}, \rref{core::}{}. \begin{rationale} % A.6.1.0450 : Typical use: \word{:} \emph{name} {\ldots} \word{;} In Forth 83, this word was specified to alter the search order. This specification is explicitly removed in this standard. We believe that in most cases this has no effect; however, systems that allow many search orders found the Forth-83 behavior of colon very undesirable. Note that colon does not itself invoke the compiler. Colon sets compilation state so that later words in the parse area are compiled. \end{rationale} \begin{testing} % T.6.1.0450 : \test{\word{:} NOP \word{:} \word{POSTPONE} \word{;} \word{;}}{} \\ \test{NOP NOP1 NOP NOP2}{} \\ \test{NOP1}{} \\ \test{NOP2}{} The following tests the dictionary search order: \test{\word{:} GDX 123 \word{;} \tab \word{:} GDX GDX 234 \word{;}}{} \\ \test{GDX}{123 234} \end{testing} \end{worddef} \begin{worddef}{0460}{;}[semicolon] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{colon-sys}{} Append the run-time semantics below to the current definition. End the current definition, allow it to be found in the dictionary and enter interpretation state, consuming \param{colon-sys}. If the data-space pointer is not aligned, reserve enough data space to align it. \runtime \stack{}{} \stack[R]{nest-sys}{} Return to the calling definition specified by \param{nest-sys}. \see \xref[3.4 The Forth text interpreter]{usage:command}, \xref[3.4.5 Compilation]{usage:compilation}, \rref{core:;}{}. \begin{rationale} % A.6.1.0460 ; Typical use: \word{:} \emph{name} {\ldots} \word{;} One function performed by both \word{;} and \word[tools]{;CODE} is to allow the current definition to be found in the dictionary. If the current definition was created by \word{:NONAME} the current definition has no definition name and thus cannot be found in the dictionary. If \word{:NONAME} is implemented the Forth compiler must maintain enough information about the current definition to allow \word{;} and \word[tools]{;CODE} to determine whether or not any action must be taken to allow it to be found. \end{rationale} \begin{testing} % T.6.1.0460 ; See \tref{core::}{:}. \end{testing} \end{worddef} \begin{worddef}[less]{0480}{<}[less-than] \item \stack{n_1 n_2}{flag} \param{flag} is true if and only if \param{n_1} is less than \param{n_2}. \see \wref{core:Uless}{U<}. \begin{testing} % T.6.1.0480 < \test{ 0 1 \word{less}}{ } \\ \test{ 1 2 \word{less}}{ } \\ \test{ -1 0 \word{less}}{ } \\ \test{ -1 1 \word{less}}{ } \\ \test{MIN-INT 0 \word{less}}{ } \\ \test{MIN-INT MAX-INT \word{less}}{ } \\ \test{ 0 MAX-INT \word{less}}{ } \\ \test{ 0 0 \word{less}}{} \\ \test{ 1 1 \word{less}}{} \\ \test{ 1 0 \word{less}}{} \\ \test{ 2 1 \word{less}}{} \\ \test{ 0 -1 \word{less}}{} \\ \test{ 1 -1 \word{less}}{} \\ \test{ 0 MIN-INT \word{less}}{} \\ \test{MAX-INT MIN-INT \word{less}}{} \\ \test{MAX-INT 0 \word{less}}{} \end{testing} \end{worddef} \begin{worddef}[num-start]{0490}{<\num}[less-number-sign] \item \stack{}{} Initialize the pictured numeric output conversion process. \see \wref{core:num}{\num}, \wref{core:num-end}{\num>}, \wref{core:numS}{\num{}S}. \begin{testing} % T.6.1.0490 <# See \tref{core:num}{\num}, \tref{core:numS}{\num{}S}, \tref{core:HOLD}{HOLD}, \tref{core:SIGN}{SIGN}. \end{testing} \end{worddef} \begin{worddef}{0530}{=}[equals] \item \stack{x_1 x_2}{flag} \param{flag} is true if and only if \param{x_1} is bit-for-bit the same as \param{x_2}. \begin{testing} % T.6.1.0530 = \test{ 0 0 \word{=}}{ } \\ \test{ 1 1 \word{=}}{ } \\ \test{-1 -1 \word{=}}{ } \\ \test{ 1 0 \word{=}}{} \\ \test{-1 0 \word{=}}{} \\ \test{ 0 1 \word{=}}{} \\ \test{ 0 -1 \word{=}}{} \\ \end{testing} \end{worddef} \begin{worddef}[more]{0540}{>}[greater-than] \item \stack{n_1 n_2}{flag} \param{flag} is true if and only if \param{n_1} is greater than \param{n_2}. \see \wref{core:Umore}{U>}. \begin{testing} % T.6.1.0540 > \test{ 0 1 \word{more}}{} \\ \test{ 1 2 \word{more}}{} \\ \test{ -1 0 \word{more}}{} \\ \test{ -1 1 \word{more}}{} \\ \test{MIN-INT 0 \word{more}}{} \\ \test{MIN-INT MAX-INT \word{more}}{} \\ \test{ 0 MAX-INT \word{more}}{} \\ \test{ 0 0 \word{more}}{} \\ \test{ 1 1 \word{more}}{} \\ \test{ 1 0 \word{more}}{ } \\ \test{ 2 1 \word{more}}{ } \\ \test{ 0 -1 \word{more}}{ } \\ \test{ 1 -1 \word{more}}{ } \\ \test{ 0 MIN-INT \word{more}}{ } \\ \test{MAX-INT MIN-INT \word{more}}{ } \\ \test{MAX-INT 0 \word{more}}{ } \end{testing} \end{worddef} \begin{worddef}[toBODY]{0550}{>BODY}[to-body] \item \stack{xt}{a-addr} \param{a-addr} is the data-field address corresponding to \param{xt}. An ambiguous condition exists if \param{xt} is not for a word defined via \word{CREATE}. \see \xref[3.3.3 Data space]{usage:dataspace}, \rref{core:toBODY}{}. \begin{rationale} % A.6.1.0550 >BODY \param{a-addr} is the address that \word{HERE} would have returned had it been executed immediately after the execution of the \word{CREATE} that defined \param{xt}. \end{rationale} \begin{testing} % T.6.1.0550 >BODY \test{ \word{CREATE} CR0}{ } \\ \test{\word{'} CR0 \word{toBODY}}{\word{HERE}} \end{testing} \end{worddef} \begin{worddef}[toIN]{0560}{>IN}[to-in] \item \stack{}{a-addr} \param{a-addr} is the address of a cell containing the offset in characters from the start of the input buffer to the start of the parse area. \begin{testing} % T.6.1.0560 >IN \ttfamily \word{VARIABLE} SCANS \\ \word{:} RESCAN? -1 SCANS \word{+!} SCANS \word{@} \word{IF} 0 \word{toIN} \word{!} \word{THEN} \word{;} \test{ 2 SCANS \word{!} \\\mbox{} 345 RESCAN? \\ }{345 345} \word{:} GS2 5 SCANS \word{!} \word{Sq} 123 RESCAN?" \word{EVALUATE} \word{;} \\ \test{GS2}{123 123 123 123 123} \word{bs} \textdf{These tests must start on a new line} \\ \word{DECIMAL} \\ T\{ 123456 \word{DEPTH} \word{OVER} 9 \word{less} 35 \word{AND} \word{+} 3 \word{+} \word{toIN} \word{!} \\ -> 123456 23456 3456 456 56 6 \}T \\ T\{ 14145 8115 \word{qDUP} \word{0=} 34 \word{AND} \word{toIN} \word{+!} \word{TUCK} \word{MOD} 14 \word{toIN} \word{!} GCD calculation \\ -> 15 \}T \end{testing} \end{worddef} \begin{worddef}[toNUMBER]{0570}{>NUMBER}[to-number] \item \stack{ud_1 c-addr_1 u_1}{ud_2 c-addr_2 u_2} \param{ud_2} is the unsigned result of converting the characters within the string specified by \param{c-addr_1 u_1} into digits, using the number in \word{BASE}, and adding each into \param{ud_1} after multiplying \param{ud_1} by the number in \word{BASE}. Conversion continues left-to-right until a character that is not convertible, including any ``+'' or ``-'', is encountered or the string is entirely converted. \param{c-addr_2} is the location of the first unconverted character or the first character past the end of the string if the string was entirely converted. \param{u_2} is the number of unconverted characters in the string. An ambiguous condition exists if \param{ud_2} overflows during the conversion. \see \xref[3.2.1.2 Digit conversion]{usage:digits}. \begin{testing} % T.6.1.0570 >NUMBER \ttfamily \word{CREATE} GN-BUF 0 \word{C,} \\ \word{:} GN-STRING GN-BUF 1 \word{;} \\ \word{:} GN-CONSUMED GN-BUF \word{CHAR+} 0 \word{;} \\ \word{:} GN' \word{[CHAR]} ' \word{WORD} \word{CHAR+} \word{C@} GN-BUF \word{C!} GN-STRING \word{;} \test{0 0 GN' 0' \word{toNUMBER}}{ 0 0 GN-CONSUMED} \\ \test{0 0 GN' 1' \word{toNUMBER}}{ 1 0 GN-CONSUMED} \\ \test{1 0 GN' 1' \word{toNUMBER}}{BASE @ 1+ 0 GN-CONSUMED} \\ \word{bs} FOLLOWING SHOULD FAIL TO CONVERT \\ \test{0 0 GN' -' \word{toNUMBER}}{ 0 0 GN-STRING } \\ \test{0 0 GN' +' \word{toNUMBER}}{ 0 0 GN-STRING } \\ \test{0 0 GN' .' \word{toNUMBER}}{ 0 0 GN-STRING } \word{:} >NUMBER-BASED \\ \tab \word{BASE} \word{@} \word{toR} \word{BASE} \word{!} \word{toNUMBER} \word{Rfrom} \word{BASE} \word{!} \word{;} \test{0 0 GN' 2' 10 >NUMBER-BASED}{ 2 0 GN-CONSUMED} \\ \test{0 0 GN' 2' 2 >NUMBER-BASED}{ 0 0 GN-STRING } \\ \test{0 0 GN' F' 10 >NUMBER-BASED}{ F 0 GN-CONSUMED} \\ \test{0 0 GN' G' 10 >NUMBER-BASED}{ 0 0 GN-STRING } \\ \test{0 0 GN' G' MAX-BASE >NUMBER-BASED}{10 0 GN-CONSUMED} \\ \test{0 0 GN' Z' MAX-BASE >NUMBER-BASED}{23 0 GN-CONSUMED} \word{:} GN1 \word{p} UD BASE -{}- UD' LEN ) \\ \tab \word{bs} UD SHOULD EQUAL UD' AND LEN SHOULD BE ZERO. \\ \tab \word{BASE} \word{@} \word{toR} \word{BASE} \word{!} \\ \tab \word{num-start} \word{numS} \word{num-end} \\ \tab 0 0 \word{2SWAP} \word{toNUMBER} \word{SWAP} \word{DROP} \tab \word{bs} RETURN LENGTH ONLY \\ \tab \word{Rfrom} \word{BASE} \word{!} \word{;} \test{ 0 0 2 GN1}{ 0 0 0} \\ \test{MAX-UINT 0 2 GN1}{MAX-UINT 0 0} \\ \test{MAX-UINT DUP 2 GN1}{MAX-UINT DUP 0} \\ \test{ 0 0 MAX-BASE GN1}{ 0 0 0} \\ \test{MAX-UINT 0 MAX-BASE GN1}{MAX-UINT 0 0} \\ \test{MAX-UINT DUP MAX-BASE GN1}{MAX-UINT DUP 0} \end{testing} \end{worddef} \enlargethispage{6ex} \begin{worddef}[toR]{0580}{>R}[to-r] \interpret Interpretation semantics for this word are undefined. \execute \stack{x}{} \stack[R]{}{x} Move \param{x} to the return stack. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:Rfrom}{R>}, \wref{core:R@}{R@}, \wref{core:2toR}{2>R}, \wref{core:2Rfrom}{2R>}, \wref{core:2R@}{2R@}. \begin{testing} % T.6.1.0580 >R % TESTING \word{toR} \word{Rfrom} \word{R@} \test{: GR1 \word{toR} \word{Rfrom} ;}{} \\ \test{: GR2 \word{toR} \word{R@} \word{Rfrom} \word{DROP} ;}{} \\ \test{123 GR1}{123} \\ \test{123 GR2}{123} \\ \test{ 1S GR1}{ 1S} \tab[2] \word{p} \textdf{Return stack holds cells} ) \end{testing} \end{worddef} \begin{worddef}[qDUP]{0630}{?DUP}[question-dupe] \item \stack{x}{0 | x x} Duplicate \param{x} if it is non-zero. \begin{testing} % T.6.1.0630 ?DUP \test{-1 \word{qDUP}}{-1 -1} \\ \test{ 0 \word{qDUP}}{ 0 } \\ \test{ 1 \word{qDUP}}{ 1 1} \end{testing} \end{worddef} \begin{worddef}{0650}{@}[fetch] \item \stack{a-addr}{x} \param{x} is the value stored at \param{a-addr}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0650 @ See \tref{core:,}{,}. \end{testing} \end{worddef} \begin{worddef}{0670}{ABORT} \item \stack{i*x}{} \stack[R]{j*x}{} Empty the data stack and perform the function of \word{QUIT}, which includes emptying the return stack, without displaying a message. \see \wref{exception:ABORT}{ABORT}. \end{worddef} \begin{worddef}[ABORTq]{0680}{ABORT"}[abort-quote] \interpret Interpretation semantics for this word are undefined. \compile \stack{"ccc"}{} Parse \param{ccc} delimited by a \texttt{"} (double-quote). Append the run-time semantics given below to the current definition. \runtime \stack{i*x x_1}{| i*x} \stack[R]{j*x}{| j*x} Remove \param{x_1} from the stack. If any bit of \param{x_1} is not zero, display \param{ccc} and perform an implementation-defined abort sequence that includes the function of \word{ABORT}. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{exception:ABORTq}{9.6.2.0680 ABORT"}, \rref{core:ABORTq}{}. \begin{rationale} % A.6.1.0680 ABORT" Typical use: \word{:} \texttt{X} {\ldots} \emph{test} \word{ABORTq} \emph{ccc}\texttt{"} {\ldots} \word{;} \end{rationale} \end{worddef} \begin{worddef}{0690}{ABS}[abs] \item \stack{n}{u} \param{u} is the absolute value of \param{n}. \begin{testing} % T.6.1.0690 ABS \test{ 0 \word{ABS}}{ 0} \\ \test{ 1 \word{ABS}}{ 1} \\ \test{ -1 \word{ABS}}{ 1} \\ \test{MIN-INT \word{ABS}}{MID-UINT+1} \end{testing} \end{worddef} \begin{worddef}{0695}{ACCEPT} \item \stack{c-addr +n_1}{+n_2} Receive a string of at most \param{+n_1} characters. An ambiguous condition exists if \param{+n_1} is zero or greater than 32,767. Display graphic characters as they are received. A program that depends on the presence or absence of non-graphic characters in the string has an environmental dependency. The editing functions, if any, that the system performs in order to construct the string are implementation-defined. Input terminates when an implementation-defined line terminator is received. When input terminates, nothing is appended to the string, and the display is maintained in an implementation-defined way. \param{+n_2} is the length of the string stored at \param{c-addr}. \see \rref{core:ACCEPT}{}. \begin{rationale} % A.6.1.0695 ACCEPT Specification of a non-zero, positive integer count (\param{+n_1}) for \word{ACCEPT} allows some implementors to continue their practice of using a zero or negative value as a flag to trigger special behavior. Insofar as such behavior is outside the standard, Standard Programs cannot depend upon it, but the committee doesn't wish to preclude it unnecessarily. Because actual values are almost always small integers, no functionality is impaired by this restriction. It is recommended that all non-graphic characters be reserved for editing or control functions and not be stored in the input string. Because external system hardware and software may perform the \word{ACCEPT} function, when a line terminator is received the action of the cursor, and therefore the display, is implementation-defined. It is recommended that the cursor remain immediately following the entered text after a line terminator is received. \end{rationale} \begin{testing} % T.6.1.0695 ACCEPT \ttfamily \word{CREATE} ABUF 80 \word{CHARS} \word{ALLOT} \word{:} ACCEPT-TEST \\ \tab[2] \word{CR} \word{.q} PLEASE TYPE UP TO 80 CHARACTERS:" \word{CR} \\ \tab[2] ABUF 80 \word{ACCEPT} \\ \tab[2] \word{CR} \word{.q} RECEIVED: " \word{[CHAR]} " \word{EMIT} \\ \tab[2] ABUF \word{SWAP} \word{TYPE} \word{[CHAR]} " \word{EMIT} \word{CR} \\ \word{;} \test{ACCEPT-TEST}{} \end{testing} \end{worddef} \begin{worddef}{0705}{ALIGN} \item \stack{}{} If the data-space pointer is not aligned, reserve enough space to align it. \see \xref[3.3.3 Data space]{usage:dataspace}, \xref[3.3.3.1 Address alignment]{usage:aaddr}, \rref{core:ALIGN}{}. \begin{rationale} % A.6.1.0705 ALIGN In this standard we have attempted to provide transportability across various CPU architectures. One of the frequent causes of transportability problems is the requirement of cell-aligned addresses on some CPUs. On these systems, \word{ALIGN} and \word{ALIGNED} may be required to build and traverse data structures built with \word{C,}. Implementors may define these words as no-ops on systems for which they aren't functional. \end{rationale} \begin{testing} % T.6.1.0705 ALIGN \ttfamily \word{ALIGN} 1 \word{ALLOT} \word{HERE} \word{ALIGN} \word{HERE} 3 \word{CELLS} \word{ALLOT} \\ \word{CONSTANT} A-ADDR \word{CONSTANT} UA-ADDR \\ \test{UA-ADDR \word{ALIGNED}}{A-ADDR} \\ \test{ 1 A-ADDR \word{C!} A-ADDR \word{C@}}{ 1} \\ \test{ 1234 A-ADDR \word{!} A-ADDR \word{@} }{ 1234} \\ \test{123 456 A-ADDR \word{2!} A-ADDR \word{2@}}{123 456} \\ \test{ 2 A-ADDR \word{CHAR+} \word{C!} A-ADDR \word{CHAR+} \word{C@}}{ 2} \\ \test{ 3 A-ADDR \word{CELL+} \word{C!} A-ADDR \word{CELL+} \word{C@}}{ 3} \\ \test{ 1234 A-ADDR \word{CELL+} \word{!} A-ADDR \word{CELL+} \word{@} }{ 1234} \\ \test{123 456 A-ADDR \word{CELL+} \word{2!} A-ADDR \word{CELL+} \word{2@}}{123 456} \end{testing} \end{worddef} \begin{worddef}{0706}{ALIGNED} \item \stack{addr}{a-addr} \param{a-addr} is the first aligned address greater than or equal to \param{addr}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}, \wref{core:ALIGN}{}. \end{worddef} \begin{worddef}{0710}{ALLOT} \item \stack{n}{} If \param{n} is greater than zero, reserve \param{n} address units of data space. If \param{n} is less than zero, release \param{|n|} address units of data space. If \param{n} is zero, leave the data-space pointer unchanged. If the data-space pointer is aligned and \param{n} is a multiple of the size of a cell when \word{ALLOT} begins execution, it will remain aligned when \word{ALLOT} finishes execution. If the data-space pointer is character aligned and \param{n} is a multiple of the size of a character when \word{ALLOT} begins execution, it will remain character aligned when \word{ALLOT} finishes execution. \see \xref[3.3.3 Data space]{usage:dataspace}. \begin{testing} % T.6.1.0710 ALLOT \ttfamily \word{HERE} 1 \word{ALLOT} \\ \word{HERE} \\ \word{CONSTANT} 2NDA \\ \word{CONSTANT} 1STA \\ \test{1STA 2NDA \word{Uless}}{} \tab \word{bs} HERE MUST GROW WITH ALLOT \\ \test{ 1STA \word{1+}}{ 2NDA} \tab \word{bs} {\ldots} BY ONE ADDRESS UNIT \\ ( MISSING TEST: NEGATIVE ALLOT ) \end{testing} \end{worddef} \begin{worddef}{0720}{AND} \item \stack{x_1 x_2}{x_3} \param{x_3} is the bit-by-bit logical ``and'' of \param{x_1} with \param{x_2}. \begin{testing} % T.6.1.0720 AND \test{0 0 \word{AND}}{0} \\ \test{0 1 \word{AND}}{0} \\ \test{1 0 \word{AND}}{0} \\ \test{1 1 \word{AND}}{1} \test{0 \word{INVERT} 1 \word{AND}}{1} \\ \test{1 \word{INVERT} 1 \word{AND}}{0} \test{0S 0S \word{AND}}{0S} \\ \test{0S 1S \word{AND}}{0S} \\ \test{1S 0S \word{AND}}{0S} \\ \test{1S 1S \word{AND}}{1S} \end{testing} \end{worddef} \begin{worddef}{0750}{BASE} \item \stack{}{a-addr} \param{a-addr} is the address of a cell containing the current number-conversion radix \{\{2...36\}\}. \begin{testing} % T.6.1.0750 BASE \ttfamily \word{:} GN2 \word{bs} ( -{}- 16 10 ) \\ \tab \word{BASE} \word{@} \word{toR} \word{HEX} \word{BASE} \word{@} \word{DECIMAL} \word{BASE} \word{@} \word{Rfrom} \word{BASE} \word{!} \word{;} \\ \test{GN2}{10 A} \end{testing} \end{worddef} \begin{worddef}{0760}{BEGIN} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{dest} Put the next location for a transfer of control, \param{dest}, onto the control flow stack. Append the run-time semantics given below to the current definition. \runtime \stack{}{} Continue execution. \see \xref[3.2.3.2 Control-flow stack]{usage:controlstack}, \wref{core:REPEAT}{REPEAT}, \wref{core:UNTIL}{UNTIL}, \wref{core:WHILE}{WHILE}, \\ \rref{core:BEGIN}{}. \begin{rationale} % A.6.1.0760 BEGIN Typical use: \tab \word{:} \texttt{X} {\ldots} \word{BEGIN} {\ldots} \emph{test} \word{UNTIL} \word{;} or \tab \word{:} \texttt{X} {\ldots} \word{BEGIN} {\ldots} \emph{test} \word{WHILE} {\ldots} \word{REPEAT} \word{;} \end{rationale} \begin{testing} % T.6.2.0760 BEGIN See \tref{core:WHILE}{WHILE}, \tref{core:UNTIL}{UNTIL}. \end{testing} \end{worddef} \enlargethispage{6ex} \begin{worddef}{0770}{BL}[b-l] \item \stack{}{char} \param{char} is the character value for a space. \see \rref{core:BL}{}. \begin{rationale} % A.6.1.0770 BL Because space is used throughout Forth as the standard delimiter, this word is the only way a program has to find and use the system value of ``space''. The value of a space character can not be obtained with \word{CHAR}, for instance. \end{rationale} \begin{testing} % T.6.1.0770 BL \test{\word{BL}}{20} \end{testing} \end{worddef} \begin{worddef}{0850}{C!}[c-store] \item \stack{char c-addr}{} Store \param{char} at \param{c-addr}. When character size is smaller than cell size, only the number of low-order bits corresponding to character size are transferred. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0850 C! See \tref{core:C,}{C,}. \end{testing} \end{worddef} \begin{worddef}{0860}{C,}[c-comma] \item \stack{char}{} Reserve space for one character in the data space and store \param{char} in the space. If the data-space pointer is character aligned when \word{C,} begins execution, it will remain character aligned when \word{C,} finishes execution. An ambiguous condition exists if the data-space pointer is not character-aligned prior to execution of \word{C,}. \see \xref[3.3.3 Data space]{usage:dataspace}, \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0860 C, \ttfamily \word{HERE} 1 \word{C,} \\ \word{HERE} 2 \word{C,} \\ \word{CONSTANT} 2NDC \\ \word{CONSTANT} 1STC \test{ 1STC 2NDC \word{Uless}}{} \word{bs} HERE MUST GROW WITH ALLOT \\ \test{ 1STC \word{CHAR+}}{ 2NDC } \word{bs} {\ldots} BY ONE CHAR \\ \test{ 1STC 1 \word{CHARS} \word{+}}{ 2NDC } \\ \test{1STC \word{C@} 2NDC \word{C@}}{ 1 2 } \\ \test{ 3 1STC \word{C!}}{ } \\ \test{1STC \word{C@} 2NDC \word{C@}}{ 3 2 } \\ \test{ 4 2NDC \word{C!}}{ } \\ \test{1STC \word{C@} 2NDC \word{C@}}{ 3 4 } \end{testing} \end{worddef} \begin{worddef}{0870}{C@}[c-fetch] \item \stack{c-addr}{char} Fetch the character stored at \param{c-addr}. When the cell size is greater than character size, the unused high-order bits are all zeroes. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.2.0870 C@ See \tref{core:C,}{C,}. \end{testing} \end{worddef} \begin{worddef}{0880}{CELL+}[cell-plus] \item \stack{a-addr_1}{a-addr_2} Add the size in address units of a cell to \param{a-addr_1}, giving \param{a-addr_2}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}, \rref{core:CELL+}{}. \begin{rationale} % A.6.1.0880 CELL+ As with \word{ALIGN} and \word{ALIGNED}, the words \word{CELLS} and \word{CELL+} were added to aid in transportability across systems with different cell sizes. They are intended to be used in manipulating indexes and addresses in integral numbers of cell-widths. Example: \begin{quote}\ttfamily \word[double]{2VARIABLE} DATA 0 100 DATA \word{2!} DATA \word{@} \word{d} 100 DATA \word{CELL+} \word{@} \word{d} 0 \end{quote} \end{rationale} \begin{testing} % T.6.1.0880 CELL+ See \tref{core:,}{,}. \end{testing} \end{worddef} \begin{worddef}{0890}{CELLS} \item \stack{n_1}{n_2} \param{n_2} is the size in address units of \param{n_1} cells. \see \rref{core:CELL+}{}, \rref{core:CELLS}{}. \begin{rationale} % A.6.1.0890 CELLS Example: \begin{quote} \word{CREATE} \texttt{NUMBERS} ~ \texttt{100} \word{CELLS} \word{ALLOT} \end{quote} Allots space in the array \texttt{NUMBERS} for 100 cells of data. \end{rationale} \begin{testing} % T.6.1.0890 CELLS \ttfamily \word{:} BITS \word{p} X -{}- U ) \\ \tab 0 \word{SWAP} \word{BEGIN} \word{DUP} \word{WHILE} \\ \tab[2] \word{DUP} MSB \word{AND} \word{IF} \word{toR} \word{1+} \word{Rfrom} \word{THEN} \word{2*} \\ \tab \word{REPEAT} \word{DROP} \word{;} \word{p} CELLS >= 1 AU, INTEGRAL MULTIPLE OF CHAR SIZE, >= 16 BITS ) \\ \test{1 \word{CELLS} 1 \word{less} }{} \\ \test{1 \word{CELLS} 1 \word{CHARS} \word{MOD}}{ 0 } \\ \test{1S BITS 10 \word{less} }{} \end{testing} \end{worddef} \begin{worddef}{0895}{CHAR}[char] \item \stack{"name"}{char} Skip leading space delimiters. Parse \param{name} delimited by a space. Put the value of its first character onto the stack. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:[CHAR]}{[CHAR]}, \rref{core:CHAR}{}. \begin{rationale} % A.6.1.0895 CHAR Typical use: {\ldots} \word{CHAR} \texttt{A} \word{CONSTANT} \texttt{"A"} {\ldots} \end{rationale} \begin{testing} % T.6.1.0895 CHAR \test{\word{CHAR} X }{58} \\ \test{\word{CHAR} HELLO}{48} \end{testing} \end{worddef} \begin{worddef}{0897}{CHAR+}[char-plus] \item \stack{c-addr_1}{c-addr_2} Add the size in address units of a character to \param{c-addr_1}, giving \param{c-addr_2}. \see \xref[3.3.3.1 Address alignment]{usage:aaddr}. \begin{testing} % T.6.1.0897 CHAR+ See \tref{core:C,}{C,}. \end{testing} \end{worddef} \begin{worddef}{0898}{CHARS}[chars] \item \stack{n_1}{n_2} \param{n_2} is the size in address units of \param{n_1} characters. \begin{testing} % T.6.1.0898 CHARS \ttfamily \word{p} CHARACTERS >= 1 AU, <= SIZE OF CELL, >= 8 BITS ) \\ \test{1 \word{CHARS} 1 \word{less} }{} \\ \test{1 \word{CHARS} 1 \word{CELLS} \word{more}}{} \\ \word{p} TBD: HOW TO FIND NUMBER OF BITS? ) \end{testing} \end{worddef} \begin{worddef}{0950}{CONSTANT} \item \stack{x "name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below. \param{name} is referred to as a ``constant''. \execute[name] \stack{}{x} Place \param{x} on the stack. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:CONSTANT}{}. \begin{rationale} % A.6.1.0950 CONSTANT Typical use: {\ldots} \word{DECIMAL} \texttt{10} \word{CONSTANT} \texttt{TEN} {\ldots} \end{rationale} \begin{testing} % T.6.1.0950 CONSTANT \test{123 \word{CONSTANT} X123}{} \\ \test{X123}{123} \test{\word{:} EQU \word{CONSTANT} \word{;}}{} \\ \test{X123 EQU Y123}{} \\ \test{Y123}{123} \end{testing} \end{worddef} \begin{worddef}{0980}{COUNT} \item \stack{c-addr_1}{c-addr_2 u} Return the character string specification for the counted string stored at \param{c-addr_1}. \param{c-addr_2} is the address of the first character after \param{c-addr_1}. \param{u} is the contents of the character at \param{c-addr_1}, which is the length in characters of the string at \param{c-addr_2}. \begin{testing} % T.6.1.0980 COUNT \test{GT1STRING \word{COUNT}}{GT1STRING \word{CHAR+} 3} \end{testing} \end{worddef} \begin{worddef}{0990}{CR}[c-r] \item \stack{}{} Cause subsequent output to appear at the beginning of the next line. \begin{testing} % T.6.1.0990 CR See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1000}{CREATE} \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below. If the data-space pointer is not aligned, reserve enough data space to align it. The new data-space pointer defines \param{name}'s data field. \word{CREATE} does not allocate data space in \param{name}'s data field. \execute[name] \stack{}{a-addr} \param{a-addr} is the address of \param{name}'s data field. The execution semantics of \param{name} may be extended by using \word{DOES}. \see \xref[3.3.3 Data space]{usage:dataspace}, \wref{core:DOES}{DOES>}, \rref{core:CREATE}{}. \begin{rationale} % A.6.1.1000 CREATE The data-field address of a word defined by \word{CREATE} is given by the data-space pointer immediately following the execution of \word{CREATE}. Reservation of data field space is typically done with \word{ALLOT}. Typical use: {\ldots} \word{CREATE} \texttt{SOMETHING} {\ldots} \end{rationale} \begin{testing} % T.6.1.1000 CREATE See \tref{core:toBODY}{>BODY} and \tref{core:DOES}{DOES}. \end{testing} \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1170}{DECIMAL} \item \stack{}{} Set the numeric conversion radix to ten (decimal). \begin{testing} % T.6.1.1170 DECIMAL See \tref{core:BASE}{BASE}. \end{testing} \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1200}{DEPTH} \item \stack{}{+n} \param{+n} is the number of single-cell values contained in the data stack before \param{+n} was placed on the stack. \begin{testing} % T.6.1.1200 DEPTH \test{0 1 \word{DEPTH}}{0 1 2} \\ \test{ 0 \word{DEPTH}}{0 1 } \\ \test{ \word{DEPTH}}{0 } \end{testing} \end{worddef} \vspace*{-0.5ex} \enlargethispage{10ex} \begin{worddef}{1240}{DO} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{do-sys} Place \param{do-sys} onto the control-flow stack. Append the run-time semantics given below to the current definition. The semantics are incomplete until resolved by a consumer of \param{do-sys} such as \word{LOOP}. %\pagebreak \runtime \stack{n_1|u_1 n_2|u_2}{} \stack[R]{}{loop-sys} Set up loop control parameters with index \param{n_2|u_2} and limit \param{n_1|u_1}. An ambiguous condition exists if \param{n_1|u_1} and \param{n_2|u_2} are not both the same type. Anything already on the return stack becomes unavailable until the loop-control parameters are discarded. \see \xref[3.2.3.2 Control-flow stack]{usage:controlstack}, \wref{core:+LOOP}{+LOOP}, \wref{core:LOOP}{LOOP}, \rref{core:DO}{}. \begin{rationale} % A.6.1.1240 DO Typical use: \tab \word{:} \texttt{X} {\ldots} \emph{limit} \emph{first} \word{DO} {\ldots} \word{LOOP} \word{;} or \tab \word{:} \texttt{X} {\ldots} \emph{limit} \emph{first} \word{DO} {\ldots} \emph{step} \word{+LOOP} \word{;} \end{rationale} \begin{testing} % T.6.1.1240 DO See \tref{core:LOOP}{LOOP}, \tref{core:+LOOP}{+LOOP}, \tref{core:J}{J}, \tref{core:LEAVE}{LEAVE}, \tref{core:UNLOOP}{UNLOOP}. \end{testing} \end{worddef} \begin{worddef}[DOES]{1250}{DOES>}[does] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{colon-sys_1}{colon-sys_2} Append the run-time semantics below to the current definition. Whether or not the current definition is rendered findable in the dictionary by the compilation of \word{DOES} is implementation defined. Consume \param{colon-sys_1} and produce \param{colon-sys_2}. Append the initiation semantics given below to the current definition. \runtime \stack{}{} \stack[R]{nest-sys_1}{} Replace the execution semantics of the most recent definition, referred to as \param{name}, with the \param{name} execution semantics given below. Return control to the calling definition specified by \param{nest-sys_1}. An ambiguous condition exists if \param{name} was not defined with \word{CREATE} or a user-defined word that calls \word{CREATE}. \init \stack{i*x}{i*x a-addr} \stack[R]{}{nest-sys_2} Save implementation-dependent information \param{nest-sys_2} about the calling definition. Place \param{name}'s data field address on the stack. The stack effects \param{i*x} represent arguments to \param{name}. \execute[name] \stack{i*x}{j*x} Execute the portion of the definition that begins with the initiation semantics appended by the \word{DOES} which modified \param{name}. The stack effects \param{i*x} and \param{j*x} represent arguments to and results from \param{name}, respectively. \see \wref{core:CREATE}{CREATE}, \rref{core:DOES}{}. \begin{rationale} % A.6.1.1250 DOES> Typical use: \word{:} \texttt{X} {\ldots} \word{DOES} {\ldots} \word{;} Following \word{DOES}, a Standard Program may not make any assumptions regarding the ability to find either the name of the definition containing the \word{DOES} or any previous definition whose name may be concealed by it. \word{DOES} effectively ends one definition and begins another as far as local variables and control-flow structures are concerned. The compilation behavior makes it clear that the user is not entitled to place \word{DOES} inside any control-flow structures. \end{rationale} \begin{testing} % T.6.1.1250 DOES> \test{\word{:} DOES1 \word{DOES} \word{@} 1 \word{+} \word{;}}{} \\ \test{\word{:} DOES2 \word{DOES} \word{@} 2 \word{+} \word{;}}{} \\ \test{\word{CREATE} CR1}{} \\ \test{CR1 }{\word{HERE}} \\ \test{1 \word{,} }{ } \\ \test{CR1 \word{@}}{1} \\ \test{DOES1}{ } \\ \test{CR1 }{2} \\ \test{DOES2}{ } \\ \test{CR1 }{3} \test{\word{:} WEIRD: \word{CREATE} \word{DOES} 1 \word{+} \word{DOES} 2 \word{+} \word{;}}{} \\ \test{WEIRD: W1}{} \\ \test{\word{'} W1 \word{toBODY}}{\word{HERE}} \\ \test{W1}{\word{HERE} 1 \word{+}} \\ \test{W1}{\word{HERE} 2 \word{+}} \end{testing} \end{worddef} \begin{worddef}{1260}{DROP} \item \stack{x}{} Remove \param{x} from the stack. \begin{testing} % T.6.1.1260 DROP \test{1 2 \word{DROP}}{1} \\ \test{0 \word{DROP}}{ } \end{testing} \end{worddef} \begin{worddef}{1290}{DUP}[dupe] \item \stack{x}{x x} Duplicate \param{x}. \begin{testing} % T.6.1.1290 DUP \test{1 \word{DUP}}{1 1} \end{testing} \end{worddef} \pagebreak \begin{worddef}{1310}{ELSE} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{orig_1}{orig_2} Put the location of a new unresolved forward reference \param{orig_2} onto the control flow stack. Append the run-time semantics given below to the current definition. The semantics will be incomplete until \param{orig_2} is resolved (e.g., by \word{THEN}). Resolve the forward reference \param{orig_1} using the location following the appended run-time semantics. \runtime \stack{}{} Continue execution at the location given by the resolution of \param{orig_2}. \see \wref{core:IF}{IF}, \wref{core:THEN}{THEN}, \rref{core:ELSE}{}. \begin{rationale} % A.6.1.1310 ELSE Typical use: \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{ELSE} {\ldots} \word{THEN} \word{;} \end{rationale} \begin{testing} % T.6.1.1310 ELSE See \tref{core:IF}{IF}. \end{testing} \end{worddef} \begin{worddef}{1320}{EMIT} \item \stack{x}{} If \param{x} is a graphic character in the implementation-defined character set, display \param{x}. The effect of \word{EMIT} for all other values of \param{x} is implementation-defined. When passed a character whose character-defining bits have a value between hex 20 and 7E inclusive, the corresponding standard character, specified by \xref[3.1.2.1 Graphic characters]{usage:ASCII}, is displayed. Because different output devices can respond differently to control characters, programs that use control characters to perform specific functions have an environmental dependency. Each EMIT deals with only one character. \see \wref{core:TYPE}{TYPE}. \begin{testing} % T.6.1.1320 EMIT \ttfamily % TESTING OUTPUT: \word{d} \word{.q} \word{CR} \word{EMIT} \word{SPACE} \word{SPACES} \word{TYPE} \word{Ud} \word{:} OUTPUT-TEST \\[1ex] \tab \word{.q} YOU SHOULD SEE THE STANDARD GRAPHIC CHARACTERS:" \word{CR} \\ \tab 41 \word{BL} \word{DO} \word{I} \word{EMIT} \word{LOOP} \word{CR} \\ \tab 61 41 \word{DO} \word{I} \word{EMIT} \word{LOOP} \word{CR} \\ \tab 7F 61 \word{DO} \word{I} \word{EMIT} \word{LOOP} \word{CR} \\[1ex] \tab \word{.q} YOU SHOULD SEE 0-9 SEPARATED BY A SPACE:" \word{CR} \\ \tab 9 \word{1+} 0 \word{DO} \word{I} \word{d} \word{LOOP} \word{CR} \\[1ex] \tab \word{.q} YOU SHOULD SEE 0-9 (WITH NO SPACES):" \word{CR} \\ \tab \word{[CHAR]} 9 \word{1+} \word{[CHAR]} 0 \word{DO} \word{I} 0 \word{SPACES} \word{EMIT} \word{LOOP} \word{CR} \\[1ex] \tab \word{.q} YOU SHOULD SEE A-G SEPARATED BY A SPACE:" \word{CR} \\ \tab \word{[CHAR]} G \word{1+} \word{[CHAR]} A \word{DO} \word{I} \word{EMIT} \word{SPACE} \word{LOOP} \word{CR} \\[1ex] \tab \word{.q} YOU SHOULD SEE 0-5 SEPARATED BY TWO SPACES:" \word{CR} \\ \tab 5 \word{1+} 0 \word{DO} \word{I} \word{[CHAR]} 0 \word{+} \word{EMIT} 2 \word{SPACES} \word{LOOP} \word{CR} \\[1ex] \tab \word{.q} YOU SHOULD SEE TWO SEPARATE LINES:" \word{CR} \\ \tab \word{Sq} LINE 1" \word{TYPE} \word{CR} \word{Sq} LINE 2" \word{TYPE} \word{CR} \\[1ex] \tab \word{.q} {\small YOU SHOULD SEE THE NUMBER RANGES OF SIGNED AND UNSIGNED NUMBERS:}" \word{CR} \\ \tab \word{.q} ~~SIGNED: " MIN-INT \word{d} MAX-INT \word{d} \word{CR} \\ \tab \word{.q} UNSIGNED: " 0 \word{Ud} MAX-UINT \word{Ud} \word{CR} \\ \word{;} \test{OUTPUT-TEST}{} \end{testing} \end{worddef} \begin{worddef}[ENVIRONMENTq]{1345}{ENVIRONMENT?}[environment-query] \item \stack{c-addr u}{false | i*x true} \param{c-addr} is the address of a character string and \param{u} is the string's character count. \param{u} may have a value in the range from zero to an implementation-defined maximum which shall not be less than 31. The character string should contain a keyword from \xref[3.2.6 Environmental queries]{usage:env} or the optional word sets to be checked for correspondence with an attribute of the present environment. If the system treats the attribute as unknown, the returned flag is \param{false}; otherwise, the flag is \param{true} and the \param{i*x} returned is of the type specified in the table for the attribute queried. \see \rref{core:ENVIRONMENTq}{}. \begin{rationale} % A.6.1.1345 ENVIRONMENT? In a Standard System that contains only the Core word set, effective use of \word{ENVIRONMENTq} requires either its use within a definition, or the use of user-supplied auxiliary definitions. The Core word set lacks both a direct method for collecting a string in interpretation state (\wref{file:Sq}{S"} is in an optional word set) and also a means to test the returned flag in interpretation state (e.g. the optional \wref{tools:[IF]}{[IF]}). \end{rationale} \begin{testing} % T.6.1.1345 ENVIRONMENT? \word{bs} should be the same for any query starting with X: \\ \test{\word{Sq} X:deferred" \word{ENVIRONMENTq} \word{DUP} \word{0=} \word{XOR} \word{INVERT}}{ } \\ \test{\word{Sq} X:notfound" \word{ENVIRONMENTq} \word{DUP} \word{0=} \word{XOR} \word{INVERT}}{} \end{testing} \end{worddef} \pagebreak \begin{worddef}{1360}{EVALUATE} \item \stack{i*x c-addr u}{j*x} Save the current input source specification. Store minus-one (-1) in \word{SOURCE-ID} if it is present. Make the string described by \param{c-addr} and \param{u} both the input source and input buffer, set \word{toIN} to zero, and interpret. When the parse area is empty, restore the prior input source specification. Other stack effects are due to the words \word{EVALUATE}d. \begin{testing} % T.6.1.1360 EVALUATE \ttfamily \word{:} GE1 \word{Sq} 123" \word{;} \word{IMMEDIATE} \\ \word{:} GE2 \word{Sq} 123 1+" \word{;} \word{IMMEDIATE} \\ \word{:} GE3 \word{Sq} \word{:} GE4 345 \word{;}" \word{;} \\ \word{:} GE5 \word{EVALUATE} \word{;} \word{IMMEDIATE} \test{GE1 \word{EVALUATE}}{123} \word{p} TEST EVALUATE IN INTERP. STATE ) \\ \test{GE2 \word{EVALUATE}}{124} \\ \test{GE3 \word{EVALUATE}}{ } \\ \test{GE4 }{345} \test{\word{:} GE6 GE1 GE5 \word{;}}{} \word{p} TEST EVALUATE IN COMPILE STATE ) \\ \test{GE6}{123} \\ \test{\word{:} GE7 GE2 GE5 \word{;}}{} \\ \test{GE7}{124} \textdf{See \ref{test:throw} for additional test.} \end{testing} \end{worddef} \begin{worddef}{1370}{EXECUTE} \item \stack{i*x xt}{j*x} Remove \param{xt} from the stack and perform the semantics identified by it. Other stack effects are due to the word \word{EXECUTE}d. \see \wref{core:'}{'}, \wref{core:[']}{[']}. \begin{testing} % T.6.1.1370 EXECUTE See \tref{core:'}{'} and \tref{core:[']}{[']}. \end{testing} \end{worddef} \begin{worddef}{1380}{EXIT} \interpret Interpretation semantics for this word are undefined. \execute \stack{}{} \stack[R]{nest-sys}{} Return control to the calling definition specified by \param{nest-sys}. Before executing \word{EXIT} within a do-loop, a program shall discard the loop-control parameters by executing \word{UNLOOP}. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:UNLOOP}{UNLOOP}, \rref{core:EXIT}{}. \begin{rationale} % A.6.1.1380 EXIT Typical use: \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{EXIT} \word{THEN} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.1380 EXIT See \tref{core:UNLOOP}{UNLOOP}. \end{testing} \end{worddef} \begin{worddef}{1540}{FILL} \item \stack{c-addr u char}{} If \param{u} is greater than zero, store \param{char} in each of \param{u} consecutive characters of memory beginning at \param{c-addr}. \begin{testing} % T.6.1.1540 FILL \test{FBUF 0 20 \word{FILL}}{} \\ \test{SEEBUF}{00 00 00} \test{FBUF 1 20 \word{FILL}}{} \\ \test{SEEBUF}{20 00 00} \test{FBUF 3 20 \word{FILL}}{} \\ \test{SEEBUF}{20 20 20} \end{testing} \end{worddef} \enlargethispage{10ex} \begin{worddef}{1550}{FIND} \item \stack{c-addr}{c-addr 0 | xt 1 | xt -1} Find the definition named in the counted string at \param{c-addr}. If the definition is not found, return \param{c-addr} and zero. If the definition is found, return its execution token \param{xt}. If the definition is immediate, also return one (\param{1}), otherwise also return minus-one (\param{-1}). For a given string, the values returned by \word{FIND} while compiling may differ from those returned while not compiling. \see \xref[3.4.2 Finding definition names]{usage:find}, \rref{core:'}{'}, \rref{core:FIND}{}, \\ \rref{core:POSTPONE}{POSTPONE}, \rref{core:[']}{[']}. \begin{rationale} % A.6.1.1550 FIND One of the more difficult issues which the committee took on was the problem of divorcing the specification of implementation mechanisms from the specification of the Forth language. Three basic implementation approaches can be quickly enumerated: \begin{enumerate} \item[1)] Threaded code mechanisms. These are the traditional approaches to implementing Forth, but other techniques may be used. \item[2)] Subroutine threading with ``macro-expansion'' (code copying). Short routines, like the code for \word{DUP}, are copied into a definition rather than compiling a \texttt{JSR} reference. \item[3)] Native coding with optimization. This may include stack optimization (replacing such phrases as \word{SWAP} \word{ROT} \word{+} with one or two machine instructions, for example), parallelization (the trend in the newer RISC chips is to have several functional subunits which can execute in parallel), and so on. \end{enumerate} The initial requirement (inherited from Forth 83) that compilation addresses be compiled into the dictionary disallowed type 2 and type 3 implementations. Type 3 mechanisms and optimizations of type 2 implementations were hampered by the explicit specification of immediacy or non-immediacy of all standard words. \word{POSTPONE} allowed de-spec\-i\-fi\-ca\-tion of immediacy or non-immediacy for all but a few Forth words whose behavior must be \word{STATE}-independent. One type 3 implementation, Charles Moore's cmForth, has both compiling and interpreting versions of many Forth words. At the present, this appears to be a common approach for type 3 implementations. The committee felt that this implementation approach must be allowed. Consequently, it is possible that words without interpretation semantics can be found only during compilation, and other words may exist in two versions: a compiling version and an interpreting version. Hence the values returned by \word{FIND} may depend on \word{STATE}, and \word{'} and \word{[']} may be unable to find words without interpretation semantics. \end{rationale} \begin{testing} % T.6.1.1550 FIND \ttfamily \word{HERE} 3 \word{C,} \word{CHAR} G \word{C,} \word{CHAR} T \word{C,} \word{CHAR} 1 \word{C,} \word{CONSTANT} GT1STRING \\ \word{HERE} 3 \word{C,} \word{CHAR} G \word{C,} \word{CHAR} T \word{C,} \word{CHAR} 2 \word{C,} \word{CONSTANT} GT2STRING \\ \test{GT1STRING \word{FIND}}{\word{'} GT1 -1} \\ \test{GT2STRING \word{FIND}}{\word{'} GT2 1 } \\ \word{p} HOW TO SEARCH FOR NON-EXISTENT WORD? ) \end{testing} \end{worddef} \begin{worddef}{1561}{FM/MOD}[f-m-slash-mod] \item \stack{d_1 n_1}{n_2 n_3} Divide \param{d_1} by \param{n_1}, giving the floored quotient \param{n_3} and the remainder \param{n_2}. Input and output stack arguments are signed. An ambiguous condition exists if \param{n_1} is zero or if the quotient lies outside the range of a single-cell signed integer. \see \xref[3.2.2.1 Integer division]{usage:div}, \wref{core:SM/REM}{6.1.2214 SM/REM}, \wref{core:UM/MOD}{6.1.2370 UM/MOD}, \rref{core:FM/MOD}{}. \begin{rationale} % A.6.1.1561 FM/MOD By introducing the requirement for ``floored'' division, Forth 83 produced much controversy and concern on the part of those who preferred the more common practice followed in other languages of implementing division according to the behavior of the host CPU, which is most often symmetric (rounded toward zero). In attempting to find a compromise position, this standard provides primitives for both common varieties, floored and symmetric (see \word{SM/REM}). \word{FM/MOD} is the floored version. The committee considered providing two complete sets of explicitly named division operators, and declined to do so on the grounds that this would unduly enlarge and complicate the standard. Instead, implementors may define the normal division words in terms of either \word{FM/MOD} or \word{SM/REM} providing they document their choice. People wishing to have explicitly named sets of operators are encouraged to do so. \word{FM/MOD} may be used, for example, to define: \begin{quote}\ttfamily \word{:} /\_MOD \word{p} n1 n2 -{}- n3 n4) \word{toR} \word{StoD} \word{Rfrom} \word{FM/MOD} \word{;} \word{:} /\_ \word{p} n1 n2 -{}- n3) /\_MOD \word{SWAP} \word{DROP} \word{;} \word{:} \_MOD \word{p} n1 n2 -{}- n3) /\_MOD \word{DROP} \word{;} \word{:} */\_MOD \word{p} n1 n2 n3 -{}- n4 n5) \word{toR} \word{M*} \word{Rfrom} \word{FM/MOD} \word{;} \word{:} */\_ \word{p} n1 n2 n3 -{}- n4 ) */\_MOD \word{SWAP} \word{DROP} \word{;} \end{quote} \end{rationale} \begin{testing} % T.6.1.1561 FM/MOD \test{ 0 \word{StoD} 1 \word{FM/MOD}}{ 0 0} \\ \test{ 1 \word{StoD} 1 \word{FM/MOD}}{ 0 1} \\ \test{ 2 \word{StoD} 1 \word{FM/MOD}}{ 0 2} \\ \test{ -1 \word{StoD} 1 \word{FM/MOD}}{ 0 -1} \\ \test{ -2 \word{StoD} 1 \word{FM/MOD}}{ 0 -2} \\ \test{ 0 \word{StoD} -1 \word{FM/MOD}}{ 0 0} \\ \test{ 1 \word{StoD} -1 \word{FM/MOD}}{ 0 -1} \\ \test{ 2 \word{StoD} -1 \word{FM/MOD}}{ 0 -2} \\ \test{ -1 \word{StoD} -1 \word{FM/MOD}}{ 0 1} \\ \test{ -2 \word{StoD} -1 \word{FM/MOD}}{ 0 2} \\ \test{ 2 \word{StoD} 2 \word{FM/MOD}}{ 0 1} \\ \test{ -1 \word{StoD} -1 \word{FM/MOD}}{ 0 1} \\ \test{ -2 \word{StoD} -2 \word{FM/MOD}}{ 0 1} \\ \test{ 7 \word{StoD} 3 \word{FM/MOD}}{ 1 2} \\ \test{ 7 \word{StoD} -3 \word{FM/MOD}}{-2 -3} \\ \test{ -7 \word{StoD} 3 \word{FM/MOD}}{ 2 -3} \\ \test{ -7 \word{StoD} -3 \word{FM/MOD}}{-1 2} \\ \test{MAX-INT \word{StoD} 1 \word{FM/MOD}}{ 0 MAX-INT} \\ \test{MIN-INT \word{StoD} 1 \word{FM/MOD}}{ 0 MIN-INT} \\ \test{MAX-INT \word{StoD} MAX-INT \word{FM/MOD}}{ 0 1} \\ \test{MIN-INT \word{StoD} MIN-INT \word{FM/MOD}}{ 0 1} \\ \test{ 1S 1 4 \word{FM/MOD}}{ 3 MAX-INT} \\ \test{ 1 MIN-INT \word{M*} 1 \word{FM/MOD}}{ 0 MIN-INT} \\ \test{ 1 MIN-INT \word{M*} MIN-INT \word{FM/MOD}}{ 0 1} \\ \test{ 2 MIN-INT \word{M*} 2 \word{FM/MOD}}{ 0 MIN-INT} \\ \test{ 2 MIN-INT \word{M*} MIN-INT \word{FM/MOD}}{ 0 2} \\ \test{ 1 MAX-INT \word{M*} 1 \word{FM/MOD}}{ 0 MAX-INT} \\ \test{ 1 MAX-INT \word{M*} MAX-INT \word{FM/MOD}}{ 0 1} \\ \test{ 2 MAX-INT \word{M*} 2 \word{FM/MOD}}{ 0 MAX-INT} \\ \test{ 2 MAX-INT \word{M*} MAX-INT \word{FM/MOD}}{ 0 2} \\ \test{MIN-INT MIN-INT \word{M*} MIN-INT \word{FM/MOD}}{ 0 MIN-INT} \\ \test{MIN-INT MAX-INT \word{M*} MIN-INT \word{FM/MOD}}{ 0 MAX-INT} \\ \test{MIN-INT MAX-INT \word{M*} MAX-INT \word{FM/MOD}}{ 0 MIN-INT} \\ \test{MAX-INT MAX-INT \word{M*} MAX-INT \word{FM/MOD}}{ 0 MAX-INT} \end{testing} \end{worddef} \enlargethispage{4ex} \begin{worddef}{1650}{HERE} \item \stack{}{addr} \param{addr} is the data-space pointer. \see \xref[3.3.3.2 Contiguous regions]{usage:contiguous}. \begin{testing} % T.6.1.1650 HERE See \tref{core:,}{,}, \tref{core:ALLOT}{ALLOT}, \tref{core:C,}{C,}. \end{testing} \end{worddef} \begin{worddef}{1670}{HOLD} \item \stack{char}{} Add \param{char} to the beginning of the pictured numeric output string. An ambiguous condition exists if \word{HOLD} executes outside of a \word{num-start} \word{num-end} delimited number conversion. \begin{testing} % T.6.1.1670 HOLD \ttfamily \word{:} GP1 \word{num-start} 41 \word{HOLD} 42 \word{HOLD} 0 0 \word{num-end} \word{Sq} BA" S= \word{;} \\ \test{GP1}{} \end{testing} \end{worddef} \begin{worddef}{1680}{I} \interpret Interpretation semantics for this word are undefined. \execute \stack{}{n|u} \stack[R]{loop-sys}{loop-sys} \param{n|u} is a copy of the current (innermost) loop index. An ambiguous condition exists if the loop control parameters are unavailable. \begin{testing} % T.6.1.1680 I See \tref{core:LOOP}{LOOP}, \tref{core:+LOOP}{+LOOP}, \tref{core:J}{J}, \tref{core:LEAVE}{LEAVE}, \tref{core:UNLOOP}{UNLOOP}. \end{testing} \end{worddef} \begin{worddef}{1700}{IF} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{orig} Put the location of a new unresolved forward reference \param{orig} onto the control flow stack. Append the run-time semantics given below to the current definition. The semantics are incomplete until \param{orig} is resolved, e.g., by \word{THEN} or \word{ELSE}. \runtime \stack{x}{} If all bits of \param{x} are zero, continue execution at the location specified by the resolution of \param{orig}. \see \xref[3.2.3.2 Control flow stack]{usage:controlstack}, \wref{core:ELSE}{ELSE}, \wref{core:THEN}{THEN}, \rref{core:IF}{}. \begin{rationale} % A.6.1.1700 IF Typical use: \tab \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{THEN} {\ldots} \word{;} or \tab \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{ELSE} {\ldots} \word{THEN} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.1700 IF \test{\word{:} GI1 \word{IF} 123 \word{THEN} \word{;}}{} \\ \test{\word{:} GI2 \word{IF} 123 \word{ELSE} 234 \word{THEN} \word{;}}{} \\ \test{ 0 GI1}{ } \\ \test{ 1 GI1}{123} \\ \test{-1 GI1}{123} \\ \test{ 0 GI2}{234} \\ \test{ 1 GI2}{123} \\ \test{-1 GI1}{123} \word{bs} \textdf{Multiple \word{ELSE}s in an \word{IF} statement} \\ \word{:} melse \word{IF} 1 \word{ELSE} 2 \word{ELSE} 3 \word{ELSE} 4 \word{ELSE} 5 \word{THEN} \word{;} \\ \test{ melse}{2 4} \\ \test{ melse}{1 3 5} \end{testing} \end{worddef} \begin{worddef}{1710}{IMMEDIATE} \item \stack{}{} Make the most recent definition an immediate word. An ambiguous condition exists if the most recent definition does not have a name or if it was defined as a \word[tools]{SYNONYM}. \see \wref{tools:SYNONYM}, \rref{core:IMMEDIATE}{}. \begin{rationale} % A.6.1.1710 IMMEDIATE Typical use: \word{:} \texttt{X} {\ldots} \word{;} \word{IMMEDIATE} \end{rationale} \begin{testing} % T.6.1.1710 IMMEDIATE \test{123 \word{CONSTANT} iw1 \word{IMMEDIATE} iw1}{123} \\ \test{\word{:} iw2 iw1 \word{LITERAL} \word{;} iw2}{123} \test{\word{VARIABLE} iw3 \word{IMMEDIATE} 234 iw3 \word{!} iw3 \word{@}}{234} \\ \test{\word{:} iw4 iw3 \word{[} \word{@} \word{]} \word{LITERAL} \word{;} iw4}{234} \test{\word{:NONAME} \word{[} 345 \word{]} iw3 \word{[} \word{!} \word{]} \word{;} \word{DROP} iw3 \word{@}}{345} \\ \test{\word{CREATE} iw5 456 \word{,} \word{IMMEDIATE}}{} \\ \test{\word{:NONAME} iw5 \word{[} \word{@} iw3 \word{!} \word{]} \word{;} \word{DROP} iw3 \word{@}}{456} \test{\word{:} iw6 \word{CREATE} \word{,} \word{IMMEDIATE} \word{DOES} \word{@} \word{1+} \word{;}}{} \\ \test{111 iw6 iw7 iw7}{112} \\ \test{\word{:} iw8 iw7 \word{LITERAL} \word{1+} \word{;} iw8}{113} \test{\word{:} iw9 \word{CREATE} \word{,} \word{DOES} \word{@} 2 \word{+} \word{IMMEDIATE} \word{;}}{} \\ \word{:} find-iw \word{BL} \word{WORD} \word{FIND} \word{NIP} \word{;} \\ \test{222 iw9 iw10 find-iw iw10}{-1} \tab \word{bs} \textdf{iw10 is not immediate} \\ \test{iw10 find-iw iw10}{224 1} \tab[3.8] \word{bs} \textdf{iw10 becomes immediate} See \tref{core:[']}{[']}, \tref{core:POSTPONE}{POSTPONE}, \tref{core:STATE}{STATE}, \tref{core:Sq}{S"}. \end{testing} \end{worddef} \begin{worddef}{1720}{INVERT} \item \stack{x_1}{x_2} Invert all bits of \param{x_1}, giving its logical inverse \param{x_2}. \see \wref{core:NEGATE}{NEGATE}, \wref{core:0=}{0=}, \rref{core:INVERT}{}. \begin{rationale} % A.6.1.1720 INVERT The word \texttt{NOT} was originally provided in Forth as a flag operator to make control structures readable. Under its intended usage the following two definitions would produce identical results: \begin{quote}\ttfamily \word{:} ONE \word{p} flag -{}- ) \\ \tab \word{IF} \word{.q} true" \word{ELSE} \word{.q} false" \word{THEN} \word{;} \word{:} TWO \word{p} flag -{}- ) \\ \tab NOT \word{IF} \word{.q} false" \word{ELSE} \word{.q} true" \word{THEN} \word{;} \end{quote} This was common usage prior to the Forth-83 Standard which redefined \texttt{NOT} as a cell-wide one's-complement operation, functionally equivalent to the phrase \texttt{-1} \word{XOR}. At the same time, the data type manipulated by this word was changed from a flag to a cell-wide collection of bits and the standard value for true was changed from ``1'' (rightmost bit only set) to ``-1'' (all bits set). As these definitions of \word{TRUE} and \texttt{NOT} were incompatible with their previous definitions, many Forth users continue to rely on the old definitions. Hence both versions are in common use. Therefore, usage of \texttt{NOT} cannot be standardized at this time. The two traditional meanings of \texttt{NOT} --- that of negating the sense of a flag and that of doing a one's complement operation --- are made available by \word{0=} and \word{INVERT}, respectively. \end{rationale} \begin{testing} % T.6.1.1720 INVERT \test{0S \word{INVERT}}{1S} \\ \test{1S \word{INVERT}}{0S} \end{testing} \end{worddef} \begin{worddef}{1730}{J} \interpret Interpretation semantics for this word are undefined. \execute \stack{}{n|u} \stack[R]{loop-sys_1 loop-sys_2}{loop-sys_1 loop-sys_2} \param{n|u} is a copy of the next-outer loop index. An ambiguous condition exists if the loop control parameters of the next-outer loop, \param{loop-sys_1}, are unavailable. \see \rref{core:J}{}. \begin{rationale} % A.6.1.1730 J \word{J} may only be used with a nested \word{DO} {\ldots} \word{LOOP}, \word{DO} {\ldots} \word{+LOOP}, \word{qDO} {\ldots} \word{LOOP}, or \word{qDO} {\ldots} \word{+LOOP}, for example, in the form: \tab \word{:} \texttt{X} {\ldots} \word{DO} {\ldots} \word{DO} {\ldots} \word{J} {\ldots} \word{LOOP} {\ldots} \word{+LOOP} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.1730 J \test{\word{:} GD3 \word{DO} 1 0 \word{DO} \word{J} \word{LOOP} \word{LOOP} \word{;}}{} \\ \test{ 4 1 GD3}{ 1 2 3 } \\ \test{ 2 -1 GD3}{-1 0 1 } \\ \test{MID-UINT+1 MID-UINT GD3}{MID-UINT} \test{\word{:} GD4 \word{DO} 1 0 \word{DO} \word{J} \word{LOOP} -1 \word{+LOOP} \word{;}}{} \\ \test{ 1 4 GD4}{4 3 2 1 } \\ \test{ -1 2 GD4}{2 1 0 -1 } \\ \test{MID-UINT MID-UINT+1 GD4}{MID-UINT+1 MID-UINT} \end{testing} \end{worddef} \begin{worddef}{1750}{KEY} \item \stack{}{char} Receive one character \param{char}, a member of the implementation-defined character set. Keyboard events that do not correspond to such characters are discarded until a valid character is received, and those events are subsequently unavailable. All standard characters can be received. Characters received by \word{KEY} are not displayed. Any standard character returned by \word{KEY} has the numeric value specified in \xref[3.1.2.1 Graphic characters]{usage:ASCII}. Programs that require the ability to receive control characters have an environmental dependency. \see \wref{facility:EKEY}{EKEY}, \wref{facility:EKEYq}{KEY?}, \wref{facility:KEYq}{}, \rref{core:KEY}{}. \begin{rationale} % KEY Use of \word{KEY} indicates that the application is processing primitive characters. Some input devices, e.g., keyboards, may provide more information than can be represented as a primitive character and such an event may be received as an implementation-specific sequence of primitive characters. See \rref{facility:EKEY}{}. \end{rationale} \end{worddef} \pagebreak \begin{worddef}{1760}{LEAVE} \interpret Interpretation semantics for this word are undefined. \execute \stack{}{} \stack[R]{loop-sys}{} Discard the current loop control parameters. An ambiguous condition exists if they are unavailable. Continue execution immediately following the innermost syntactically enclosing \word{DO}\ldots\word{LOOP} or \word{DO}\ldots\word{+LOOP}. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:+LOOP}{+LOOP}, \wref{core:LOOP}{LOOP}, \rref{core:LEAVE}{}. \begin{rationale} % A.6.1.1760 LEAVE Note that \word{LEAVE} immediately exits the loop. No words following \word{LEAVE} within the loop will be executed. Typical use: \tab \word{:} \texttt{X} {\ldots} \word{DO} {\ldots} \word{IF} {\ldots} \word{LEAVE} \word{THEN} \place{ed13}{{\ldots} \word{LOOP} {\ldots}} \word{;} \end{rationale} \begin{testing} % T.6.1.1760 LEAVE \test{\word{:} GD5 123 \word{SWAP} 0 \word{DO} \\ \tab[2] \word{I} 4 \word{more} \word{IF} \word{DROP} 234 \word{LEAVE} \word{THEN} \\ \tab \word{LOOP} \word{;}}{} \\ \test{1 GD5}{123} \\ \test{5 GD5}{123} \\ \test{6 GD5}{234} \end{testing} \end{worddef} \enlargethispage{4ex} \begin{worddef}{1780}{LITERAL} \interpret Interpretation semantics for this word are undefined. \compile \stack{x}{} Append the run-time semantics given below to the current definition. \runtime \stack{}{x} Place \param{x} on the stack. \see \rref{core:LITERAL}{}. \begin{rationale} % A.6.1.1780 LITERAL Typical use: \word{:} \texttt{X} {\ldots} \word{[} \texttt{x} \word{]} \word{LITERAL} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.1780 LITERAL \test{\word{:} GT3 GT2 \word{LITERAL} \word{;}}{} \\ \test{GT3}{\word{'} GT1} \end{testing} \end{worddef} \begin{worddef}{1800}{LOOP} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{do-sys}{} Append the run-time semantics given below to the current definition. Resolve the destination of all unresolved occurrences of \word{LEAVE} between the location given by \param{do-sys} and the next location for a transfer of control, to execute the words following the \word{LOOP}. \runtime \stack{}{} \stack[R]{loop-sys_1}{| loop-sys_2} An ambiguous condition exists if the loop control parameters are unavailable. Add one to the loop index. If the loop index is then equal to the loop limit, discard the loop parameters and continue execution immediately following the loop. Otherwise continue execution at the beginning of the loop. \see \wref{core:DO}{DO}, \wref{core:I}{I}, \wref{core:LEAVE}{LEAVE}% \rref{core:LOOP}{}. \begin{rationale} % A.6.1.1800 LOOP Typical use: \tab \word{:} \texttt{X} {\ldots} \emph{limit} \emph{first} \word{DO} {\ldots} \word{LOOP} {\ldots} \word{;} or \tab \word{:} \texttt{X} {\ldots} \emph{limit} \emph{first} \word{qDO} {\ldots} \word{LOOP} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.1800 LOOP \test{\word{:} GD1 \word{DO} \word{I} \word{LOOP} \word{;}}{} \\ \test{ 4 1 GD1}{ 1 2 3 } \\ \test{ 2 -1 GD1}{-1 0 1 } \\ \test{MID-UINT+1 MID-UINT GD1}{MID-UINT} \end{testing} \end{worddef} \begin{worddef}{1805}{LSHIFT}[l-shift] \item \stack{x_1 u}{x_2} Perform a logical left shift of \param{u} bit-places on \param{x_1}, giving \param{x_2}. Put zeroes into the least significant bits vacated by the shift. An ambiguous condition exists if \param{u} is greater than or equal to the number of bits in a cell. \begin{testing} % T.6.1.1805 LSHIFT \test{ 1 0 \word{LSHIFT}}{ 1} \\ \test{ 1 1 \word{LSHIFT}}{ 2} \\ \test{ 1 2 \word{LSHIFT}}{ 4} \\ \test{ 1 F \word{LSHIFT}}{8000} \tab[2] \word{bs} BIGGEST GUARANTEED SHIFT \\ \test{ 1S 1 \word{LSHIFT} 1 \word{XOR}}{1S} \\ \test{MSB 1 \word{LSHIFT}}{ 0} \end{testing} \end{worddef} \begin{worddef}{1810}{M*}[m-star] \item \stack{n_1 n_2}{d} \param{d} is the signed product of \param{n_1} times \param{n_2}. \see \rref{core:M*}{}. \begin{rationale} % A.6.1.1810 M* This word is a useful early step in calculation, going to extra precision conveniently. It has been in use since the Forth systems of the early 1970's. \end{rationale} \begin{testing} % T.6.1.1810 M* \test{ 0 0 \word{M*}}{ 0 \word{StoD}} \\ \test{ 0 1 \word{M*}}{ 0 \word{StoD}} \\ \test{ 1 0 \word{M*}}{ 0 \word{StoD}} \\ \test{ 1 2 \word{M*}}{ 2 \word{StoD}} \\ \test{ 2 1 \word{M*}}{ 2 \word{StoD}} \\ \test{ 3 3 \word{M*}}{ 9 \word{StoD}} \\ \test{ -3 3 \word{M*}}{ -9 \word{StoD}} \\ \test{ 3 -3 \word{M*}}{ -9 \word{StoD}} \\ \test{ -3 -3 \word{M*}}{ 9 \word{StoD}} \\ \test{ 0 MIN-INT \word{M*}}{ 0 \word{StoD}} \\ \test{ 1 MIN-INT \word{M*}}{MIN-INT \word{StoD}} \\ \test{ 2 MIN-INT \word{M*}}{ 0 1S } \\ \test{ 0 MAX-INT \word{M*}}{ 0 \word{StoD}} \\ \test{ 1 MAX-INT \word{M*}}{MAX-INT \word{StoD}} \\ \test{ 2 MAX-INT \word{M*}}{MAX-INT 1 \word{LSHIFT} 0} \\ \test{MIN-INT MIN-INT \word{M*}}{ 0 MSB 1 \word{RSHIFT} } \\ \test{MAX-INT MIN-INT \word{M*}}{ MSB MSB \word{2/} } \\ \test{MAX-INT MAX-INT \word{M*}}{ 1 MSB \word{2/} \word{INVERT} } \end{testing} \end{worddef} \begin{worddef}{1870}{MAX} \item \stack{n_1 n_2}{n_3} \param{n_3} is the greater of \param{n_1} and \param{n_2}. \begin{testing} % T.6.1.1870 MAX \test{ 0 1 \word{MAX}}{ 1} \\ \test{ 1 2 \word{MAX}}{ 2} \\ \test{ -1 0 \word{MAX}}{ 0} \\ \test{ -1 1 \word{MAX}}{ 1} \\ \test{MIN-INT 0 \word{MAX}}{ 0} \\ \test{MIN-INT MAX-INT \word{MAX}}{MAX-INT} \\ \test{ 0 MAX-INT \word{MAX}}{MAX-INT} \\ \test{ 0 0 \word{MAX}}{ 0} \\ \test{ 1 1 \word{MAX}}{ 1} \\ \test{ 1 0 \word{MAX}}{ 1} \\ \test{ 2 1 \word{MAX}}{ 2} \\ \test{ 0 -1 \word{MAX}}{ 0} \\ \test{ 1 -1 \word{MAX}}{ 1} \\ \test{ 0 MIN-INT \word{MAX}}{ 0} \\ \test{MAX-INT MIN-INT \word{MAX}}{MAX-INT} \\ \test{MAX-INT 0 \word{MAX}}{MAX-INT} \\ \end{testing} \end{worddef} \begin{worddef}{1880}{MIN} \item \stack{n_1 n_2}{n_3} \param{n_3} is the lesser of \param{n_1} and \param{n_2}. \begin{testing} % T.6.1.1880 MIN \test{ 0 1 \word{MIN}}{ 0} \\ \test{ 1 2 \word{MIN}}{ 1} \\ \test{ -1 0 \word{MIN}}{ -1} \\ \test{ -1 1 \word{MIN}}{ -1} \\ \test{MIN-INT 0 \word{MIN}}{MIN-INT} \\ \test{MIN-INT MAX-INT \word{MIN}}{MIN-INT} \\ \test{ 0 MAX-INT \word{MIN}}{ 0} \\ \test{ 0 0 \word{MIN}}{ 0} \\ \test{ 1 1 \word{MIN}}{ 1} \\ \test{ 1 0 \word{MIN}}{ 0} \\ \test{ 2 1 \word{MIN}}{ 1} \\ \test{ 0 -1 \word{MIN}}{ -1} \\ \test{ 1 -1 \word{MIN}}{ -1} \\ \test{ 0 MIN-INT \word{MIN}}{MIN-INT} \\ \test{MAX-INT MIN-INT \word{MIN}}{MIN-INT} \\ \test{MAX-INT 0 \word{MIN}}{ 0} \\ \end{testing} \end{worddef} \begin{worddef}{1890}{MOD} \item \stack{n_1 n_2}{n_3} Divide \param{n_1} by \param{n_2}, giving the single-cell remainder \param{n_3}. An ambiguous condition exists if \param{n_2} is zero. If \param{n_1} and \param{n_2} differ in sign, the implementation-defined result returned will be the same as that returned by either the phrase \word{toR} \word{StoD} \word{Rfrom} \word{FM/MOD} \word{DROP} or the phrase \word{toR} \word{StoD} \word{Rfrom} \word{SM/REM} \word{DROP}. \see \xref[3.2.2.1 Integer division]{usage:div}. \begin{testing} % T.6.1.1890 MOD \ttfamily IFFLOORED \tab \word{:} TMOD T/MOD \word{DROP} \word{;} \\ IFSYM \tab[2.8] \word{:} TMOD T/MOD \word{DROP} \word{;} \test{ 0 1 \word{MOD}}{ 0 1 TMOD} \\ \test{ 1 1 \word{MOD}}{ 1 1 TMOD} \\ \test{ 2 1 \word{MOD}}{ 2 1 TMOD} \\ \test{ -1 1 \word{MOD}}{ -1 1 TMOD} \\ \test{ -2 1 \word{MOD}}{ -2 1 TMOD} \\ \test{ 0 -1 \word{MOD}}{ 0 -1 TMOD} \\ \test{ 1 -1 \word{MOD}}{ 1 -1 TMOD} \\ \test{ 2 -1 \word{MOD}}{ 2 -1 TMOD} \\ \test{ -1 -1 \word{MOD}}{ -1 -1 TMOD} \\ \test{ -2 -1 \word{MOD}}{ -2 -1 TMOD} \\ \test{ 2 2 \word{MOD}}{ 2 2 TMOD} \\ \test{ -1 -1 \word{MOD}}{ -1 -1 TMOD} \\ \test{ -2 -2 \word{MOD}}{ -2 -2 TMOD} \\ \test{ 7 3 \word{MOD}}{ 7 3 TMOD} \\ \test{ 7 -3 \word{MOD}}{ 7 -3 TMOD} \\ \test{ -7 3 \word{MOD}}{ -7 3 TMOD} \\ \test{ -7 -3 \word{MOD}}{ -7 -3 TMOD} \\ \test{MAX-INT 1 \word{MOD}}{MAX-INT 1 TMOD} \\ \test{MIN-INT 1 \word{MOD}}{MIN-INT 1 TMOD} \\ \test{MAX-INT MAX-INT \word{MOD}}{MAX-INT MAX-INT TMOD} \\ \test{MIN-INT MIN-INT \word{MOD}}{MIN-INT MIN-INT TMOD} \end{testing} \end{worddef} \begin{worddef}{1900}{MOVE} \item \stack{addr_1 addr_2 u}{} If \param{u} is greater than zero, copy the contents of \param{u} consecutive address units at \param{addr_1} to the \param{u} consecutive address units at \param{addr_2}. After \word{MOVE} completes, the \param{u} consecutive address units at \param{addr_2} contain exactly what the \param{u} consecutive address units at \param{addr_1} contained before the move. \see \wref{string:CMOVE}{CMOVE}, \wref{string:CMOVEtop}{CMOVE>}, \rref{core:MOVE}{}. \begin{rationale} % A.6.1.1900 MOVE \word[string]{CMOVE} and \word[string]{CMOVEtop} are the primary move operators in Forth 83. They specify a behavior for moving that implies propagation if the move is suitably invoked. In some hardware, this specific behavior cannot be achieved using the best move instruction. Further, \word[string]{CMOVE} and \word[string]{CMOVEtop} move characters; Forth needs a move instruction capable of dealing with address units. Thus \word{MOVE} has been defined and added to the Core word set, and \word[string]{CMOVE} and \word[string]{CMOVEtop} have been moved to the String word set. \end{rationale} \begin{testing} % T.6.1.1900 MOVE \test{FBUF FBUF 3 \word{CHARS} \word{MOVE}}{} \hfill \word{bs} BIZARRE SPECIAL CASE \\ \test{SEEBUF}{20 20 20} \test{SBUF FBUF 0 \word{CHARS} \word{MOVE}}{} \\ \test{SEEBUF}{20 20 20} \test{SBUF FBUF 1 \word{CHARS} \word{MOVE}}{} \\ \test{SEEBUF}{12 20 20} \test{SBUF FBUF 3 \word{CHARS} \word{MOVE}}{} \\ \test{SEEBUF}{12 34 56} \test{FBUF FBUF \word{CHAR+} 2 \word{CHARS} \word{MOVE}}{} \\ \test{SEEBUF}{12 12 34} \test{FBUF \word{CHAR+} FBUF 2 \word{CHARS} \word{MOVE}}{} \\ \test{SEEBUF}{12 34 34} \end{testing} \end{worddef} \enlargethispage{8ex} \begin{worddef}{1910}{NEGATE} \item \stack{n_1}{n_2} Negate \param{n_1}, giving its arithmetic inverse \param{n_2}. \see \wref{core:INVERT}{INVERT}, \wref{core:0=}{0=}. \begin{testing} % T.6.1.1910 NEGATE \test{ 0 \word{NEGATE}}{ 0} \\ \test{ 1 \word{NEGATE}}{-1} \\ \test{-1 \word{NEGATE}}{ 1} \\ \test{ 2 \word{NEGATE}}{-2} \\ \test{-2 \word{NEGATE}}{ 2} \end{testing} \end{worddef} \begin{worddef}{1980}{OR} \item \stack{x_1 x_2}{x_3} \param{x_3} is the bit-by-bit inclusive-or of \param{x_1} with \param{x_2}. \begin{testing} % T.6.1.1980 OR \test{0S 0S \word{OR}}{0S} \\ \test{0S 1S \word{OR}}{1S} \\ \test{1S 0S \word{OR}}{1S} \\ \test{1S 1S \word{OR}}{1S} \end{testing} \end{worddef} \begin{worddef}{1990}{OVER} \item \stack{x_1 x_2}{x_1 x_2 x_1} Place a copy of \param{x_1} on top of the stack. \begin{testing} % T.6.1.1990 OVER \test{1 2 \word{OVER}}{1 2 1} \end{testing} \end{worddef} \begin{worddef}{2033}{POSTPONE} \interpret Interpretation semantics for this word are undefined. \compile \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Find \param{name}. Append the compilation semantics of \param{name} to the current definition. An ambiguous condition exists if \param{name} is not found. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:POSTPONE}{}. \begin{rationale} % A.6.1.2033 POSTPONE Typical use: \tab \word{:} \texttt{ENDIF} \word{POSTPONE} \word{THEN} \word{;} \word{IMMEDIATE} \tab \word{:} \texttt{X} {\ldots} \word{IF} {\ldots} \texttt{ENDIF} {\ldots} \word{;} \word{POSTPONE} replaces most of the functionality of \texttt{COMPILE} and \word{[COMPILE]}. \texttt{COMPILE} and \linebreak \word{[COMPILE]} are used for the same purpose: postpone the compilation behavior of the next word in the parse area. \texttt{COMPILE} was designed to be applied to non-immediate words and \word{[COMPILE]} to immediate words. This burdens the programmer with needing to know which words in a system are immediate. Consequently, Forth standards have had to specify the immediacy or non-immediacy of all words covered by the standard. This unnecessarily constrains implementors. A second problem with \texttt{COMPILE} is that some programmers have come to expect and exploit a particular implementation, namely: \tab \word{:} \texttt{COMPILE} \word{Rfrom} \word{DUP} \word{@} \word{,} \word{CELL+} \word{toR} \word{;} This implementation will not work on native code Forth systems. In a native code Forth using inline code expansion and peephole optimization, the size of the object code produced varies; this information is difficult to communicate to a ``dumb'' \texttt{COMPILE}. A ``smart'' (i.e., immediate) \texttt{COMPILE} would not have this problem, but this was forbidden in previous standards. For these reasons, \texttt{COMPILE} has not been included in the standard and \word{[COMPILE]} has been moved in favor of \word{POSTPONE}. Additional discussion can be found in Hayes, J.R., ``Postpone'', \emph{Proceedings of the 1989 Rochester Forth Conference}. \end{rationale} \begin{testing} % T.6.1.2033 POSTPONE \test{\word{:} GT4 \word{POSTPONE} GT1 \word{;} \word{IMMEDIATE}}{} \\ \test{\word{:} GT5 GT4 \word{;}}{} \\ \test{GT5}{123} \test{\word{:} GT6 345 \word{;} \word{IMMEDIATE}}{} \\ \test{\word{:} GT7 \word{POSTPONE} GT6 \word{;}}{} \\ \test{GT7}{345} \end{testing} \end{worddef} \begin{worddef}{2050}{QUIT} \item \stack{}{} \stack[R]{i*x}{} Empty the return stack, store zero in \word{SOURCE-ID} if it is present, make the user input device the input source, and enter interpretation state. Do not display a message. Repeat the following: \begin{itemize} \item Accept a line from the input source into the input buffer, set \word{toIN} to zero, and interpret. \item Display the implementation-defined system prompt if in interpretation state, all processing has been completed, and no ambiguous condition exists. \end{itemize} \see \xref[3.4 The Forth text interpreter]{usage:command}. \begin{implement} \word{:} \word{QUIT} \\ \tab \word{p} \textdf{empty the return stack and set the input source to the user input device} ) \\ \tab \word{POSTPONE} \word{[} \\ \tab[2] \word{REFILL} \\ \tab \word{WHILE} \\ \tab[2] \word{[']} INTERPRET \word[exception]{CATCH} \\ \tab[2] \word{CASE} \\ \tab[2] ~0 \word{OF} \word{STATE} \word{@} \word{0=} \word{IF} \word{.q} OK" \word{THEN} \word{CR} \word{ENDOF} \\ \tab[2] -1 \word{OF} \word{p} \textdf{Aborted} ) \word{ENDOF} \\ \tab[2] -2 \word{OF} \word{p} \textdf{display message from \word{ABORTq}} ) \word{ENDOF} \\ \tab[2] \word{p} \textdf{default} ) \word{DUP} \word{.q} Exception \# " \word{d} \\ \tab[2] \word{ENDCASE} \\ \tab \word{REPEAT} \word[tools]{BYE} \\ \word{;} \dffamily This assumes the existence of a system-implementation word \texttt{INTERPRET} that embodies the text interpreter semantics described in \xref[3.4 The Forth text interpreter]{usage:command}. Further discussion of the interpret loop can be found in \rref{core:COMPILE,}{}. \end{implement} \end{worddef} \enlargethispage{8ex} \begin{worddef}[Rfrom]{2060}{R>}[r-from] \interpret Interpretation semantics for this word are undefined. \execute \stack{}{x} \stack[R]{x}{} Move \param{x} from the return stack to the data stack. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:toR}{>R}, \wref{core:R@}{R@}, \wref{core:2toR}{2>R}, \wref{core:2Rfrom}{2R>}, \wref{core:2R@}{2R@}. \begin{testing} % T.6.1.2060 R> See \tref{core:toR}{>R}. \end{testing} \end{worddef} \begin{worddef}{2070}{R@}[r-fetch] \interpret Interpretation semantics for this word are undefined. \execute \stack{}{x} \stack[R]{x}{x} Copy \param{x} from the return stack to the data stack. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:toR}{>R}, \wref{core:Rfrom}{R>}, \wref{core:2toR}{2>R}, \wref{core:2Rfrom}{2R>}, \wref{core:2R@}{2R@}. \begin{testing} % T.6.1.2070 R@ See \tref{core:toR}{>R}. \end{testing} \end{worddef} \begin{worddef}{2120}{RECURSE} \interpret Interpretation semantics for this word are undefined. \compile \stack{}{} Append the execution semantics of the current definition to the current definition. An ambiguous condition exists if \word{RECURSE} appears in a definition after \word{DOES}. \see \wref{core:DOES}{DOES>}, \wref{core:RECURSE}{RECURSE}, \rref{core:RECURSE}{}. \begin{rationale} % A.6.1.2120 RECURSE Typical use: \word{:} \texttt{X} {\ldots} \word{RECURSE} {\ldots} \word{;} This is Forth's recursion operator; in some implementations it is called \texttt{MYSELF}. The usual example is the coding of the factorial function. \begin{quote}\ttfamily \word{:} FACTORIAL \word{p} +n1 -{}- +n2) \\ \tab \word{DUP} 2 \word{less} \word{IF}~ \word{DROP} 1 \word{EXIT}~ \word{THEN} \\ \tab \word{DUP} 1- ~\word{RECURSE}~ \word{*} \\ \word{;} \end{quote} $n_2 = n_1(n_1-1)(n_1-2)\cdots(2)(1)$, the product of $n_1$ with all positive integers less than itself (as a special case, zero factorial equals one). While beloved of computer scientists, recursion makes unusually heavy use of both stacks and should therefore be used with caution. See alternate definition in \rref{core:REPEAT}{REPEAT}. \end{rationale} \begin{testing} % T.6.1.2120 RECURSE \test{\word{:} GI6 \word{p} N -{}- 0,1,..N ) \\ \mbox{} \tab[1.8] \word{DUP} \word{IF} \word{DUP} \word{toR} \word{1-} \word{RECURSE} \word{Rfrom} \word{THEN} \word{;}}{} \\ \test{0 GI6}{0} \\ \test{1 GI6}{0 1} \\ \test{2 GI6}{0 1 2} \\ \test{3 GI6}{0 1 2 3} \\ \test{4 GI6}{0 1 2 3 4} \word{DECIMAL} \\ \test{\word{:NONAME} \word{p} n -{}- 0, 1, .., n ) \\ \tab[2] \word{DUP} \word{IF} \word{DUP} \word{toR} \word{1-} \word{RECURSE} \word{Rfrom} \word{THEN} \\ \tab \word{;} \\ \tab \word{CONSTANT} rn1}{} \\ \test{0 rn1 EXECUTE}{0} \\ \test{4 rn1 EXECUTE}{0 1 2 3 4} \word{:NONAME} \word{p} n -{}- n1 ) \\ \tab \word{1-} \word{DUP} \\ \tab \word{CASE} 0 \word{OF} \word{EXIT} \word{ENDOF} \\ \tab[2] 1 \word{OF} 11 \word{SWAP} \word{RECURSE} \word{ENDOF} \\ \tab[2] 2 \word{OF} 22 \word{SWAP} \word{RECURSE} \word{ENDOF} \\ \tab[2] 3 \word{OF} 33 \word{SWAP} \word{RECURSE} \word{ENDOF} \\ \tab[2] \word{DROP} \word{ABS} \word{RECURSE} \word{EXIT} \\ \tab \word{ENDCASE} \\ \word{;} \word{CONSTANT} rn2 \test{ 1 rn2 EXECUTE}{0} \\ \test{ 2 rn2 EXECUTE}{11 0} \\ \test{ 4 rn2 EXECUTE}{33 22 11 0} \\ \test{25 rn2 EXECUTE}{33 22 11 0} \end{testing} \end{worddef} \begin{worddef}{2140}{REPEAT} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{orig dest}{} Append the run-time semantics given below to the current definition, resolving the backward reference \param{dest}. Resolve the forward reference \param{orig} using the location following the appended run-time semantics. \runtime \stack{}{} Continue execution at the location given by \param{dest}. \see \wref{core:BEGIN}{BEGIN}, \wref{core:WHILE}{WHILE}, \rref{core:REPEAT}{}. \begin{rationale} % A.6.1.2140 REPEAT Typical use: \begin{quote}\ttfamily \word{:} FACTORIAL \word{p} +n1 -{}- +n2 ) \\ \tab \word{DUP} 2 \word{less} \word{IF}~ \word{DROP} 1 \word{EXIT}~ \word{THEN} \\ \tab \word{DUP} \\ \tab \word{BEGIN}~ \word{DUP} 2 \word{more} \word{WHILE} \\ \tab~~ 1- ~\word{SWAP} \word{OVER} \word{*}~ \word{SWAP} \\ \tab \word{REPEAT} \word{DROP} \\ \word{;} \end{quote} \end{rationale} \begin{testing} % T.6.1.2140 REPEAT See \tref{core:WHILE}{WHILE}. \end{testing} \end{worddef} \begin{worddef}{2160}{ROT}[rote] \item \stack{x_1 x_2 x_3}{x_2 x_3 x_1} Rotate the top three stack entries. \begin{testing} % T.6.1.2160 ROT \test{1 2 3 \word{ROT}}{2 3 1} \end{testing} \end{worddef} \begin{worddef}{2162}{RSHIFT}[r-shift] \item \stack{x_1 u}{x_2} Perform a logical right shift of \param{u} bit-places on \param{x_1}, giving \param{x_2}. Put zeroes into the most significant bits vacated by the shift. An ambiguous condition exists if \param{u} is greater than or equal to the number of bits in a cell. \begin{testing} % T.6.1.2162 RSHIFT \test{ 1 0 \word{RSHIFT}}{1} \\ \test{ 1 1 \word{RSHIFT}}{0} \\ \test{ 2 1 \word{RSHIFT}}{1} \\ \test{ 4 2 \word{RSHIFT}}{1} \\ \test{8000 F \word{RSHIFT}}{1} \tab[7] \word{bs} \textdf{Biggest} \\ \test{ MSB 1 \word{RSHIFT} MSB \word{AND}}{ 0} \tab[1] \word{bs} RSHIFT \textdf{zero fills MSBs} \\ \test{ MSB 1 \word{RSHIFT} \word{2*} }{MSB} \end{testing} \end{worddef} \enlargethispage{4ex} \begin{worddef}[Sq]{2165}{S"}[s-quote] \interpret Interpretation semantics for this word are undefined. \compile \stack{"ccc"}{} Parse \param{ccc} delimited by \texttt{"} (double-quote). Append the run-time semantics given below to the current definition. \runtime \stack{}{c-addr u} Return \param{c-addr} and \param{u} describing a string consisting of the characters \param{ccc}. A program shall not alter the returned string. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:Cq}{C"}, \wref{file:Sq}{S"}, \wref{core:Seq}{}, \rref{core:Sq}{}. \begin{rationale} % A.6.1.2165 S" Typical use: \word{:} \texttt{X} {\ldots} \word{Sq} \emph{ccc}\texttt{"} {\ldots} \word{;} \end{rationale} \begin{testing} % A.6.1.2165 S" \test{\word{:} GC4 \word{Sq} XY" \word{;}}{ } \\ \test{GC4 \word{SWAP} \word{DROP} }{2} \\ \test{GC4 \word{DROP} \word{DUP} \word{C@} \word{SWAP} \word{CHAR+} \word{C@}}{58 59} \word{:} GC5 \word{Sq} A String"\word{2DROP} \word{;} \word{bs} \textdf{There is no space between the " and \word{2DROP}} \\ \test{GC5}{} \end{testing} \end{worddef} \begin{worddef}[StoD]{2170}{S>D}[s-to-d] \item \stack{n}{d} Convert the number \param{n} to the double-cell number \param{d} with the same numerical value. \begin{testing} % T.6.1.2170 S>D \test{ 0 \word{StoD}}{ 0 0} \\ \test{ 1 \word{StoD}}{ 1 0} \\ \test{ 2 \word{StoD}}{ 2 0} \\ \test{ -1 \word{StoD}}{ -1 -1} \\ \test{ -2 \word{StoD}}{ -2 -1} \\ \test{MIN-INT \word{StoD}}{MIN-INT -1} \\ \test{MAX-INT \word{StoD}}{MAX-INT 0} \end{testing} \end{worddef} \begin{worddef}{2210}{SIGN} \item \stack{n}{} If \param{n} is negative, add a minus sign to the beginning of the pictured numeric output string. An ambiguous condition exists if \word{SIGN} executes outside of a \word{num-start} \word{num-end} delimited number conversion. \begin{testing} % T.6.1.2210 SIGN \ttfamily \word{:} GP2 \word{num-start} -1 \word{SIGN} 0 \word{SIGN} -1 \word{SIGN} 0 0 \word{num-end} \word{Sq} -{}-" S= \word{;} \\ \test{GP2}{} \end{testing} \end{worddef} \begin{worddef}{2214}{SM/REM}[s-m-slash-rem] \item \stack{d_1 n_1}{n_2 n_3} Divide \param{d_1} by \param{n_1}, giving the symmetric quotient \param{n_3} and the remainder \param{n_2}. Input and output stack arguments are signed. An ambiguous condition exists if \param{n_1} is zero or if the quotient lies outside the range of a single-cell signed integer. \see \xref[3.2.2.1 Integer division]{usage:div}, \wref{core:FM/MOD}{FM/MOD}, \wref{core:UM/MOD}{UM/MOD}, \rref{core:SM/REM}{}. \begin{rationale} % A.6.1.2214 SM/REM See the previous discussion of division under \word{FM/MOD}. \word{SM/REM} is the symmetric-division primitive, which allows programs to define the following symmetric-division operators: \begin{quote}\ttfamily \word{:} /-REM \word{p} n1 n2 -{}- n3 n4 ) \word{toR} \word{StoD} \word{Rfrom} \word{SM/REM} \word{;} \word{:} /- \word{p} n1 n2 -{}- n3 ) /-REM \word{SWAP} \word{DROP} \word{;} \word{:} -REM \word{p} n1 n2 -{}- n3 ) /-REM \word{DROP} \word{;} \word{:} */-REM \word{p} n1 n2 n3 -{}- n4 n5 ) \word{toR} \word{M*} \word{Rfrom} \word{SM/REM} \word{;} \word{:} */- \word{p} n1 n2 n3 -{}- n4 ) */-REM \word{SWAP} \word{DROP} \word{;} \end{quote} \end{rationale} \begin{testing} % T.6.1.2214 SM/REM \test{ 0 \word{StoD} 1 \word{SM/REM}}{ 0 0} \\ \test{ 1 \word{StoD} 1 \word{SM/REM}}{ 0 1} \\ \test{ 2 \word{StoD} 1 \word{SM/REM}}{ 0 2} \\ \test{ -1 \word{StoD} 1 \word{SM/REM}}{ 0 -1} \\ \test{ -2 \word{StoD} 1 \word{SM/REM}}{ 0 -2} \\ \test{ 0 \word{StoD} -1 \word{SM/REM}}{ 0 0} \\ \test{ 1 \word{StoD} -1 \word{SM/REM}}{ 0 -1} \\ \test{ 2 \word{StoD} -1 \word{SM/REM}}{ 0 -2} \\ \test{ -1 \word{StoD} -1 \word{SM/REM}}{ 0 1} \\ \test{ -2 \word{StoD} -1 \word{SM/REM}}{ 0 2} \\ \test{ 2 \word{StoD} 2 \word{SM/REM}}{ 0 1} \\ \test{ -1 \word{StoD} -1 \word{SM/REM}}{ 0 1} \\ \test{ -2 \word{StoD} -2 \word{SM/REM}}{ 0 1} \\ \test{ 7 \word{StoD} 3 \word{SM/REM}}{ 1 2} \\ \test{ 7 \word{StoD} -3 \word{SM/REM}}{ 1 -2} \\ \test{ -7 \word{StoD} 3 \word{SM/REM}}{ 1 -2} \\ \test{ -7 \word{StoD} -3 \word{SM/REM}}{-1 2} \\ \test{MAX-INT \word{StoD} 1 \word{SM/REM}}{ 0 MAX-INT} \\ \test{MIN-INT \word{StoD} 1 \word{SM/REM}}{ 0 MIN-INT} \\ \test{MAX-INT \word{StoD} MAX-INT \word{SM/REM}}{ 0 1} \\ \test{MIN-INT \word{StoD} MIN-INT \word{SM/REM}}{ 0 1} \\ \test{ 1S 1 4 \word{SM/REM}}{ 3 MAX-INT} \\ \test{ 2 MIN-INT \word{M*} 2 \word{SM/REM}}{ 0 MIN-INT} \\ \test{ 2 MIN-INT \word{M*} MIN-INT \word{SM/REM}}{ 0 2} \\ \test{ 2 MAX-INT \word{M*} 2 \word{SM/REM}}{ 0 MAX-INT} \\ \test{ 2 MAX-INT \word{M*} MAX-INT \word{SM/REM}}{ 0 2} \\ \test{MIN-INT MIN-INT \word{M*} MIN-INT \word{SM/REM}}{ 0 MIN-INT} \\ \test{MIN-INT MAX-INT \word{M*} MIN-INT \word{SM/REM}}{ 0 MAX-INT} \\ \test{MIN-INT MAX-INT \word{M*} MAX-INT \word{SM/REM}}{ 0 MIN-INT} \\ \test{MAX-INT MAX-INT \word{M*} MAX-INT \word{SM/REM}}{ 0 MAX-INT} \end{testing} \end{worddef} \begin{worddef}{2216}{SOURCE} \item \stack{}{c-addr u} \param{c-addr} is the address of, and \param{u} is the number of characters in, the input buffer. \see \rref{core:SOURCE}{}. \begin{rationale} % A.6.1.2216 SOURCE \word{SOURCE} simplifies the process of directly accessing the input buffer by hiding the differences between its location for different input sources. This also gives implementors more flexibility in their implementation of buffering mechanisms for different input sources. The committee moved away from an input buffer specification consisting of a collection of individual variables. \end{rationale} \begin{testing} % T.6.1.2216 SOURCE \ttfamily \word{:} GS1 \word{Sq} \word{SOURCE}" \word{2DUP} \word{EVALUATE} \word{toR} \word{SWAP} \word{toR} \word{=} \word{Rfrom} \word{Rfrom} \word{=} \word{;} \\ \test{GS1}{ } \word{:} GS4 \word{SOURCE} \word{toIN} \word{!} \word{DROP} \word{;} \\ \test{GS4 123 456 \\\mbox{}\tab[1.2]}{} \end{testing} \end{worddef} \begin{worddef}{2220}{SPACE} \item \stack{}{} Display one space. \begin{testing} % T.6.1.2220 SPACE See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \begin{worddef}{2230}{SPACES} \item \stack{n}{} If \param{n} is greater than zero, display \param{n} spaces. \begin{testing} % T.6.1.2230 SPACES See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \begin{worddef}{2250}{STATE} \item \stack{}{a-addr} \param{a-addr} is the address of a cell containing the compilation-state flag. \word{STATE} is \emph{true} when in compilation state, \emph{false} otherwise. The \emph{true} value in \word{STATE} is non-zero, but is otherwise implementation-defined. Only the following standard words alter the value in \word{STATE}: \word{:} (colon), \word{;} (semicolon), \word{ABORT}, \word{QUIT}, \word{:NONAME}, \word{[} (left-bracket), \word{]} (right-bracket). \note A program shall not directly alter the contents of \word{STATE}. \see \xref[3.4 The Forth text interpreter]{usage:command}, \wref{core::}{:}, \wref{core:;}{;} \wref{core:ABORT}{ABORT}, \wref{core:QUIT}{QUIT}, \wref{core:[}{[}, \wref{core:]}{]}, \wref{core::NONAME}{:NONAME}, \wref{tools:STATE}{STATE}, \rref{core:STATE}{}. \begin{rationale} % A.6.1.2250 STATE Although \word{EVALUATE}, \word[block]{LOAD}, \word[file]{INCLUDE-FILE} and \word[file]{INCLUDED} are not listed as words which alter \word{STATE}, the text interpreted by any one of these words could include one or more words which explicitly alter \word{STATE}. \word{EVALUATE}, \word[block]{LOAD}, \word[file]{INCLUDE-FILE} and \word[file]{INCLUDED} do not in themselves alter \word{STATE}. \word{STATE} does not nest with text interpreter nesting. For example, the code sequence: \tab \word{:} \texttt{FOO}~ \word{Sq} \texttt{]"} \word{EVALUATE} \word{;} \qquad \texttt{FOO} will leave the system in compilation state. Similarly, after \word[block]{LOAD}ing a block containing \word{]}, the system will be in compilation state. Note that \word{]} does not affect the parse area and that the only effect that \word{:} has on the parse area is to parse a word. This entitles a program to use these words to set the state with known side-effects on the parse area. For example: \tab \word{:} \texttt{NOP}~ \word{:} \word{POSTPONE} \word{;} \word{IMMEDIATE} \word{;} \tab \texttt{NOP} \word{ALIGN} \\ \tab \texttt{NOP} \word{ALIGNED} Some non-compliant systems have \word{]} invoke a compiler loop in addition to setting \word{STATE}. Such a system would inappropriately attempt to compile the second use of \texttt{NOP}. \end{rationale} \begin{testing} % T.6.1.2250 STATE \test{\word{:} GT8 \word{STATE} \word{@} \word{;} \word{IMMEDIATE}}{} \\ \test{GT8}{0} \\ \test{\word{:} GT9 GT8 \word{LITERAL} \word{;}}{} \\ \test{GT9 \word{0=}}{} \end{testing} \end{worddef} \begin{worddef}{2260}{SWAP} \item \stack{x_1 x_2}{x_2 x_1} Exchange the top two stack items. \begin{testing} % T.6.1.2260 SWAP \test{1 2 \word{SWAP}}{2 1} \end{testing} \end{worddef} \begin{worddef}{2270}{THEN} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{orig}{} Append the run-time semantics given below to the current definition. Resolve the forward reference \param{orig} using the location of the appended run-time semantics. \runtime \stack{}{} Continue execution. \see \wref{core:ELSE}{ELSE}, \wref{core:IF}{IF}, \rref{core:THEN}{}. \begin{rationale} % A.6.1.2270 THEN Typical use: \tab \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{THEN} {\ldots} \word{;} or \tab \word{:} \texttt{X} {\ldots} \emph{test} \word{IF} {\ldots} \word{ELSE} {\ldots} \word{THEN} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2270 THEN See \tref{core:IF}{IF}. \end{testing} \end{worddef} \begin{worddef}{2310}{TYPE} \item \stack{c-addr u}{} If \param{u} is greater than zero, display the character string specified by \param{c-addr} and \param{u}. When passed a character in a character string whose character-defining bits have a value between hex 20 and 7E inclusive, the corresponding standard character, specified by \xref[3.1.2.1 graphic characters]{usage:ASCII}, is displayed. Because different output devices can respond differently to control characters, programs that use control characters to perform specific functions have an environmental dependency. \see \wref{core:EMIT}{EMIT}. \begin{testing} % T.6.1.2310 TYPE See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \begin{worddef}[Ud]{2320}{U.{}}[u-dot] \item \stack{u}{} Display \param{u} in free field format. \begin{testing} % T.6.1.2320 U. See \tref{core:EMIT}{EMIT}. \end{testing} \end{worddef} \begin{worddef}[Uless]{2340}{U<}[u-less-than] \item \stack{u_1 u_2}{flag} \param{flag} is true if and only if \param{u_1} is less than \param{u_2}. \see \wref{core:less}{<}. \begin{testing} % T.6.1.2340 U< \test{ 0 1 \word{Uless}}{ } \\ \test{ 1 2 \word{Uless}}{ } \\ \test{ 0 MID-UINT \word{Uless}}{ } \\ \test{ 0 MAX-UINT \word{Uless}}{ } \\ \test{MID-UINT MAX-UINT \word{Uless}}{ } \\ \test{ 0 0 \word{Uless}}{} \\ \test{ 1 1 \word{Uless}}{} \\ \test{ 1 0 \word{Uless}}{} \\ \test{ 2 1 \word{Uless}}{} \\ \test{MID-UINT 0 \word{Uless}}{} \\ \test{MAX-UINT 0 \word{Uless}}{} \\ \test{MAX-UINT MID-UINT \word{Uless}}{} \end{testing} \end{worddef} \begin{worddef}{2360}{UM*}[u-m-star] \item \stack{u_1 u_2}{ud} Multiply \param{u_1} by \param{u_2}, giving the unsigned double-cell product \param{ud}. All values and arithmetic are unsigned. \begin{testing} % T.6.1.2360 UM* \test{0 0 \word{UM*}}{0 0} \\ \test{0 1 \word{UM*}}{0 0} \\ \test{1 0 \word{UM*}}{0 0} \\ \test{1 2 \word{UM*}}{2 0} \\ \test{2 1 \word{UM*}}{2 0} \\ \test{3 3 \word{UM*}}{9 0} \test{MID-UINT+1 1 \word{RSHIFT} 2 \word{UM*}}{ MID-UINT+1 0} \\ \test{MID-UINT+1 2 \word{UM*}}{ 0 1} \\ \test{MID-UINT+1 4 \word{UM*}}{ 0 2} \\ \test{ 1S 2 \word{UM*}}{1S 1 \word{LSHIFT} 1} \\ \test{ MAX-UINT MAX-UINT \word{UM*}}{ 1 1 \word{INVERT}} \end{testing} \end{worddef} \begin{worddef}{2370}{UM/MOD}[u-m-slash-mod] \item \stack{ud u_1}{u_2 u_3} Divide \param{ud} by \param{u_1}, giving the quotient \param{u_3} and the remainder \param{u_2}. All values and arithmetic are unsigned. An ambiguous condition exists if \param{u_1} is zero or if the quotient lies outside the range of a single-cell unsigned integer. \see \xref[3.2.2.1 Integer division]{usage:div}, \wref{core:FM/MOD}{FM/MOD}, \wref{core:SM/REM}{SM/REM}. \begin{testing} % T.6.1.2370 UM/MOD \test{ 0 0 1 \word{UM/MOD}}{0 0} \\ \test{ 1 0 1 \word{UM/MOD}}{0 1} \\ \test{ 1 0 2 \word{UM/MOD}}{1 0} \\ \test{ 3 0 2 \word{UM/MOD}}{1 1} \\ \test{MAX-UINT 2 \word{UM*} 2 \word{UM/MOD}}{0 MAX-UINT} \\ \test{MAX-UINT 2 \word{UM*} MAX-UINT \word{UM/MOD}}{0 2} \\ \test{MAX-UINT MAX-UINT \word{UM*} MAX-UINT \word{UM/MOD}}{0 MAX-UINT} \end{testing} \end{worddef} \pagebreak \begin{worddef}{2380}{UNLOOP} \interpret Interpretation semantics for this word are undefined. \execute \stack{}{} \stack[R]{loop-sys}{} Discard the loop-control parameters for the current nesting level. An \word{UNLOOP} is required for each nesting level before the definition may be \word{EXIT}ed. An ambiguous condition exists if the loop-control parameters are unavailable. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \rref{core:UNLOOP}{}. \begin{rationale} % A.6.1.2380 UNLOOP Typical use: \begin{quote} \word{:} \texttt{X} {\ldots} \\ \tab \emph{limit} \emph{first} \word{DO} \\ \tab~~ {\ldots} \emph{test} \word{IF} {\ldots} \word{UNLOOP} \word{EXIT} \word{THEN} {\ldots} \\ \tab \word{LOOP} {\ldots} \\ \word{;} \end{quote} \word{UNLOOP} allows the use of \word{EXIT} within the context of \word{DO} {\ldots} \word{LOOP} and related do-loop constructs. \word{UNLOOP} as a function has been called \texttt{UNDO}. \word{UNLOOP} is more indicative of the action: nothing gets undone --- we simply stop doing it. \end{rationale} \begin{testing} % T.6.1.2380 UNLOOP \test{\word{:} GD6 \word{p} PAT:{\small \{0 0\},\{0 0\}\{1 0\}\{1 1\},\{0 0\}\{1 0\}\{1 1\}\{2 0\}\{2 1\}\{2 2\}} ) \\ \tab[2.4] 0 \word{SWAP} 0 \word{DO} \\ \tab[3.6] \word{I} \word{1+} 0 \word{DO} \\ \tab[4.8] \word{I} \word{J} \word{+} 3 \word{=} \word{IF} \word{I} \word{UNLOOP} \word{I} \word{UNLOOP} \word{EXIT} \word{THEN} \word{1+} \\ \tab[3.6] \word{LOOP} \\ \tab[2.4] \word{LOOP} \word{;}}{} \\ \test{1 GD6}{1} \\ \test{2 GD6}{3} \\ \test{3 GD6}{4 1 2} \end{testing} \end{worddef} \begin{worddef}{2390}{UNTIL} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{dest}{} Append the run-time semantics given below to the current definition, resolving the backward reference \param{dest}. \runtime \stack{x}{} If all bits of \param{x} are zero, continue execution at the location specified by \param{dest}. \see \wref{core:BEGIN}{BEGIN}, \rref{core:UNTIL}{}. \begin{rationale} % A.6.1.2390 UNTIL Typical use: \word{:} \texttt{X} {\ldots} \word{BEGIN} {\ldots} \emph{test} \word{UNTIL} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2390 UNTIL \test{\word{:} GI4 \word{BEGIN} \word{DUP} \word{1+} \word{DUP} 5 \word{more} \word{UNTIL} \word{;}}{} \\ \test{3 GI4}{3 4 5 6} \\ \test{5 GI4}{5 6} \\ \test{6 GI4}{6 7} \end{testing} \end{worddef} \begin{worddef}{2410}{VARIABLE} \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below. Reserve one cell of data space at an aligned address. \param{name} is referred to as a ``variable''. \execute[name] \stack{}{a-addr} \param{a-addr} is the address of the reserved cell. A program is responsible for initializing the contents of the reserved cell. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:VARIABLE}{}. \begin{rationale} % A.6.1.2410 VARIABLE Typical use: \word{VARIABLE} \texttt{XYZ} \end{rationale} \begin{testing} % T.6.1.2410 VARIABLE \test{\word{VARIABLE} V1}{ } \\ \test{ 123 V1 \word{!}}{ } \\ \test{ V1 \word{@}}{123} \end{testing} \end{worddef} \pagebreak \begin{worddef}{2430}{WHILE} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{dest}{orig dest} Put the location of a new unresolved forward reference \param{orig} onto the control flow stack, under the existing \param{dest}. Append the run-time semantics given below to the current definition. The semantics are incomplete until \param{orig} and \param{dest} are resolved (e.g., by \word{REPEAT}). \runtime \stack{x}{} If all bits of \param{x} are zero, continue execution at the location specified by the resolution of \param{orig}. \see \rref{core:WHILE}{}. \begin{rationale} % A.6.1.2430 WHILE Typical use: \word{:} \texttt{X} {\ldots} \word{BEGIN} {\ldots} \emph{test} \word{WHILE} {\ldots} \word{REPEAT} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2430 WHILE \test{\word{:} GI3 \word{BEGIN} \word{DUP} 5 \word{less} \word{WHILE} \word{DUP} \word{1+} \word{REPEAT} \word{;}}{} \\ \test{0 GI3}{0 1 2 3 4 5} \\ \test{4 GI3}{4 5} \\ \test{5 GI3}{5} \\ \test{6 GI3}{6} \test{\word{:} GI5 \word{BEGIN} \word{DUP} 2 \word{more} \word{WHILE} \\ \tab[2.4] \word{DUP} 5 \word{less} \word{WHILE} \word{DUP} \word{1+} \word{REPEAT} \\ \tab[2.4] 123 \word{ELSE} 345 \word{THEN} \word{;}}{} \\ \test{1 GI5}{1 345} \\ \test{2 GI5}{2 345} \\ \test{3 GI5}{3 4 5 123} \\ \test{4 GI5}{4 5 123} \\ \test{5 GI5}{5 123} \end{testing} \end{worddef} \begin{worddef}{2450}{WORD} \item \stack{char "ccc"}{c-addr} Skip leading delimiters. Parse characters \param{ccc} delimited by \param{char}. An ambiguous condition exists if the length of the parsed string is greater than the implementation-defined length of a counted string. \param{c-addr} is the address of a transient region containing the parsed word as a counted string. If the parse area was empty or contained no characters other than the delimiter, the resulting string has a zero length. A program may replace characters within the string. \see \xref[3.3.3.6 Other transient regions]{usage:transient}, \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:WORD}{}. \begin{rationale} % A.6.1.2450 WORD Typical use: \emph{char} \word{WORD} \emph{ccc}\arg{char} \end{rationale} \begin{testing} % T.6.1.2450 WORD \ttfamily \word{:} GS3 \word{WORD} \word{COUNT} \word{SWAP} \word{C@} \word{;} \\ \test{\word{BL} GS3 HELLO}{5 \word{CHAR} H} \\ \test{\word{CHAR} " GS3 GOODBYE"}{7 \word{CHAR} G} \\ \test{BL GS3 \\\mbox{} \word{DROP}}{0} \hfill \word{bs} \textdf{Blank lines return zero-length strings} \end{testing} \end{worddef} \begin{worddef}{2490}{XOR}[x-or] \item \stack{x_1 x_2}{x_3} \param{x_3} is the bit-by-bit exclusive-or of \param{x_1} with \param{x_2}. \begin{testing} % T.6.1.2490 XOR \test{0S 0S \word{XOR}}{0S} \\ \test{0S 1S \word{XOR}}{1S} \\ \test{1S 0S \word{XOR}}{1S} \\ \test{1S 1S \word{XOR}}{0S} \end{testing} \end{worddef} \begin{worddef}{2500}{[}[left-bracket] \interpret Interpretation semantics for this word are undefined. \compile Perform the execution semantics given below. \execute \stack{}{} Enter interpretation state. \word{[} is an immediate word. \see \xref[The Forth text interpreter]{usage:command}, \xref[3.4.5 Compilation]{usage:compilation}, \wref{core:]}{]}, \rref{core:[}{}. \begin{rationale} % A.6.1.2500 [ Typical use: \word{:} \texttt{X} {\ldots} \word{[} \texttt{4321} \word{]} \word{LITERAL} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2500 [ \test{\word{:} GC3 \word{[} GC1 \word{]} \word{LITERAL} \word{;}}{} \\ \test{GC3}{58} \end{testing} \end{worddef} \begin{worddef}{2510}{[']}[bracket-tick] \interpret Interpretation semantics for this word are undefined. \compile \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Find \param{name}. Append the run-time semantics given below to the current definition. An ambiguous condition exists if \param{name} is not found. \runtime \stack{}{xt} Place \param{name}'s execution token \param{xt} on the stack. The execution token returned by the compiled phrase ``\word{[']} \texttt{X}'' is the same value returned by ``\word{'} \texttt{X}'' outside of compilation state. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:FIND}{}, \rref{core:'}{'} \rref{core:POSTPONE}{POSTPONE},\newline \rref{core:[']}{}. \begin{rationale} % A.6.1.2510 ['] Typical use: \word{:} \texttt{X} {\ldots} \word{[']} \emph{name} {\ldots} \word{;} See: \rref{core:FIND}{FIND}. \end{rationale} \begin{testing} % T.6.1.2510 ['] \test{\word{:} GT2 \word{[']} GT1 \word{;} \word{IMMEDIATE}}{} \\ \test{GT2 \word{EXECUTE}}{123} \end{testing} \end{worddef} \begin{worddef}{2520}{[CHAR]}[bracket-char] \interpret Interpretation semantics for this word are undefined. \compile \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Append the run-time semantics given below to the current definition. \runtime \stack{}{char} Place \param{char}, the value of the first character of \param{name}, on the stack. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:CHAR}{CHAR}, \rref{core:[CHAR]}{}. \begin{rationale} % A.6.1.2520 [CHAR] Typical use: \word{:} \texttt{X} {\ldots} \word{[CHAR]} \emph{c} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2520 [CHAR] \test{: GC1 \word{[CHAR]} X ;}{} \\ \test{: GC2 \word{[CHAR]} HELLO ;}{} \\ \test{GC1}{58} \\ \test{GC2}{48} \end{testing} \end{worddef} \begin{worddef}{2540}{]}[right-bracket] \item \stack{}{} Enter compilation state. \see \xref[3.4 The Forth text interpreter]{usage:command}, \xref[3.4.5 Compilation]{usage:compilation}, \wref{core:[}{[}, \rref{core:]}{}. \begin{rationale} % A.6.1.2540 ] Typical use: \word{:} \texttt{X} {\ldots} \word{[} \texttt{4321} \word{]} \word{LITERAL} {\ldots} \word{;} \end{rationale} \begin{testing} % T.6.1.2540 ] See \tref{core:[}{[}. \end{testing} \end{worddef} \section{Core extension words} % 6.2 \extended % Output core-ext rationale to a seperate file \ifanswerfiles \Closesolutionfile{rationale} % \Closesolutionfile{testing} % \Closesolutionfile{implementation} \Opensolutionfile{rationale}[r-core-ext] % \Opensolutionfile{testing}[t-core-ext] % \Opensolutionfile{implementation}[i-core-ext] \fi %\begin{worddef}[numTIB]{0060}{\num{}TIB}[number-t-i-b][x:legacy] %\item \stack{}{a-addr} % % \param{a-addr} is the address of a cell containing the number % of characters in the terminal input buffer. % %\note % This word is obsolescent and is included as a concession to % existing implementations. % % \begin{rationale} % A.6.2.0060 #TIB % The function of \word{numTIB} has been superseded by % \word{SOURCE}. % \end{rationale} %\end{worddef} \enlargethispage{6ex} \begin{worddef}[.p]{0200}{.(}[dot-paren] \compile Perform the execution semantics given below. \execute \stack{"ccc"}{} Parse and display \param{ccc} delimited by \texttt{)} (right parenthesis). \word{.p} is an immediate word. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:.q}{."}, \rref{core:.p}{}. \begin{rationale} % A.6.2.0200 . Typical use: \word{.p} \emph{ccc}\texttt{)} \end{rationale} \end{worddef} \begin{worddef}{0210}{.R}[dot-r] \item \stack{n_1 n_2}{} Display \param{n_1} right aligned in a field \param{n_2} characters wide. If the number of characters required to display \param{n_1} is greater than \param{n_2}, all digits are displayed with no leading spaces in a field as wide as necessary. \see \rref{core:.R}{}. \begin{rationale} % A.6.2.0210 .R In \word{.R}, ``R'' is short for RIGHT. \end{rationale} \end{worddef} \begin{worddef}[0ne]{0260}{0<>}[zero-not-equals] \item \stack{x}{flag} \param{flag} is true if and only if \param{x} is not equal to zero. \end{worddef} \begin{worddef}[0more]{0280}{0>}[zero-greater] \item \stack{n}{flag} \param{flag} is true if and only if \param{n} is greater than zero. \end{worddef} \begin{worddef}[2toR]{0340}{2>R}[two-to-r] \interpret Interpretation semantics for this word are undefined. \execute \stack{x_1 x_2}{} \stack[R]{}{x_1 x_2} Transfer cell pair \param{x_1 x_2} to the return stack. Semantically equivalent to \word{SWAP} \word{toR} \word{toR}. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:toR}{>R}, \wref{core:Rfrom}{R>}, \wref{core:R@}{R@}, \wref{core:2Rfrom}{2R>}, \wref{core:2R@}{2R@}, \rref{core:2toR}{}. \begin{rationale} % A.6.2.0340 2>R The primary advantage of \word{2toR} is that it puts the top stack entry on the top of the return stack. For instance, a double-cell number may be transferred to the return stack and still have the most significant cell accessible on the top of the return stack. \end{rationale} \end{worddef} \begin{worddef}[2Rfrom]{0410}{2R>}[two-r-from] \interpret Interpretation semantics for this word are undefined. \execute \stack{}{x_1 x_2} \stack[R]{x_1 x_2}{} Transfer cell pair \param{x_1 x_2} from the return stack. Semantically equivalent to \word{Rfrom} \word{Rfrom} \word{SWAP}. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:toR}{>R} \wref{core:Rfrom}{R>} \wref{core:R@}{R@} \wref{core:2toR}{2>R}, \wref{core:2R@}{2R@}, \rref{core:2Rfrom}{}. \begin{rationale} % A.6.2.0410 2R> Note that \word{2Rfrom} is not equivalent to \word{Rfrom} \word{Rfrom}. Instead, it mirrors the action of \word{2toR} (see \ref{rat:core:2toR}). \end{rationale} \end{worddef} \pagebreak \begin{worddef}{0415}{2R@}[two-r-fetch] \interpret Interpretation semantics for this word are undefined. \execute \stack{}{x_1 x_2} \stack[R]{x_1 x_2}{x_1 x_2} Copy cell pair \param{x_1 x_2} from the return stack. Semantically equivalent to \word{Rfrom} \word{Rfrom} \word{2DUP} \word{toR} \word{toR} \word{SWAP}. \see \xref[3.2.3.3 Return stack]{usage:returnstack}, \wref{core:toR}{>R}, \wref{core:Rfrom}{R>}, \wref{core:R@}{R@}, \wref{core:2toR}{2>R}, \wref{core:2Rfrom}{2R>}. \end{worddef} \begin{worddef}{0455}{:NONAME}[colon-no-name] \item \stack[C]{}{colon-sys} \stack[S]{}{xt} Create an execution token \param{xt}, enter compilation state and start the current definition, producing \param{colon-sys}. Append the initiation semantics given below to the current definition. The execution semantics of \param{xt} will be determined by the words compiled into the body of the definition. This definition can be executed later by using \param{xt} \word{EXECUTE}. If the control-flow stack is implemented using the data stack, \param{colon-sys} shall be the topmost item on the data stack. See \xref[3.2.3.2 Control-flow stack]{usage:controlstack}. \init \stack{i*x}{i*x} \stack[R]{}{nest-sys} Save implementation-dependent information \param{nest-sys} about the calling definition. The stack effects \param{i*x} represent arguments to \param{xt}. \execute[xt] \stack{i*x}{j*x} Execute the definition specified by \param{xt}. The stack effects \param{i*x} and \param{j*x} represent arguments to and results from \param{xt}, respectively. \see \rref{core::NONAME}{}. \begin{rationale} % A.6.2.0455 :NONAME Typical use: \tab \word{DEFER} \texttt{print} \\[2ex] \tab \word{:NONAME} \word{p} n -{}- ) \word{d} \word{;} \word{IS} \texttt{print} \note \word{RECURSE} and \word{DOES} shall work within a \word{:NONAME} definition. \end{rationale} \begin{testing} \word{VARIABLE} nn1 \\ \word{VARIABLE} nn2 \\ \test{\word{:NONAME} 1234 \word{;} nn1 \word{!}}{} \\ \test{\word{:NONAME} 9876 \word{;} nn2 \word{!}}{} \\ \test{nn1 \word{@} \word{EXECUTE}}{1234} \\ \test{nn2 \word{@} \word{EXECUTE}}{9876} \end{testing} \end{worddef} \begin{worddef}[ne]{0500}{<>}[not-equals] \item \stack{x_1 x_2}{flag} \param{flag} is true if and only if \param{x_1} is not bit-for-bit the same as \param{x_2}. \end{worddef} \begin{worddef}[qDO]{0620}{?DO}[question-do] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{do-sys} Put \param{do-sys} onto the control-flow stack. Append the run-time semantics given below to the current definition. The semantics are incomplete until resolved by a consumer of \emph{do-sys} such as \word{LOOP}. \runtime \stack{n_1|u_1 n_2|u_2}{} \stack[R]{}{loop-sys} If \param{n_1|u_1} is equal to \param{n_2|u_2}, continue execution at the location given by the consumer of \param{do-sys}. Otherwise set up loop control parameters with index \param{n_2|u_2} and limit \param{n_1|u_1} and continue executing immediately following \word{qDO}. Anything already on the return stack becomes unavailable until the loop control parameters are discarded. An ambiguous condition exists if \param{n_1|u_1} and \param{n_2|u_2} are not both of the same type. \see \xref[3.2.3.2 Control-flow stack]{usage:controlstack}, \wref{core:+LOOP}{+LOOP}, \wref{core:DO}{DO}, \wref{core:I}{I}, \\ \wref{core:LEAVE}{LEAVE}, \wref{core:LOOP}{LOOP}, \wref{core:UNLOOP}{UNLOOP}, \rref{core:qDO}{}. \begin{rationale} % A.6.2.0620 ?DO Typical use: \tab \word{:} \texttt{X} {\ldots} \word{qDO} {\ldots} \word{LOOP} {\ldots} \word{;} \end{rationale} \begin{testing}\ttfamily \word{DECIMAL} \word{:} qd \word{qDO} \word{I} \word{LOOP} \word{;} \\ \test{ 789 789 qd}{} \\ \test{-9876 -9876 qd}{} \\ \test{ 5 0 qd}{0 1 2 3 4} \word{:} qd1 \word{qDO} \word{I} 10 \word{+LOOP} \word{;} \\ \test{50 1 qd1}{1 11 21 31 41} \\ \test{50 0 qd1}{0 10 20 30 40} \word{:} qd2 \word{qDO} \word{I} 3 \word{more} \word{IF} \word{LEAVE} \word{ELSE} \word{I} \word{THEN} \word{LOOP} \word{;} \\ \test{5 -1 qd2}{-1 0 1 2 3} \word{:} qd3 \word{qDO} \word{I} 1 \word{+LOOP} \word{;} \\ \test{4 4 qd3}{} \\ \test{4 1 qd3}{ 1 2 3} \\ \test{2 -1 qd3}{-1 0 1} \word{:} qd4 \word{qDO} \word{I} -1 \word{+LOOP} \word{;} \\ \test{ 4 4 qd4}{} \\ \test{ 1 4 qd4}{4 3 2 1} \\ \test{-1 2 qd4}{2 1 0 -1} \word{:} qd5 \word{qDO} \word{I} -10 \word{+LOOP} \word{;} \\ \test{ 1 50 qd5}{50 40 30 20 10 } \\ \test{ 0 50 qd5}{50 40 30 20 10 0} \\ \test{-25 10 qd5}{10 0 -10 -20 } \word{VARIABLE} qditerations \\ \word{VARIABLE} qdincrement \word{:} qd6 \word{p} limit start increment -{}- ) \tab qdincrement \word{!} \\ \tab 0 qditerations \word{!} \\ \tab \word{qDO} \\ \tab[2] 1 qditerations \word{+!} \\ \tab[2] \word{I} \\ \tab[2] qditerations \word{@} 6 \word{=} \word{IF} \word{LEAVE} \word{THEN} \\ \tab[2] qdincrement \word{@} \\ \tab \word{+LOOP} qditerations \word{@} \\ \word{;} \test{ 4 4 -1 qd6}{ 0 } \\ \test{ 1 4 -1 qd6}{ 4 3 2 1 4 } \\ \test{ 4 1 -1 qd6}{ 1 0 -1 -2 -3 -4 6 } \\ \test{ 4 1 0 qd6}{ 1 1 1 1 1 1 6 } \\ \test{ 0 0 0 qd6}{ 0 } \\ \test{ 1 4 0 qd6}{ 4 4 4 4 4 4 6 } \\ \test{ 1 4 1 qd6}{ 4 5 6 7 8 9 6 } \\ \test{ 4 1 1 qd6}{ 1 2 3 3 } \\ \test{ 4 4 1 qd6}{ 0 } \\ \test{ 2 -1 -1 qd6}{-1 -2 -3 -4 -5 -6 6 } \\ \test{-1 2 -1 qd6}{ 2 1 0 -1 4 } \\ \test{ 2 -1 0 qd6}{-1 -1 -1 -1 -1 -1 6 } \\ \test{-1 2 0 qd6}{ 2 2 2 2 2 2 6 } \\ \test{-1 2 1 qd6}{ 2 3 4 5 6 7 6 } \\ \test{ 2 -1 1 qd6}{-1 0 1 3 } \end{testing} \end{worddef} \begin{worddef}{0698}{ACTION-OF}[][X:deferred] \interpret \stack{"name"}{xt} Skip leading spaces and parse \param{name} delimited by a space. \param{xt} is the execution token that \param{name} is set to execute. An ambiguous condition exists if \param{name} was not defined by \word{DEFER}, or if the \param{name} has not been set to execute an \param{xt}. \compile \stack{"name"}{} Skip leading spaces and parse \param{name} delimited by a space. Append the run-time semantics given below to the current definition. An ambiguous condition exists if \param{name} was not defined by \word{DEFER}. \runtime \stack{}{xt} \param{xt} is the execution token that \param{name} is set to execute. An ambiguous condition exists if \param{name} has not been set to execute an \param{xt}. An ambiguous condition exists if \word{POSTPONE}, \word{[COMPILE]}, \word{[']} or \word{'} is applied to \word{ACTION-OF}. \see \wref{core:DEFER}{DEFER}, \wref{core:DEFER!}{DEFER!}, \wref{core:DEFER@}{DEFER@}, \wref{core:IS}{IS}. \begin{implement} % I.6.2.---- ACTION-OF \word{:} \word{ACTION-OF} \\ \tab \word{STATE} \word{@} \word{IF} \\ \tab[2] \word{POSTPONE} \word{[']} \word{POSTPONE} \word{DEFER@} \\ \tab \word{ELSE} \\ \tab[2] \word{'} \word{DEFER@} \\ \tab \word{THEN} \word{;} \word{IMMEDIATE} \end{implement} \begin{testing} % T.6.2.---- ACTION-OF \test{\word{DEFER} defer1}{} \\ \test{\word{:} action-defer1 \word{ACTION-OF} defer1 \word{;}}{} \test{\word{'} \word{*} \word{'} defer1 \word{DEFER!}}{ } \\ \test{ 2 3 defer1}{6} \\ \test{\word{ACTION-OF} defer1}{\word{'} \word{*}} \\ \test{ action-defer1}{\word{'} \word{*}} \test{\word{'} \word{+} \word{IS} defer1}{ } \\ \test{ 1 2 defer1}{3} \\ \test{\word{ACTION-OF} defer1}{\word{'} \word{+}} \\ \test{ action-defer1}{\word{'} \word{+}} \end{testing} \end{worddef} \begin{worddef}{0700}{AGAIN} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{dest}{} Append the run-time semantics given below to the current definition, resolving the backward reference \param{dest}. \runtime \stack{}{} Continue execution at the location specified by \param{dest}. If no other control flow words are used, any program code after \word{AGAIN} will not be executed. \see \wref{core:BEGIN}{BEGIN}, \rref{core:AGAIN}{}. \begin{rationale} % A.6.2.0700 AGAIN Typical use: \word{:} \texttt{X} {\ldots} \word{BEGIN} {\ldots} \word{AGAIN} {\ldots} \word{;} Unless word-sequence has a way to terminate, this is an endless loop. \end{rationale} \end{worddef} % ------------------------------------------------------------------- \enlargethispage{6ex} \begin{worddef}{0825}{BUFFER:}[buffer-colon][x:buffer] \item \stack{u "name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name}, with the execution semantics defined below. Reserve \param{u} address units at an aligned address. Contiguity of this region with any other region is undefined. \execute[name] \stack{}{a-addr} \param{a-addr} is the address of the space reserved by \word{BUFFER:} when it defined \param{name}. The program is responsible for initializing the contents. \see \rref{core:BUFFER:}{}. \begin{rationale} \word{BUFFER:} provides a means of defining an uninitialized buffer. In systems that use a single memory space, this can effectively be defined as: \begin{quote}\ttfamily \word{:} \word{BUFFER:} \word{p} u "" -{}- ; -{}- addr ) \\ \tab\,\word{CREATE} \word{ALLOT} \\ \word{;} \end{quote} However, many systems profit from a separation of uninitialized and initialized data areas. Such systems can implement \word{BUFFER:} so that it allocates memory from a separate uninitialized memory area. Embedded systems can take advantage of the lack of initialization of the memory area while hosted systems are permitted to \word[memory]{ALLOCATE} a buffer. A system may select a region of memory for performance reasons. A detailed knowledge of the memory allocation within the system is required to provide a version of \word{BUFFER:} that can take advantage of the system. It should be noted that the memory buffer provided by \word{BUFFER:} is not initialized by the system and that if the application requires it to be initialized, it is the responsibility of the application to initialize it. \end{rationale} \begin{implement} \dffamily This implementation depends on children of \word{CREATE} returning an aligned address. Other memory location techniques require implementation-specific knowledge of the underlying Forth system. \ttfamily \word{:} \word{BUFFER:} \word{bs} u "" -- ; -- addr \\ \word{bs} \textdf{Create a buffer of u address units whose address is returned at run time.} \\ \tab \word{CREATE} \word{ALLOT} \\ \word{;} \end{implement} \begin{testing} \ttfamily \word{DECIMAL} \\ \test{127 \word{CHARS} \word{BUFFER:} TBUF1}{} \\ \test{127 \word{CHARS} \word{BUFFER:} TBUF2}{} \word{bs} \textdf{Buffer is aligned} \\ \test{TBUF1 \word{ALIGNED}}{TBUF1} \word{bs} \textdf{Buffers do not overlap} \\ \test{TBUF2 TBUF1 \word{-} \word{ABS} 127 \word{CHARS} \word{less}}{} \word{bs} \textdf{Buffer can be written to} \\ 1 \word{CHARS} \word{CONSTANT} /CHAR \\ \word{:} TFULL? \word{p} c-addr n char -{}- flag )\\ \tab\,\word{TRUE} \word{2SWAP} \word{CHARS} \word{OVER} \word{+} \word{SWAP} \word{qDO} \\ \tab[2] \word{OVER} \word{I} \word{C@} \word{=} \word{AND} \\ \tab\,/CHAR \word{+LOOP} \word{NIP} \\ \word{;} \test{TBUF1 127 \word{CHAR} * \word{FILL} }{ } \\ \test{TBUF1 127 \word{CHAR} * TFULL?}{} \test{TBUF1 127 0 \word{FILL} }{ } \\ \test{TBUF1 127 0 TFULL?}{} \end{testing} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}[Cq]{0855}{C"}[c-quote] \interpret Interpretation semantics for this word are undefined. \compile \stack{"ccc"}{} Parse \param{ccc} delimited by \texttt{"} (double-quote) and append the run-time semantics given below to the current definition. \runtime \stack{}{c-addr} Return \param{c-addr}, a counted string consisting of the characters \param{ccc}. A program shall not alter the returned string. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:Sq}{S"}, \wref{file:Sq}{S"}, \rref{core:Cq}{}. \begin{rationale} % A.6.2.0855 C" Typical use: \word{:} \texttt{X} {\ldots} \word{Cq} \emph{ccc}\texttt{"} {\ldots} \word{;} See: \xref[A.3.1.3.4 Counted strings]{rat:cstring}. \end{rationale} \begin{testing} \test{\word{:} cq1 \word{Cq} 123\texttt{"} \word{;}}{} \\ \test{\word{:} cq2 \word{Cq} \texttt{"} \word{;} }{} \\ \test{cq1 \word{COUNT} \word{EVALUATE}}{123} \\ \test{cq2 \word{COUNT} \word{EVALUATE}}{ } \end{testing} \end{worddef} \begin{worddef}{0873}{CASE} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{case-sys} Mark the start of the \word{CASE}\ldots\word{OF}\ldots\word{ENDOF}\ldots\word{ENDCASE} structure. Append the run-time semantics given below to the current definition. \runtime \stack{}{} Continue execution. \see \wref{core:ENDCASE}{ENDCASE}, \wref{core:ENDOF}{ENDOF}, \wref{core:OF}{OF}, \rref{core:CASE}{}. \begin{rationale} % A.6.2.0873 CASE Typical use: \begin{quote} \word{:} \texttt{X} {\ldots} \\ \tab \word{CASE} \\ \tab~~ \emph{test1} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ \emph{testn} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ {\ldots} \word{p} default ) \\ \tab \word{ENDCASE} {\ldots} \\ \word{;} \end{quote} \end{rationale} \begin{testing}\ttfamily \word{:} cs1 \word{CASE} 1 \word{OF} 111 \word{ENDOF} \\ \tab 2 \word{OF} 222 \word{ENDOF} \\ \tab 3 \word{OF} 333 \word{ENDOF} \\ \tab \word{toR} 999 \word{Rfrom} \\ \tab \word{ENDCASE} \\ \word{;} \test{1 cs1}{111} \\ \test{2 cs1}{222} \\ \test{3 cs1}{333} \\ \test{4 cs1}{999} \\ \word{:} cs2 \word{toR} \word{CASE} \\ \tab -1 \word{OF} \word{CASE} \word{R@} 1 \word{OF} 100 \word{ENDOF} \\ \tab[7.3] 2 \word{OF} 200 \word{ENDOF} \\ \tab[7.3] \word{toR} -300 \word{Rfrom} \\ \tab[3.5] \word{ENDCASE} \\ \tab[2] \word{ENDOF} \\ \tab -2 \word{OF} \word{CASE} \word{R@} 1 \word{OF} -99 \word{ENDOF} \\ \tab[7.3] \word{toR} -199 \word{Rfrom} \\ \tab[3.5] \word{ENDCASE} \\ \tab[2] \word{ENDOF} \\ \tab[2] \word{toR} 299 \word{Rfrom} \\ \tab \word{ENDCASE} \word{Rfrom} \word{DROP} \word{;} \test{-1 1 cs2}{ 100} \\ \test{-1 2 cs2}{ 200} \\ \test{-1 3 cs2}{-300} \\ \test{-2 1 cs2}{ -99} \\ \test{-2 2 cs2}{-199} \\ \test{ 0 2 cs2}{ 299} \end{testing} \end{worddef} \pagebreak \begin{worddef}{0945}{COMPILE,}[compile-comma] \interpret Interpretation semantics for this word are undefined. \execute \stack{xt}{} Append the execution semantics of the definition represented by \param{xt} to the execution semantics of the current definition. \see \rref{core:COMPILE,}{}. \begin{rationale} % A.6.2.0945 COMPILE, \word{COMPILE,} is the compilation equivalent of \word{EXECUTE}. In traditional threaded-code implementations, compilation is performed by \word{,} (comma). This usage is not portable; it doesn't work for subroutine-threaded, native code, or relocatable implementations. Use of \word{COMPILE,} is portable. In most systems it is possible to implement \word{COMPILE,} so it will generate code that is optimized to the same extent as code that is generated by the normal compilation process. However, in some implementations there are two different ``tokens'' corresponding to a particular definition name: the normal ``execution token'' that is used while interpreting or with \word{EXECUTE}, and another ``compilation token'' that is used while compiling. It is not always possible to obtain the compilation token from the execution token. In these implementations, \word{COMPILE,} might not generate code that is as efficient as normally compiled code. The intention is that \word{COMPILE,} can be used as follows to write the classic interpreter/com\-piler loop: \begin{quote}\ttfamily \ldots \tab[22] \word{p} c-addr ) \\ \word{FIND} \word{qDUP} \word{IF} \tab[17.2] \word{p} xt +-1 ) \\ \tab \word{STATE} \word{@} \word{IF} \tab[17.4] \word{p} xt +-1 ) \\ \tab[2] \word{0more} \word{IF} \ \word{EXECUTE} \ \word{ELSE} \ \word{COMPILE,} \ \word{THEN} \tab[0.2] \word{p} ??? ) \\ \tab \word{ELSE} \tab[21] \word{p} xt +-1 ) \\ \tab[2] \word{DROP} \word{EXECUTE} \tab[14.6] \word{p} ??? ) \\ \tab \word{THEN} \\ \word{ELSE} \tab[22] \word{p} c-addr ) \\ \tab \word{p} \textrm{whatever you do for an undefined word} ) \\ \word{THEN} \\ \ldots \end{quote} Thus the interpretation semantics are left undefined, as \word{COMPILE,} will not be executed during interpretation. \end{rationale} \begin{testing}\ttfamily \word{:NONAME} \word{DUP} \word{+} \word{;} \word{CONSTANT} dup+ \\ \test{\word{:} q dup+ \word{COMPILE,} \word{;}}{} \\ \test{\word{:} as \word{[} q \word{]} \word{;}}{} \\ \test{123 as}{246} \end{testing} \end{worddef} %\begin{worddef}{0970}{CONVERT}[][x:legacy] %\item \stack{ud_1 c-addr_1}{ud_2 c-addr_2} % % \param{ud_2} is the result of converting the characters within % the text beginning at the first character after \param{c-addr_1} % into digits, using the number in \word{BASE}, and adding each % digit to \param{ud_1} after multiplying \param{ud_1} by the % number in \word{BASE}. Conversion continues until a character % that is not convertible is encountered. \param{c-addr_2} is % the location of the first unconverted character. An ambiguous % condition exists if \param{ud_2} overflows. % %\note % This word is obsolescent and is included as a concession to % existing implementations. Its function is superseded by % \wref{core:toNUMBER}{>NUMBER}. % %\see \xref[3.2.1.2 Digit conversion]{usage:digits}. % % \begin{rationale} % A.6.2.0970 CONVERT % \word{CONVERT} may be defined as follows: % % \tab \word{:} \word{CONVERT}~ % \word{CHAR+} \texttt{65535} \word{toNUMBER} \word{DROP} % \word{;} % \end{rationale} %\end{worddef} \begin{worddef}{1173}{DEFER}[][X:deferred] \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below. \execute[name] \stack{i*x}{j*x} Execute the \param{xt} that \param{name} is set to execute. An ambiguous condition exists if \param{name} has not been set to execute an \param{xt}. \see \wref{core:ACTION-OF}{ACTION-OF}, \wref{core:DEFER!}{DEFER!}, \wref{core:DEFER@}{DEFER@}, \wref{core:IS}{IS}. \begin{implement} % I.6.2.---- DEFER \word{:} \word{DEFER} \word{p} "name" -{}- ) \\ \tab \word{CREATE} \word{[']} \word{ABORT} \word{,} \\ \word{DOES} \word{p} {\ldots} -{}- {\ldots} ) \\ \tab \word{@} \word{EXECUTE} \word{;} \end{implement} \begin{testing} % T 6.2.---- DEFER \test{\word{DEFER} defer2}{ } \\ \test{\word{'} \word{*} \word{'} defer2 \word{DEFER!}}{} \\ \test{ 2 3 defer2}{6} \test{\word{'} \word{+} \word{IS} defer2}{ } \\ \test{ 1 2 defer2}{3} \end{testing} \end{worddef} \begin{worddef}{1175}{DEFER!}[defer-store][X:deferred] \item \stack{xt_2 xt_1}{} Set the word \param{xt_1} to execute \param{xt_2}. An ambiguous condition exists if \param{xt_1} is not for a word defined by \word{DEFER}. \see \wref{core:ACTION-OF}{ACTION-OF}, \wref{core:DEFER}{DEFER}, \wref{core:DEFER@}{DEFER@}, \wref{core:IS}{IS}. \begin{implement} % I.6.2.---- DEFER! \word{:} \word{DEFER!} \word{p} xt2 xt1 -{}- ) \\ \tab \word{toBODY} \word{!} \word{;} \end{implement} \begin{testing} % T.6.2.---- DEFER! \test{\word{DEFER} defer3}{} \test{\word{'} \word{*} \word{'} defer3 \word{DEFER!}}{} \\ \test{2 3 defer3}{6} \test{\word{'} \word{+} \word{'} defer3 \word{DEFER!}}{} \\ \test{1 2 defer3}{3} \end{testing} \end{worddef} \begin{worddef}{1177}{DEFER@}[defer-fetch][X:deferred] \item \stack{xt_1}{xt_2} \param{xt_2} is the execution token \param{xt_1} is set to execute. An ambiguous condition exists if \param{xt_1} is not the execution token of a word defined by \word{DEFER}, or if \param{xt_1} has not been set to execute an xt. \see \wref{core:ACTION-OF}{ACTION-OF}, \wref{core:DEFER}{DEFER}, \wref{core:DEFER!}{DEFER!}, \wref{core:IS}{IS}. \begin{implement} % I.6.2.---- DEFER@ \word{:} \word{DEFER@} \word{p} xt1 -{}- xt2 ) \\ \tab \word{toBODY} \word{@} \word{;} \end{implement} \begin{testing} % T.6.2.---- DEFER@ \test{\word{DEFER} defer4}{} \test{\word{'} \word{*} \word{'} defer4 \word{DEFER!}}{} \\ \test{2 3 defer4}{6} \\ \test{\word{'} defer4 \word{DEFER@}}{\word{'} \word{*}} \test{\word{'} \word{+} \word{IS} defer4}{} \\ \test{1 2 defer4}{3} \\ \test{\word{'} defer4 \word{DEFER@}}{\word{'} \word{+}} \end{testing} \end{worddef} \pagebreak \begin{worddef}{1342}{ENDCASE}[end-case] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{case-sys}{} Mark the end of the \word{CASE}\ldots\word{OF}\ldots\word{ENDOF}\ldots\word{ENDCASE} structure. Use \param{case-sys} to resolve the entire structure. Append the run-time semantics given below to the current definition. \runtime \stack{x}{} Discard the case selector \param{x} and continue execution. \see \wref{core:CASE}{CASE}, \wref{core:ENDOF}{ENDOF}, \wref{core:OF}{OF}, \rref{core:ENDCASE}{}. \begin{rationale} % A.6.2.1342 ENDCASE Typical use: \begin{quote} \word{:} \texttt{X} {\ldots} \\ \tab \word{CASE} \\ \tab~~ \emph{test1} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ \emph{testn} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ {\ldots} \word{p} default ) \\ \tab \word{ENDCASE} {\ldots} \\ \word{;} \end{quote} \end{rationale} \begin{testing} See \tref{core:CASE}{}. \end{testing} \end{worddef} \begin{worddef}{1343}{ENDOF}[end-of] \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{case-sys_1 of-sys}{case-sys_2} Mark the end of the \word{OF}\ldots\word{ENDOF} part of the \word{CASE} structure. The next location for a transfer of control resolves the reference given by \param{of-sys}. Append the run-time semantics given below to the current definition. Replace \param{case-sys_1} with \param{case-sys_2} on the control-flow stack, to be resolved by \word{ENDCASE}. \runtime \stack{}{} Continue execution at the location specified by the consumer of \param{case-sys_2}. \see \wref{core:CASE}{CASE}, \wref{core:ENDCASE}{ENDCASE}, \wref{core:OF}{OF}, \rref{core:ENDOF}{}. \begin{rationale} % A.6.2.1343 ENDOF Typical use: \begin{quote} \word{:} \texttt{X} {\ldots} \\ \tab \word{CASE} \\ \tab~~ \emph{test1} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ \emph{testn} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ {\ldots} \word{p} default ) \\ \tab \word{ENDCASE} {\ldots} \\ \word{;} \end{quote} \end{rationale} \begin{testing} See \tref{core:CASE}{}. \end{testing} \end{worddef} \begin{worddef}{1350}{ERASE} \item \stack{addr u}{} If \param{u} is greater than zero, clear all bits in each of \param{u} consecutive address units of memory beginning at \param{addr}. \end{worddef} %\begin{worddef}{1390}{EXPECT}[][x:legacy] %\item \stack{c-addr +n}{} % % Receive a string of at most \param{+n} characters. Display graphic % characters as they are received. A program that depends on % the presence or absence of non-graphic characters in the % string has an environmental dependency. The editing functions, % if any, that the system performs in order to construct the % string of characters are implementation-defined. % % Input terminates when an implementation-defined line terminator % is received or when the string is \param{+n} characters long. When % input terminates, nothing is appended to the string and the % display is maintained in an implementation-defined way. % % Store the string at \param{c-addr} and its length in \word{SPAN}. % %\note % This word is obsolescent and is included as a concession to % existing implementations. Its function is superseded % by \wref{core:ACCEPT}{ACCEPT}. % % \begin{rationale} % A.6.2.1390 EXPECT % Specification of positive integer counts (\param{+n}) for % \word{EXPECT} allows some implementors to continue their % practice of using a zero or negative value as a flag to % trigger special behavior. Insofar as such behavior is outside % the Standard, Standard Programs cannot depend upon it, but % the Technical Committee doesn't wish to preclude it % unnecessarily. Since actual values are almost always small % integers, no functionality is impaired by this restriction. % \end{rationale} %\end{worddef} \begin{worddef}{1485}{FALSE} \item \stack{}{false} Return a \param{false} flag. \see \xref[3.1.3.1 Flags]{usage:flags} \begin{testing} \test{\word{FALSE}}{0} \\ \test{\word{FALSE}}{} \end{testing} \end{worddef} \begin{worddef}{1660}{HEX} \item \stack{}{} Set contents of \word{BASE} to sixteen. \begin{testing} % T.6.2.1660 HEX See \tref{core:BASE}{BASE}. \end{testing} \end{worddef} % =================================================================== \begin{worddef}{1675}{HOLDS}[][x:xchar] \item \stack{c-addr u}{} Adds the string represented by \param{c-addr u} to the pictured numeric output string. An ambiguous condition exists if \word{HOLDS} executes outside of a \word{num-start} \word{num-end} delimited number conversion. \see \wref{core:HOLD}{}. \begin{implement} \word{:} \word{HOLDS} \word{p} addr u -{}- ) \\ \tab[0.6] \word{BEGIN} \word{DUP} \word{WHILE} \word{1-} \word{2DUP} \word{+} \word{C@} \word{HOLD} \word{REPEAT} \word{2DROP} \word{;} \end{implement} \begin{testing} \test{0. \word{num-start} \word[file]{Sq} Test" \word{HOLDS} \word{num-end} \word[file]{Sq} Test" \word[string]{COMPARE}}{0} \end{testing} \end{worddef} % =================================================================== \enlargethispage{2ex} \begin{worddef}{1725}{IS}[][X:deferred] \interpret \stack{xt "name"}{} Skip leading spaces and parse \param{name} delimited by a space. Set \param{name} to execute \param{xt}. An ambiguous condition exists if \param{name} was not defined by \word{DEFER}. \compile \stack{"name"}{} Skip leading spaces and parse \param{name} delimited by a space. Append the run-time semantics given below to the current definition. An ambiguous condition exists if \param{name} was not defined by \word{DEFER}. \runtime \stack{xt}{} Set \param{name} to execute \param{xt}. An ambiguous condition exists if \word{POSTPONE}, \word{[COMPILE]}, \word{[']} or \word{'} is applied to \word{IS}. \see \wref{core:ACTION-OF}{ACTION-OF}, \wref{core:DEFER}{DEFER}, \wref{core:DEFER!}{DEFER!}, \wref{core:DEFER@}{DEFER@}. \begin{implement} % I.6.2.---- IS \word{:} \word{IS} \\ \tab \word{STATE} \word{@} \word{IF} \\ \tab[2] \word{POSTPONE} \word{[']} \word{POSTPONE} \word{DEFER!} \\ \tab \word{ELSE} \\ \tab[2] \word{'} \word{DEFER!} \\ \tab \word{THEN} \word{;} \word{IMMEDIATE} \end{implement} \begin{testing} % T.6.2.---- IS \test{\word{DEFER} defer5}{} \\ \test{\word{:} is-defer5 \word{IS} defer5 \word{;}}{} \test{\word{'} \word{*} \word{IS} defer5}{} \\ \test{2 3 defer5}{6} \test{\word{'} \word{+} is-defer5}{} \\ \test{1 2 defer5}{3} \end{testing} \end{worddef} \begin{worddef}{1850}{MARKER} \item \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below. \execute[name] \stack{}{} Restore all dictionary allocation and search order pointers to the state they had just prior to the definition of \param{name}. Remove the definition of \param{name} and all subsequent definitions. Restoration of any structures still existing that could refer to deleted definitions or deallocated data space is not necessarily provided. No other contextual information such as numeric base is affected. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{tools:FORGET}{FORGET}, \rref{core:MARKER}{}. \begin{rationale} % A.6.2.1850 MARKER As dictionary implementations have become more elaborate and in some cases have used multiple address spaces, \word[tools]{FORGET} has become prohibitively difficult or impossible to implement on many Forth systems. \word{MARKER} greatly eases the problem by making it possible for the system to remember ``landmark information'' in advance that specifically marks the spots where the dictionary may at some future time have to be rearranged. \pagebreak \end{rationale} \end{worddef} \begin{worddef}{1930}{NIP} \item \stack{x_1 x_2}{x_2} Drop the first item below the top of stack. \end{worddef} \begin{worddef}{1950}{OF} \interpret Interpretation semantics for this word are undefined. \compile \stack[C]{}{of-sys} Put \param{of-sys} onto the control flow stack. Append the run-time semantics given below to the current definition. The semantics are incomplete until resolved by a consumer of \param{of-sys} such as \word{ENDOF}. \runtime \stack{x_1 x_2}{x_1} If the two values on the stack are not equal, discard the top value and continue execution at the location specified by the consumer of \param{of-sys}, e.g., following the next \word{ENDOF}. Otherwise, discard both values and continue execution in line. \see \wref{core:CASE}{CASE}, \wref{core:ENDCASE}{ENDCASE}, \wref{core:ENDOF}{ENDOF}, \rref{core:OF}{}. \begin{rationale} % A.6.2.1950 OF Typical use: \begin{quote} \word{:} \texttt{X} {\ldots} \\ \tab \word{CASE} \\ \tab~~ \emph{test1} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ \emph{testn} \word{OF} {\ldots} \word{ENDOF} \\ \tab~~ {\ldots} \word{p} default ) \\ \tab \word{ENDCASE} {\ldots} \\ \word{;} \end{quote} \end{rationale} \begin{testing} See \tref{core:CASE}{}. \end{testing} \end{worddef} \begin{worddef}{2000}{PAD} \item \stack{}{c-addr} \param{c-addr} is the address of a transient region that can be used to hold data for intermediate processing. \see \xref[3.3.3.6 Other transient regions]{usage:transient}, \rref{core:PAD}{}. \begin{rationale} % A.6.2.2000 PAD \word{PAD} has been available as scratch storage for strings since the earliest Forth implementations. It was brought to our attention that many programmers are reluctant to use \word{PAD}, fearing incompatibilities with system uses. \word{PAD} is specifically intended as a programmer convenience, however, which is why we documented the fact that no standard words use it. \end{rationale} \end{worddef} \begin{worddef}{2008}{PARSE} \item \stack{char "ccc"}{c-addr u} Parse \param{ccc} delimited by the delimiter \param{char}. \param{c-addr} is the address (within the input buffer) and \param{u} is the length of the parsed string. If the parse area was empty, the resulting string has a zero length. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:PARSE}{}. \begin{rationale} % A.6.2.2008 PARSE Typical use: \emph{char} \word{PARSE} \emph{ccc}\arg{char} The traditional Forth word for parsing is \word{WORD}. \word{PARSE} solves the following problems with \word{WORD}: \begin{enumerate} \item \word{WORD} always skips leading delimiters. This behavior is appropriate for use by the text interpreter, which looks for sequences of non-blank characters, but is inappropriate for use by words like \word{p} , \word{.p}, and \word{.q}. Consider the following (flawed) definition of \word{.p}: \tab \word{:} \word{.p} ~ \word{[CHAR]} \texttt{)} ~ \word{WORD} \word{COUNT} \word{TYPE} \word{;} ~ \word{IMMEDIATE} This works fine when used in a line like: \tab \word{.p} \texttt{HELLO)} \quad \texttt{5} \word{d} but consider what happens if the user enters an empty string: \tab \word{.p} \texttt{)} \quad \texttt{5} \word{d} The definition of \word{.p} shown above would treat the \texttt{)} as a leading delimiter, skip it, and continue consuming characters until it located another \texttt{)} that followed a non-\texttt{)} character, or until the parse area was empty. In the example shown, the \texttt{5} \word{d} would be treated as part of the string to be printed. With \word{PARSE}, we could write a correct definition of \word{.p}: \tab \word{:} \word{.p} ~ \word{[CHAR]} \texttt{)} ~ \word{PARSE} \word{TYPE} \word{;} ~ \word{IMMEDIATE} This definition avoids the ``empty string'' anomaly. \item \word{WORD} returns its result as a counted string. This has four bad effects: \begin{enumerate} \item The characters accepted by \word{WORD} must be copied from the input buffer into a temporary buffer, in order to make room for the count character that must be at the beginning of the counted string. The copy step is inefficient, compared to \word{PARSE}, which leaves the string in the input buffer and doesn't need to copy it anywhere. \item \word{WORD} must be careful not to store too many characters into the temporary buffer, thus overwriting something beyond the end of the buffer. This adds to the overhead of the copy step. (\word{WORD} may have to scan a lot of characters before finding the trailing delimiter.) \item The count character limits the length of the string returned by \word{WORD} to 255 characters (longer strings can easily be stored in blocks!). This limitation does not exist for \word{PARSE}. \item The temporary buffer is typically overwritten by the next use of \word{WORD}. \end{enumerate} The need for \word{WORD} has largely been eliminated by \word{PARSE} and \word{PARSE-NAME}. \word{WORD} is retained for backward compatibility. \end{enumerate} \end{rationale} \end{worddef} \begin{worddef}{2020}{PARSE-NAME}[][X:parse-name] \item \stack{"name"}{c-addr u} Skip leading space delimiters. Parse \param{name} delimited by a space. \param{c-addr} is the address of the selected string within the input buffer and \param{u} is its length in characters. If the parse area is empty or contains only white space, the resulting string has length zero. \begin{implement} % I.6.2.---- PARSE-NAME \word{:} isspace? \word{p} c -{}- f ) \\ \tab \word{BL} \word{1+} \word{Uless} \word{;} \word{:} isnotspace? \word{p} c -{}- f ) \\ \tab isspace? \word{0=} \word{;} \word{:} xt-skip \word{p} addr1 n1 xt -{}- addr2 n2 ) \\ \tab \word{bs} skip all characters satisfying xt ( c -{}- f ) \\ \tab \word{toR} \\ \tab \word{BEGIN} \\ \tab[2] \word{DUP} \\ \tab \word{WHILE} \\ \tab[2] \word{OVER} \word{C@} \word{R@} \word{EXECUTE} \\ \tab \word{WHILE} \\ \tab[2] 1 \word[string]{/STRING} \\ \tab \word{REPEAT} \word{THEN} \\ \tab \word{Rfrom} \word{DROP} \word{;} \word{:} parse-name \word{p} "name" -{}- c-addr u ) \\ \tab \word{SOURCE} \word{toIN} \word{@} \word[string]{/STRING} \\ \tab \word{[']} isspace? xt-skip \word{OVER} \word{toR} \\ \tab \word{[']} isnotspace? xt-skip \word{p} end-word restlen r: start-word ) \\ \tab \word{2DUP} 1 \word{MIN} \word{+} \word{SOURCE} \word{DROP} \word{-} \word{toIN} \word{!} \\ \tab \word{DROP} \word{Rfrom} \word{TUCK} \word{-} \word{;} \end{implement} \begin{testing} % T.6.2.---- PARSE-NAME \test{\word{PARSE-NAME} abcd \word{Sq} abcd" S=}{} \\ \test{\word{PARSE-NAME} abcde \word{Sq} abcde" S=}{} \word{bs} test empty parse area \\ \test{\word{PARSE-NAME} \\\mbox{} \tab[0.6] \word{NIP}}{0} \tab \word{bs} empty line \\ \test{PARSE-NAME \\\mbox{} \tab[0.6] \word{NIP}}{0} \tab \word{bs} line with white space \test{\word{:} parse-name-test \word{p} ``name1'' ``name2'' -{}- n ) \\ \tab[0.6] \word{PARSE-NAME} \word{PARSE-NAME} S= \word{;}}{} \test{parse-name-test abcd abcd}{} \\ \test{parse-name-test abcd abcd }{} \\ \test{parse-name-test abcde abcdf}{} \\ \test{parse-name-test abcdf abcde}{} \\ \test{parse-name-test abcde abcde \\\tab[1.2]}{} \\ \test{parse-name-test abcde abcde \\\tab[1.2]}{} \tab \word{bs} line with white space \end{testing} \end{worddef} \begin{worddef}{2030}{PICK} \item \stack{x_u{\ldots}x_1 x_0 u}{x_u{\ldots}x_1 x_0 x_u} Remove \param{u}. Copy the \param{x_u} to the top of the stack. An ambiguous condition exists if there are less than \param{u}+2 items on the stack before \word{PICK} is executed. \see \rref{core:PICK}{}. \begin{rationale} % A.6.2.2030 PICK \texttt{0} \word{PICK} is equivalent to \word{DUP} and \texttt{1} \word{PICK} is equivalent to \word{OVER}. \end{rationale} \end{worddef} %\begin{worddef}{2040}{QUERY}[][x:legacy] %\item \stack{}{} % % Make the user input device the input source. Receive input into % the terminal input buffer, replacing any previous contents. Make % the result, whose address is returned by \word{TIB}, the input % buffer. Set \word{toIN} to zero. % %\note % This word is obsolescent and is included as a concession to % existing implementations. % % \begin{rationale} % A.6.2.2040 QUERY % The function of \word{QUERY} may be performed with \word{ACCEPT} % and \word{EVALUATE}. % \end{rationale} %\end{worddef} \begin{worddef}{2125}{REFILL} \item \stack{}{flag} Attempt to fill the input buffer from the input source, returning a true flag if successful. When the input source is the user input device, attempt to receive input into the terminal input buffer. If successful, make the result the input buffer, set \word{toIN} to zero, and return \emph{true}. Receipt of a line containing no characters is considered successful. If there is no input available from the current input source, return \emph{false}. When the input source is a string from \word{EVALUATE}, return \emph{false} and perform no other action. \see \wref{block:REFILL}{REFILL}, \wref{file:REFILL}{REFILL}, \rref{core:REFILL}{}. \begin{rationale} % A.6.2.2125 REFILL \word{REFILL} is designed to behave reasonably for all possible input sources. If the input source is coming from the user, \word{REFILL} could still return a false value if, for instance, a communication channel closes so that the system knows that no more input will be available. \end{rationale} \end{worddef} \begin{worddef}{2148}{RESTORE-INPUT} \item \stack{x_n {\ldots} x_1 n}{flag} Attempt to restore the input source specification to the state described by \param{x_1} through \param{x_n}. \param{flag} is true if the input source specification cannot be so restored. An ambiguous condition exists if the input source represented by the arguments is not the same as the current input source. \see \wref{tools:NtoR}{}, \wref{tools:NRfrom}{}, \rref{core:SAVE-INPUT}{SAVE-INPUT}. \end{worddef} \begin{worddef}{2150}{ROLL} \item \stack{x_u x_{u-1} {\ldots} x_0 u}{x_{u-1} {\ldots} x_0 x_u} Remove \param{u}. Rotate \param{u}+1 items on the top of the stack. An ambiguous condition exists if there are less than \param{u}+2 items on the stack before \word{ROLL} is executed. \see \rref{core:ROLL}{}. \begin{rationale} % A.6.2.2150 ROLL \texttt{2} \word{ROLL} is equivalent to \word{ROT}, \texttt{1} \word{ROLL} is equivalent to \word{SWAP} and \texttt{0} \word{ROLL} is a null operation. \end{rationale} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}[Seq]{2266}{S\bs"}[s-backslash-quote][X:escaped-strings] \interpret Interpretation semantics for this word are undefined. \compile \stack{"ccc"}{} \\ Parse \param{ccc} delimited by \verb|"| (double-quote), using the translation rules below. Append the run-time semantics given below to the current definition. \item[Translation rules] Characters are processed one at a time and appended to the compiled string. If the character is a `\bs' character it is processed by parsing and substituting one or more \linebreak characters as follows, where the character after the backslash is case sensitive: \begin{tabular}{llll} \verb|\a| & BEL & (alert, & ASCII 7) \\ \verb|\b| & BS & (backspace, & ASCII 8) \\ \verb|\e| & ESC & (escape, & ASCII 27) \\ \verb|\f| & FF & (form feed, & ASCII 12) \\ \verb|\l| & LF & (line feed, & ASCII 10) \\ \verb|\m| & CR/LF & pair & (ASCII 13, 10) \\ \verb|\n| & newline & \multicolumn{2}{l}{(implementation dependent , e.g., CR/LF, CR, LF, LF/CR)} \\ \verb|\q| & \multicolumn{2}{l}{double-quote} & (ASCII 34) \\ \verb|\r| & CR & (carriage return, & ASCII 13) \\ \verb|\t| & HT & (horizontal tab, & ASCII 9) \\ \verb|\v| & VT & (vertical tab, & ASCII 11) \\ \verb|\z| & NUL & (no character, & ASCII 0) \\ \verb|\"| & \multicolumn{2}{l}{double-quote} & (ASCII 34) \\ \multicolumn{3}{l}{\texttt{\bs{}x}\arg{hexdigit}\arg{hexdigit}} \\ &&\multicolumn{2}{p{27em}}{ The resulting character is the conversion of these two hexadecimal digits. An ambiguous conditions exists if \texttt{\bs{x}} is not followed by two hexadecimal characters.} \\ \texttt{\bs\bs} & \multicolumn{2}{l}{backslash itself} & (ASCII 92) \\ \end{tabular} An ambiguous condition exists if a \bs{} is placed before any character, other than those defined in here. \runtime \stack{}{c-addr u} \\ Return \param{c-addr} and \param{u} describing a string consisting of the translation of the characters \param{ccc}. A program shall not alter the returned string. \see \xref{usage:parsing}, \wref{core:Cq}{}, \wref{file:Sq}{}, \rref{core:Sq}{}. \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{2182}{SAVE-INPUT} \item \stack{}{x_n {\ldots} x_1 n} \param{x_1} through \param{x_n} describe the current state of the input source specification for later use by \word{RESTORE-INPUT}. \see \wref{tools:NtoR}{}, \wref{tools:NRfrom}{}, \rref{core:SAVE-INPUT}{}. \begin{rationale} % A.6.2.2182 SAVE-INPUT \word{SAVE-INPUT} and \word{RESTORE-INPUT} allow the same degree of input source repositioning within a text file as is available with \word[block]{BLOCK} input. \word{SAVE-INPUT} and \word{RESTORE-INPUT} ``hide the details'' of the operations necessary to accomplish this repositioning, and are used the same way with all input sources. This makes it easier for programs to reposition the input source, because they do not have to inspect several variables and take different action depending on the values of those variables. \word{SAVE-INPUT} and \word{RESTORE-INPUT} are intended for repositioning within a single input source; for example, the following scenario is NOT allowed for a Standard Program: \begin{quote}\ttfamily \word{:} XX \\ \tab \word{SAVE-INPUT} ~ \word{CREATE} \\ \tab \word{Sq} RESTORE-INPUT" \word{EVALUATE} \\ \tab \word{ABORTq} couldn't restore input" \\ \word{;} \end{quote} This is incorrect because, at the time \word{RESTORE-INPUT} is executed, the input source is the string via \word{EVALUATE}, which is not the same input source that was in effect when \word{SAVE-INPUT} was executed. The following code is allowed: \begin{quote}\ttfamily \word{:} XX \\ \tab \word{SAVE-INPUT} ~ \word{CREATE} \\ \tab \word{Sq} \word{.p} Hello)" \word{EVALUATE} \\ \tab \word{RESTORE-INPUT} \word{ABORTq} couldn't restore input" \\ \word{;} \end{quote} After \word{EVALUATE} returns, the input source specification is restored to its previous state, thus \hyperref{}{core}{SAVE-INPUT}{\textbf{\texttt{SAVE-}}} \hyperref{}{core}{SAVE-INPUT}{\textbf{\texttt{INPUT}}} and \word{RESTORE-INPUT} are called with the same input source in effect. In the above examples, the \word{EVALUATE} phrase could have been replaced by a phrase involving \word[file]{INCLUDE-FILE} and the same rules would apply. The standard does not specify what happens if a program violates the above rules. A Standard System might check for the violation and return an exception indication from \word{RESTORE-INPUT}, or it might fail in an unpredictable way. The return value from \word{RESTORE-INPUT} is primarily intended to report the case where the program attempts to restore the position of an input source whose position cannot be restored. The keyboard might be such an input source. Nesting of \word{SAVE-INPUT} and \word{RESTORE-INPUT} is allowed. For example, the following situation works as expected: \begin{quote}\ttfamily \word{:} XX \\ \tab \word{SAVE-INPUT} \\ \tab~~ \word{Sq} f1" \word[file]{INCLUDED} \\ \tab~~ \word{bs} The file "f1" includes: \\ \tab~~ \word{bs} ~~ {\ldots} SAVE-INPUT {\ldots} RESTORE-INPUT {\ldots} \\ \tab~~ \word{bs} End of file "f1" \\ \tab \word{RESTORE-INPUT} ~ \word{ABORTq} couldn't restore input" \\ \word{;} \end{quote} In principle, \word{RESTORE-INPUT} could be implemented to ``always fail'', e.g.: \begin{quote}\ttfamily \word{:} \word{RESTORE-INPUT} \word{p} x1 {\ldots} xn n -{}- flag ) \\ \tab 0 \word{qDO} \word{DROP} \word{LOOP} \word{TRUE} \\ \word{;} \end{quote} Such an implementation would not be useful in most cases. It would be preferable for a system to leave \word{SAVE-INPUT} and \word{RESTORE-INPUT} undefined, rather than to create a useless implementation. In the absence of the words, the application programmer could choose whether or not to create ``dummy'' implementations or to work-around the problem in some other way. Examples of how an implementation might use the return values from \word{SAVE-INPUT} to accomplish the save/restore function: \begin{center} \begin{tabular}{lllll} \hline\hline Input Source & \multicolumn{4}{l}{possible stack values} \\ \hline block & \word{toIN} \word{@} & \word[block]{BLK} \word{@} & \texttt{2} \\ \word{EVALUATE} & \word{toIN} \word{@} & \texttt{1} \\ keyboard & \word{toIN} \word{@} & \texttt{1} \\ text file & \word{toIN} \word{@} & \texttt{lo-pos} & \texttt{hi-pos} & \texttt{3} \\ \hline\hline \end{tabular} \end{center} These are examples only; a Standard Program may not assume any particular meaning for the individual stack items returned by \word{SAVE-INPUT}. \pagebreak \end{rationale} \begin{testing}\ttfamily \textdf{Testing with a file source} \\ \word{VARIABLE} siv -1 siv \word{!} \word{:} NeverExecuted \\ \tab \word{.q} This should never be executed\texttt{"} \word{ABORT} \\ \word{;} 11111 \word{SAVE-INPUT} siv \word{@} \word[tools]{[IF]} \\ \tab 0 siv \word{!} \\ \tab \word{RESTORE-INPUT} \\ \tab NeverExecuted \\ \word[tools]{[ELSE]} \\ \tab \word{bs} \textdf{Testing the ELSE part is executed} \\ \tab 22222 \\ \word[tools]{[THEN]} \test{}{11111 0 22222} \tab \word{bs} \textdf{0 comes from \word{RESTORE-INPUT}} \textdf{Testing with a string source} \\ \word{VARIABLE} si\_inc 0 si\_inc \word{!} \word{:} si1 \\ \tab si\_inc \word{@} \word{toIN} \word{+!} \\ \tab 15 si\_inc \word{!} \\ \word{;} \word{:} s\$ \word{Sq} \word{SAVE-INPUT} si1 \word{RESTORE-INPUT} 12345\texttt{"} \word{;} \test{s\$ \word{EVALUATE} si\_inc \word{@}}{0 2345 15} \textdf{Testing nesting} \\ \word{:} read\_a\_line \\ \tab \word{REFILL} \word{0=} \\ \tab \word{ABORTq} \word{REFILL} failed\texttt{"} \\ \word{;} 0 si\_inc \word{!} \\ \word[double]{2VARIABLE} 2res -1.\ 2res \word{2!} \word{:} si2 \\ \tab read\_a\_line \\ \tab read\_a\_line \\ \tab \word{SAVE-INPUT} \\ \tab read\_a\_line \\ \tab read\_a\_line \\ \tab s\$ \word{EVALUATE} 2res \word{2!} \\ \tab \word{RESTORE-INPUT} \\ \word{;} \textdf{\textbf{WARNING:} do not delete or insert lines of text after si2 is called otherwise the next test will fail} si2 \\ 33333 \tab[7.75] \word{bs} \textdf{This line should be ignored} \\ 2res 2@ 44444 \tab[3] \word{bs} \textdf{\word{RESTORE-INPUT} should return to this line} 55555 \test{}{0 0 2345 44444 55555} \end{testing} \end{worddef} \begin{worddef}{2218}{SOURCE-ID}[source-i-d] \item \stack{}{0 | -1 } Identifies the input source as follows: \begin{center} \begin{tabular}{cl} \hline\hline \word{SOURCE-ID} & Input source \\ \hline -1 & String (via \word{EVALUATE}) \\ 0 & User input device \\ \hline\hline \end{tabular} \end{center} \see \wref{file:SOURCE-ID}{SOURCE-ID}. \end{worddef} %\begin{worddef}{2240}{SPAN}[][x:legacy] %\item \stack{}{a-addr} % % \param{a-addr} is the address of a cell containing the count of % characters stored by the last execution of \word{EXPECT}. % %\note % This word is obsolescent and is included as a concession to % existing implementations. %\end{worddef} %\begin{worddef}{2290}{TIB}[t-i-b][x:legacy] %\item \stack{}{c-addr} % % \param{c-addr} is the address of the terminal input buffer. % %\note % This word is obsolescent and is included as a concession to % existing implementations. % %\see \rref{core:TIB}{}. % % \begin{rationale} % A.6.2.2290 TIB % The function of \word{TIB} has been superseded by % \word{SOURCE}. % \end{rationale} %\end{worddef} \begin{worddef}{2295}{TO} \interpret \stack{i*x "name"}{} Skip leading spaces and parse \param{name} delimited by a space. Perform the ``TO \param{name} run-time'' semantics given in the definition for the defining word of \param{name}. An ambiguous condition exists if \param{name} was not defined by a word with ``TO \param{name} run-time'' semantics. \compile \stack{"name"}{} Skip leading spaces and parse \param{name} delimited by a space. Append the ``TO \param{name} run-time'' semantics given in the definition for the defining word of \param{name} to the current definition. An ambiguous condition exists if \param{name} was not defined by a word with ``TO \param{name} run-time'' semantics. \runtime \stack{}{} \note An ambiguous condition exists if any of \word{POSTPONE}, \word{[COMPILE]}, \word{'} or \word{[']} are applied to \word{TO}. \see \wref{core:VALUE}{VALUE}, \wref{double:2VALUE}{2VALUE}, \wref{floating:FVALUE}{FVALUE}, \wref{local:LOCAL}{(LOCAL)}, \rref{core:TO}{}. \begin{rationale} % A.6.2.2295 TO Typical use: \texttt{x} \word{TO} \emph{name} Some implementations of \word{TO} do not parse; instead they set a mode flag that is tested by the subsequent execution of \param{name}. Standard programs must use \word{TO} as if it parses. Therefore \word{TO} and \param{name} must be contiguous and on the same line in the source text. \end{rationale} \begin{testing} % T.6.2.2295 TO See \tref{core:VALUE}{VALUE}. \end{testing} \end{worddef} \enlargethispage{6ex} \begin{worddef}{2298}{TRUE} \item \stack{}{true} Return a \param{true} flag, a single-cell value with all bits set. \see \xref[3.1.3.1 Flags]{usage:flags}, \rref{core:TRUE}{}. \begin{rationale} % A.6.2.2298 TRUE \word{TRUE} is equivalent to the phrase \texttt{0} \word{0=}. \end{rationale} \begin{testing} \test{\word{TRUE}}{} \\ \test{\word{TRUE}}{0 INVERT} \\ \end{testing} \end{worddef} \begin{worddef}{2300}{TUCK} \item \stack{x_1 x_2}{x_2 x_1 x_2} Copy the first (top) stack item below the second stack item. \end{worddef} \begin{worddef}{2330}{U.R}[u-dot-r] \item \stack{u n}{} Display \param{u} right aligned in a field \param{n} characters wide. If the number of characters required to display \param{u} is greater than \param{n}, all digits are displayed with no leading spaces in a field as wide as necessary. \end{worddef} \begin{worddef}[Umore]{2350}{U>}[u-greater-than] \item \stack{u_1 u_2}{flag} \param{flag} is true if and only if \param{u_1} is greater than \param{u_2}. \see \wref{core:more}{>}. \end{worddef} \begin{worddef}{2395}{UNUSED} \item \stack{}{u} \param{u} is the amount of space remaining in the region addressed by \word{HERE}, in address units. \end{worddef} \begin{worddef}{2405}{VALUE} \item \stack{x "name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Create a definition for \param{name} with the execution semantics defined below, with an initial value equal to \param{x}. \param{name} is referred to as a ``value''. \execute[name] \stack{}{x} Place \param{x} on the stack. The value of \param{x} is that given when \param{name} was created, until the phrase \param{x} \word{TO} \param{name} is executed, causing a new value of \param{x} to be assigned to \param{name}. \runtime[\word{TO} \param{name}] \stack{x}{} Assign the value \param{x} to \param{name}. \see \xref[3.4.1 Parsing]{usage:parsing}, \wref{core:TO}{TO}, \rref{core:VALUE}{}. \begin{rationale} % A.6.2.2405 VALUE Typical use: \begin{quote}\ttfamily 0 \word{VALUE} data \word{:} EXCHANGE \word{p} n1 -{}- n2 ) data \word{SWAP} \word{TO} data \word{;} \end{quote} \texttt{EXCHANGE} leaves \param{n_1} in \texttt{data} and returns the prior value \param{n_2}. \end{rationale} \begin{testing} % T.6.2.2405 VALUE \test{ 111 VALUE v1}{} \\ \test{-999 VALUE v2}{} \\ \test{v1}{ 111} \\ \test{v2}{-999} \\ \test{222 TO v1}{} \\ \test{v1}{222} \test{\word{:} vd1 v1 \word{;}}{} \\ \test{vd1}{222} \test{\word{:} vd2 \word{TO} v2 \word{;}}{} \\ \test{v2}{-999} \\ \test{-333 vd2}{} \\ \test{v2}{-333} \\ \test{v1}{ 222} \end{testing} \end{worddef} \begin{worddef}{2440}{WITHIN} \item \stack{n_1|u_1 n_2|u_2 n_3|u_3}{flag} Perform a comparison of a test value \param{n_1|u_1} with a lower limit \param{n_2|u_2} and an upper limit \param{n_3|u_3}, returning \emph{true} if either (\param{n_2|u_2} < \param{n_3|u_3} and (\param{n_2|u_2} <= \param{n_1|u_1} and \param{n_1|u_1} < \param{n_3|u_3})) or (\param{n_2|u_2} > \param{n_3|u_3} and (\param{n_2|u_2} <= \param{n_1|u_1} or \param{n_1|u_1} < \param{n_3|u_3})) is true, returning \emph{false} otherwise. An ambiguous condition exists \param{n_1|u_1}, \param{n_2|u_2}, and \param{n_3|u_3} are not all the same type. \see \rref{core:WITHIN}{}. \begin{rationale} % A.6.2.2440 WITHIN We describe \word{WITHIN} without mentioning circular number spaces (an undefined term) or providing the code. Here is a number line with the overflow point ($o$) at the far right and the underflow point ($u$) at the far left: \begin{center} $u$\rule[.5ex]{15em}{.4pt}$o$ \end{center} There are two cases to consider: either the \param{n_2|u_2\ldots n_3|u_3} range straddles the overflow/underflow points or it does not. Lets examine the non-straddle case first: \begin{center} $u$\rule[.5ex]{5em}{.4pt}\makebox[5em]{[\dotfill)}\rule[.5ex]{5em}{.4pt}$o$ \end{center} The [ denotes \param{n_2|u_2}, the ) denotes \param{n_3|u_3}, and the dots and [ are numbers \word{WITHIN} the range. \param{n_3|u_3} is greater than \param{n_2|u_2}, so the following tests will determine if \param{n_1|u_1} is \word{WITHIN} \param{n_2|u_2} and \param{n_3|u_3}: \begin{center} \param{n_2|u_2} $\le$ \param{n_1|u_1} and \param{n_1|u_1} < \param{n_3|u_3}. \end{center} In the case where the comparison range straddles the overflow/underflow points: \begin{center} $u$\makebox[5em]{\dotfill)}\rule[.5ex]{5em}{.4pt}\makebox[5em]{[\dotfill}$o$ \end{center} \param{n_3|u_3} is less than \param{n_2|u_2} and the following tests will determine if \param{n_1|u_1} is \word{WITHIN} \param{n_2|u_2} and \param{n_3|u_3}: \begin{center} \param{n_2|u_2} $\le$ \param{n_1|u_1} or \param{n_1|u_1} < \param{n_3|u_3}. \end{center} \word{WITHIN} must work for both signed and unsigned arguments. One obvious implementation does not work: \begin{quote}\ttfamily \word{:} \word{WITHIN} \word{p} test low high -{}- flag ) \\ \tab \word{toR} \word{OVER} \word{less} \word{0=} \word{p} test flag1 ) \word{SWAP} \word{Rfrom} \word{less} \word{p} flag1 flag2 ) \word{AND} \\ \word{;} \end{quote} Assume two's-complement arithmetic on a 16-bit machine, and consider the following test: \tab \texttt{33000 ~ 32000 ~ 34000 ~ WITHIN} The above implementation returns \emph{false} for that test, even though the unsigned number 33000 is clearly within the range \{\{32000 {\ldots} 34000\}\}. The problem is that, in the incorrect implementation, the signed comparison \word{less} gives the wrong answer when 32000 is compared to 33000, because when those numbers are treated as signed numbers, 33000 is treated as negative 32536, while 32000 remains positive. Replacing \word{less} with \word{Uless} in the above implementation makes it work with unsigned numbers, but causes problems with certain signed number ranges; in particular, the test: \begin{quote}\ttfamily 1 ~ -5 ~ 5 ~ WITHIN \end{quote} would give an incorrect answer. For two's-complement machines that ignore arithmetic overflow (most machines), the following implementation works in all cases: \begin{quote}\ttfamily \word{:} \word{WITHIN} \word{p} test low high -{}- flag ) ~ \word{OVER} \word{-} \word{toR} \word{-} \word{Rfrom} \word{Uless} ~ \word{;} \end{quote} \end{rationale} \end{worddef} \begin{worddef}{2530}{[COMPILE]}[bracket-compile] \interpret Interpretation semantics for this word are undefined. \compile \stack{"name"}{} Skip leading space delimiters. Parse \param{name} delimited by a space. Find \param{name}. If \param{name} has other than default compilation semantics, append them to the current definition; otherwise append the execution semantics of \param{name}. An ambiguous condition exists if \param{name} is not found. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{core:[COMPILE]}{}. \begin{rationale} % A.6.2.2530 [COMPILE] Typical use: \word{:} \texttt{name2} {\ldots} \word{[COMPILE]} \texttt{name1} {\ldots} \word{;} ~ \word{IMMEDIATE} \end{rationale} \begin{testing} \textdf{With default compilation semantics} \\ \test{\word{:} [c1] \word{[COMPILE]} \word{DUP} \word{;} \word{IMMEDIATE}}{} \\ \test{123 [c1]}{123 123} \textdf{With an immediate word} \\ \test{\word{:} [c2] \word{[COMPILE]} [c1] \word{;}}{} \\ \test{234 [c2]}{234 234} \textdf{With special compilation semantics} \\ \test{\word{:} [cif] \word{[COMPILE]} \word{IF} \word{;} \word{IMMEDIATE}}{} \\ \test{\word{:} [c3] [cif] 111 \word{ELSE} 222 \word{THEN} \word{;}}{} \\ \test{-1 [c3]}{111} \\ \test{ 0 [c3]}{222} \end{testing} \end{worddef} \begin{worddef}[bs]{2535}{\bs}[backslash] \compile Perform the execution semantics given below. \execute \stack{"ccc"}{} Parse and discard the remainder of the parse area. \word{bs} is an immediate word. \see \wref{block:bs}{\bs}, \rref{core:bs}{}. \begin{rationale} % A.6.2.2535 \ Typical use: \begin{quote}\ttfamily 5 \word{CONSTANT} THAT ~ \word{bs} ~ \textdf{This is a comment about THAT} \end{quote} \end{rationale} \end{worddef}