% !TeX root = forth.tex % !TeX spell check = en_US \chapter{The optional Floating-Point word set} % 12 \wordlist{floating} \section{Introduction} % 12.1 \section{Additional terms and notation} % 12.2 \subsection{Definition of terms} % 12.2.1 \label{float:terms} \begin{description} \item[float-aligned address:] The address of a memory location at which a floating-point number can be accessed. \item[double-float-aligned address:] The address of a memory location at which a 64-bit IEEE double-precision floating-point number can be accessed. \item[single-float-aligned address:] The address of a memory location at which a 32-bit IEEE single-precision floating-point number can be accessed. \item[IEEE floating-point number:] A single- or double-precision floating-point number as defined in \linebreak \textbf{ANSI/IEEE 754-1985}. \end{description} \subsection{Notation} % 12.2.2 \label{float:notation} \stepcounter{subsubsection} \subsubsection{Stack notation} % 12.2.2.2 Floating-point stack notation is: \begin{quote} \stack[F]{before}{after} \end{quote} A unified stack notation is provided for systems with the environmental restriction that the floating-point numbers are kept on the data stack. \section{Additional usage requirements} % 12.3 \subsection{Data types} % 12.3.1 \label{float:datatypes} Append table \ref{float:types} to table \ref{table:datatypes}. \begin{table}[ht] \begin{center} \caption{Data Types} \label{float:types} \begin{tabular}{llr} \hline\hline \emph{Symbol} & \emph{Data type} & \emph{Size on stack} \\ \hline \emph{df-addr} & double-float-aligned address & 1 cell \\ \emph{f-addr} & float-aligned address & 1 cell \\ \emph{r} & floating-point number & implementation-defined \\ \emph{sf-addr} & single-float-aligned address & 1 cell \\ \hline\hline \end{tabular} \end{center} \end{table} \subsubsection{Addresses} % 12.3.1.1 \label{float:addr} The set of float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a floating-point number to a float-aligned address shall produce a float-aligned address. The set of double-float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a 64-bit IEEE double-precision floating-point number to a double-float-aligned address shall produce a double-float-aligned address. The set of single-float-aligned addresses is an implementation-defined subset of the set of aligned addresses. Adding the size of a 32-bit IEEE single-precision floating-point number to a single-float-aligned address shall produce a single-float-aligned address. \subsubsection{Floating-point numbers} % 12.3.1.2 \label{float:num} The internal representation of a floating-point number, including the format and precision of the significand and the format and range of the exponent, is implementation defined. Any rounding or truncation of floating-point numbers is implementation defined. \subsection{Floating-point operations} % 12.3.2 \label{float:ops} ``Round to nearest'' means round the result of a floating-point operation to the representable value nearest the result. If the two nearest representable values are equally near the result, the one having zero as its least significant bit shall be delivered. ``Round toward negative infinity'' means round the result of a floating-point operation to the representable value nearest to and no greater than the result. ``Round toward zero'' means round the result of a floating-point operation to the representable value nearest to zero, frequently referred to as ``truncation''. \subsection{Floating-point stack} % 12.3.3 \label{float:stack} A last in, first out list that shall be used by all floating-point operators. The width of the floating-point stack is implementation-defined. The floating-point stack shall be separate from the data and return stacks. The size of a floating-point stack shall be at least 6 items. A program that depends on the floating-point stack being larger than six items has an environmental dependency. \subsection{Environmental queries} % 12.3.4 Append table \ref{float:env} to table \ref{table:env}. See: \xref[3.2.6 Environmental queries]{usage:env}. \begin{table}[ht] \begin{center} \caption{Environmental Query Strings} \label{float:env} \begin{tabular}{p{9em}rcp{0.42\textwidth}} \hline\hline \multicolumn{2}{l}{String \hfill Value data type} & Constant? & Meaning \\ \hline \texttt{FLOATING-STACK} & \emph{n} & yes & the maximum depth of the separate floating-point stack. On systems with the environmental restriction of keeping floating-point items on the data stack, \emph{n} = 0. \\ \texttt{MAX-FLOAT} & \emph{r} & yes & largest usable floating-point number \\ \hline\hline \end{tabular} \end{center} \end{table} \subsection{Address alignment} % 12.3.5 Since the address returned by a \word[core]{CREATE}d word is not necessarily aligned for any particular class of floating-point data, a program shall align the address (to be float aligned, single-float aligned, or double-float aligned) before accessing floating-point data at the address. See: \xref[3.3.3.1 Address Alignment]{usage:aaddr}, \xref[12.3.1.1 Addresses]{float:addr}. \subsection{Variables} % 12.3.6 A program may address memory in data space regions made available by \word{FVARIABLE}. These regions may be non-contiguous with regions subsequently allocated with \word[core]{,} (comma) or \word[core]{ALLOT}. See: \xref[3.3.3.3 Variables]{usage:var}. \subsection{Text interpreter input number conversion} % 12.3.7 \label{float:conv} If the Floating-Point word set is present in the dictionary and the current base is \word[core]{DECIMAL}, the input number-conversion algorithm shall be extended to recognize floating-point numbers in this form: \begin{center} \begin{tabular}{r@{ \textsf{:=} }l} Convertible string & \arg{significand}\arg{exponent} \\ \arg{significand} & [\arg{sign}]\arg{digits}[\textbf{.}\arg{digits0}] \\ \arg{exponent} & \textbf{E}[\arg{sign}]\arg{digits0} \\ \arg{sign} & \{ \textbf{+} {\textbar} \textbf{-} \} \\ \arg{digits} & \arg{digit}\arg{digits0} \\ \arg{digits0} & \arg{digit}* \\ \arg{digit} & \{ \textbf{0} {\textbar} \textbf{1} {\textbar} \textbf{2} {\textbar} \textbf{3} {\textbar} \textbf{4} {\textbar} \textbf{5} {\textbar} \textbf{6} {\textbar} \textbf{7} {\textbar} \textbf{8} {\textbar} \textbf{9} \} \\ \end{tabular} \end{center} These are examples of valid representations of floating-point numbers in program source: \begin{center} \texttt{1E \qquad 1.E \qquad 1.E0 \qquad +1.23E-1 \qquad -1.23E+1} \end{center} See: \xref[3.4.1.3 Text interpreter input number conversion]{usage:numbers}, \wref{floating:toFLOAT}{>FLOAT}. \section{Additional documentation requirements} % 12.4 \subsection{System documentation} % 12.4.1 \subsubsection{Implementation-defined options} % 12.4.1.1 \begin{itemize} \item format and range of floating-point numbers (\xref[12.3.1 Data types]{float:datatypes}, \wref{floating:REPRESENT}{REPRESENT}); \item results of \wref{floating:REPRESENT}{REPRESENT} when \emph{float} is out of range; \item rounding or truncation of floating-point numbers (\xref[12.3.1.2 Floating-point numbers]{float:num}); \item size of floating-point stack (\xref[12.3.3 Floating-point stack]{float:stack}); \item width of floating-point stack (\xref[12.3.3 Floating-point stack]{float:stack}). \end{itemize} \subsubsection{Ambiguous conditions} % 12.4.1.2 \label{float:ambiguous} \begin{itemize} \item \word{DF@} or \word{DF!} is used with an address that is not double-float aligned; \item \word{F@} or \word{F!} is used with an address that is not float aligned; \item floating point result out of range (e.g., in \wref{floating:F/}{F/}); \item \word{SF@} or \word{SF!} is used with an address that is not single-float aligned; \item \word[core]{BASE} is not decimal (\wref{floating:REPRESENT}{REPRESENT}, \wref{floating:Fd}{F.}, \wref{floating:FEd}{FE.}, \wref{floating:FSd}{FS.}); \item both arguments equal zero (\wref{floating:FATAN2}{FATAN2}); \item cosine of argument is zero for \wref{floating:FTAN}{FTAN}; \item \param{d} can't be precisely represented as \emph{float} in \wref{floating:DtoF}{D>F}; \item dividing by zero (\wref{floating:F/}{F/}); \item exponent too big for conversion (\wref{floating:DF!}{DF!}, \wref{floating:DF@}{DF@}, \wref{floating:SF!}{SF!}, \wref{floating:SF@}{SF@}); \item \emph{float} less than one (\wref{floating:FACOSH}{FACOSH}); \item \emph{float} less than or equal to minus-one (\wref{floating:FLNP1}{FLNP1}); \item \emph{float} less than or equal to zero (\wref{floating:FLN}{FLN}, \wref{floating:FLOG}{FLOG}); \item \emph{float} less than zero (\wref{floating:FSQRT}{FSQRT}); \item \emph{float} magnitude greater than one (\wref{floating:FACOS}{FACOS}, \wref{floating:FASIN}{FASIN}, \wref{floating:FATANH}{FATANH}); \item integer part of \emph{float} can't be represented by \param{d} in \wref{floating:FtoD}{F>D}; \item string larger than pictured-numeric output area (\wref{floating:Fd}{F.}, \wref{floating:FEd}{FE.}, \wref{floating:FSd}{FS.}); \item \param{n} can't be precisely represented as \emph{float} in \wref{floating:StoF}{S>F}; \item integer part of \emph{float} can't be represented by \param{n} in \wref{floating:FtoS}{F>S}. \end{itemize} \subsubsection{Other system documentation} % 12.4.1.3 \begin{itemize} \item no additional requirements. \end{itemize} \subsubsection{Environmental restrictions} % 12.4.1.4 \label{float:restrictions} \begin{itemize} \item Keeping floating-point numbers on the data stack. \end{itemize} \subsection{Program documentation} % 12.4.2 \subsubsection{Environmental dependencies} % 12.4.2.1 \label{float:dependencies} \begin{itemize} \item requiring the floating-point stack to be larger than six items (\xref[12.3.3 Floating-point stack]{float:stack}); \item requiring floating-point numbers to be kept on the data stack, with $n$ cells per floating point number. \end{itemize} \subsubsection{Other program documentation} % 12.4.2.2 \begin{itemize} \item no additional requirements. \end{itemize} \section{Compliance and labeling} % 12.5 \subsection{Forth-\snapshot{} systems} % 12.5.1 The phrase ``Providing the Floating-Point word set'' shall be appended to the label of any Standard System that provides all of the Floating-Point word set. The phrase ``Providing \emph{name(s)} from the Floating-Point Extensions word set'' shall be appended to the label of any Standard System that provides portions of the Floating-Point Extensions word set. The phrase ``Providing the Floating-Point Extensions word set'' shall be appended to the label of any Standard System that provides all of the Floating-Point and Floating-Point Extensions word sets. \subsection{Forth-\snapshot{} programs} % 12.5.2 The phrase ``Requiring the Floating-Point word set'' shall be appended to the label of Standard Programs that require the system to provide the Floating-Point word set. The phrase ``Requiring \emph{name(s)} from the Floating-Point Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide portions of the Floating-Point Extensions word set. The phrase ``Requiring the Floating-Point Extensions word set'' shall be appended to the label of Standard Programs that require the system to provide all of the Floating-Point and Floating-Point Extensions word sets. \section{Glossary} % 12.6 \subsection{Floating-Point words} % 12.6.1 \enlargethispage{2ex} \begin{worddef}[toFLOAT]{0558}{>FLOAT}[to-float] \item \stack{c-addr u}{true | false} \stack[F]{}{r |~} or \stack{c-addr u}{r true | false} An attempt is made to convert the string specified by \param{c-addr} and \param{u} to internal floating-point representation. If the string represents a valid floating-point number in the syntax below, its value \param{r} and \param{true} are returned. If the string does not represent a valid floating-point number only \param{false} is returned. A string of blanks should be treated as a special case representing zero. The syntax of a convertible string \begin{center} \begin{tabular}{r@{ \textsf{:=} }l} & \arg{significand}[\arg{exponent}] \\ \arg{significand} & [\arg{sign}]\{\arg{digits}[\textbf{.}\arg{digits0}] {\textbar} \textbf{.}\arg{digits} \} \\ \arg{exponent} & \arg{marker}\arg{digits0} \\ \arg{marker} & \{\arg{e-form} {\textbar} \arg{sign-form}\}\\ \arg{e-form} & \arg{e-char}[\arg{sign-form}] \\ \arg{sign-form} & \{ \textbf{+} {\textbar} \textbf{-} \} \\ \arg{e-char} & \{ \textbf{D} {\textbar} \textbf{d} {\textbar} \textbf{E} {\textbar} \textbf{e} \} \\ \end{tabular} \end{center} \see \rref{floating:toFLOAT}{}. \begin{rationale} % A.12.6.1.0558 >FLOAT \word{toFLOAT} enables programs to read floating-point data in legible ASCII format. It accepts a much broader syntax than does the text interpreter since the latter defines rules for composing source programs whereas \word{toFLOAT} defines rules for accepting data. \word{toFLOAT} is defined as broadly as is feasible to permit input of data from Forth-\snapshot{} systems as well as other widely used standard programming environments. This is a synthesis of common FORTRAN practice. Embedded spaces are explicitly forbidden in much scientific usage, as are other field separators such as comma or slash. While \word{toFLOAT} is not required to treat a string of blanks as zero, this behavior is strongly encouraged, since a future version of this standard may include such a requirement. \end{rationale} \end{worddef} \begin{worddef}[DtoF]{1130}{D>F}[d-to-f] \item \stack{d}{} \stack[F]{}{r} or \stack{d}{r} \param{r} is the floating-point equivalent of \param{d}. An ambiguous condition exists if \param{d} cannot be precisely represented as a floating-point value. \end{worddef} \begin{worddef}{1400}{F!}[f-store] \item \stack{f-addr}{} \stack[F]{r}{} or \stack{r f-addr}{} Store \param{r} at \param{f-addr}. \end{worddef} \begin{worddef}{1410}{F*}[f-star] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} Multiply \param{r_1} by \param{r_2} giving \param{r_3}. \end{worddef} \begin{worddef}{1420}{F+}[f-plus] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} Add \param{r_1} to \param{r_2} giving the sum \param{r_3}. \end{worddef} \begin{worddef}{1425}{F-}[f-minus] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} Subtract \param{r_2} from \param{r_1}, giving \param{r_3}. \end{worddef} \begin{worddef}{1430}{F/}[f-slash] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} Divide \param{r_1} by \param{r_2}, giving the quotient \param{r_3}. An ambiguous condition exists if \param{r_2} is zero, or the quotient lies outside of the range of a floating-point number. \end{worddef} \begin{worddef}[F0less]{1440}{F0<}[f-zero-less-than] \item \stack{}{flag} \stack[F]{r}{} or \stack{r}{flag} \param{flag} is true if and only if \param{r} is less than zero. \end{worddef} \begin{worddef}{1450}{F0=}[f-zero-equals] \item \stack{}{flag} \stack[F]{r}{} or \stack{r}{flag} \param{flag} is true if and only if \param{r} is equal to zero. \end{worddef} \begin{worddef}[Fless]{1460}{F<}[f-less-than] \item \stack{}{flag} \stack[F]{r_1 r_2}{} or \stack{r_1 r_2}{flag} \param{flag} is true if and only if \param{r_1} is less than \param{r_2}. \end{worddef} \begin{worddef}[FtoD]{1470}{F>D}[f-to-d] \item \stack{}{d} \stack[F]{r}{} or \stack{r}{d} \param{d} is the double-cell signed-integer equivalent of the integer portion of \param{r}. The fractional portion of \param{r} is discarded. An ambiguous condition exists if the integer portion of \param{r} cannot be represented as a double-cell signed integer. \note Rounding the floating-point value prior to calling \word{FtoD} is advised, because \word{FtoD} rounds towards zero. \end{worddef} \begin{worddef}{1472}{F@}[f-fetch] \item \stack{f-addr}{} \stack[F]{}{r} or \stack{f-addr}{r} \param{r} is the value stored at \param{f-addr}. \end{worddef} \begin{worddef}{1479}{FALIGN}[f-align] \item \stack{}{} If the data-space pointer is not float aligned, reserve enough data space to make it so. \end{worddef} \begin{worddef}{1483}{FALIGNED}[f-aligned] \item \stack{addr}{f-addr} \param{f-addr} is the first float-aligned address greater than or equal to \param{addr}. \end{worddef} \begin{worddef}{1492}{FCONSTANT}[f-constant] \item \stack{"name"}{} \stack[F]{r}{} or \stack{r "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 an ``f-constant''. \execute[name] \stack{}{} \stack[F]{}{r} or \stack{}{r} Place \param{r} on the floating-point stack. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{floating:FCONSTANT}{}. \begin{rationale} % A.12.6.1.1492 FCONSTANT Typical use: \texttt{r} \word[floating]{FCONSTANT} \param{name} \end{rationale} \end{worddef} \begin{worddef}{1497}{FDEPTH}[f-depth] \item \stack{}{+n} \param{+n} is the number of values contained on the floating-point stack. If the system has an environmental restriction of keeping the floating-point numbers on the data stack, \param{+n} is the current number of possible floating-point values contained on the data stack. \end{worddef} \begin{worddef}{1500}{FDROP}[f-drop] \item \stack[F]{r}{} or \stack{r}{} Remove \param{r} from the floating-point stack. \end{worddef} \begin{worddef}{1510}{FDUP}[f-dupe] \item \stack[F]{r}{r r} or \stack{r}{r r} Duplicate \param{r}. \end{worddef} \begin{worddef}{1552}{FLITERAL}[f-literal] \interpret Interpretation semantics for this word are undefined. \compile \stack[F]{r}{} or \stack{r}{} Append the run-time semantics given below to the current definition. \runtime \stack[F]{}{r} or \stack{}{r} Place \param{r} on the floating-point stack. \see \rref{floating:FLITERAL}{}. \begin{rationale} % A.12.6.1.1552 FLITERAL Typical use: \word[core]{:} \texttt{X} {\ldots} \word[core]{[} {\ldots} \word[core]{p} r ) \word[core]{]} \word{FLITERAL} {\ldots} \word[core]{;} \end{rationale} \end{worddef} \begin{worddef}{1555}{FLOAT+}[float-plus] \item \stack{f-addr_1}{f-addr_2} Add the size in address units of a floating-point number to \param{f-addr_1}, giving \param{f-addr_2}. \end{worddef} \begin{worddef}{1556}{FLOATS} \item \stack{n_1}{n_2} \param{n_2} is the size in address units of \param{n_1} floating-point numbers. \end{worddef} \begin{worddef}{1558}{FLOOR} \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Round \param{r_1} to an integral value using the ``round toward negative infinity'' rule, giving \param{r_2}. \see \xref{float:ops}, \wref{floating:FROUND}{}, \wref{floating:FTRUNC}{}. \end{worddef} \begin{worddef}{1562}{FMAX}[f-max] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} \param{r_3} is the greater of \param{r_1} and \param{r_2}. \end{worddef} \begin{worddef}{1565}{FMIN}[f-min] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} \param{r_3} is the lesser of \param{r_1} and \param{r_2}. \end{worddef} \begin{worddef}{1567}{FNEGATE}[f-negate] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the negation of \param{r_1}. \end{worddef} \begin{worddef}{1600}{FOVER}[f-over] \item \stack[F]{r_1 r_2}{r_1 r_2 r_1} or \stack{r_1 r_2}{r_1 r_2 r_1} Place a copy of \param{r_1} on top of the floating-point stack. \end{worddef} \begin{worddef}{1610}{FROT}[f-rote] \item \stack[F]{r_1 r_2 r_3}{r_2 r_3 r_1} or \stack{r_1 r_2 r_3}{r_2 r_3 r_1} Rotate the top three floating-point stack entries. \end{worddef} \begin{worddef}{1612}{FROUND}[f-round] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Round \param{r_1} to an integral value using the ``round to nearest'' rule, giving \param{r_2}. \see \xref[12.3.2 Floating-point operations]{float:ops}, \wref{floating:FLOOR}{}, \wref{floating:FTRUNC}{}. \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1620}{FSWAP}[f-swap] \item \stack[F]{r_1 r_2}{r_2 r_1} or \stack{r_1 r_2}{r_2 r_1} Exchange the top two floating-point stack items. \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1630}{FVARIABLE}[f-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 \texttt{1} \word{FLOATS} address units of data space at a float-aligned address. \param{name} is referred to as an ``f-variable''. \execute[name] \stack{}{f-addr} \param{f-addr} is the address of the data space reserved by \word{FVARIABLE} when it created \param{name}. A program is responsible for initializing the contents of the reserved space. \see \xref[3.4.1 Parsing]{usage:parsing}, \rref{floating:FVARIABLE}{}. \begin{rationale} % A.12.6.1.1630 FVARIABLE Typical use: \word{FVARIABLE} \param{name} \end{rationale} \end{worddef} \enlargethispage{6ex} \begin{worddef}{2143}{REPRESENT} \item \stack{c-addr u}{n flag_1 flag_2} \stack[F]{r}{} or \stack{r c-addr u}{n flag_1 flag_2} At \param{c-addr}, place the character-string external representation of the significand of the floating-point number \param{r}. Return the decimal-base exponent as \param{n}, the sign as \param{flag_1} and ``valid result'' as \param{flag_2}. The character string shall consist of the \param{u} most significant digits of the significand represented as a decimal fraction with the implied decimal point to the left of the first digit, and the first digit zero only if all digits are zero. The significand is rounded to \param{u} digits following the ``round to nearest'' rule; \param{n} is adjusted, if necessary, to correspond to the rounded magnitude of the significand. If \param{flag_2} is \emph{true} then \param{r} was in the implementation-defined range of floating-point numbers. If \param{flag_1} is \emph{true} then \param{r} is negative. An ambiguous condition exists if the value of \word[core]{BASE} is not decimal ten. When \param{flag_2} is \emph{false}, \param{n} and \param{flag_1} are implementation defined, as are the contents of \param{c-addr}. Under these circumstances, the string at \param{c-addr} shall consist of graphic characters. \see \xref[3.2.1.2 Digit conversion]{usage:digits}, \wref{core:BASE}{BASE}, \xref[12.3.2 Floating-point operations]{float:ops}, \\ \rref{floating:REPRESENT}{}. \begin{rationale} % A.12.6.1.2143 REPRESENT This word provides a primitive for floating-point display. Some floating-point formats, including those specified by IEEE-754, allow representations of numbers outside of an implementation-defined range. These include plus and minus infinities, denormalized numbers, and others. In these cases we expect that \word{REPRESENT} will usually be implemented to return appropriate character strings, such as ``+infinity'' or ``nan'', possibly truncated. \end{rationale} \end{worddef} \subsection{Floating-Point extension words} % 12.6.2 \extended \begin{worddef}{1203}{DF!}[d-f-store] \item \stack{df-addr}{} \stack[F]{r}{} or \stack{r df-addr}{} Store the floating-point number \param{r} as a 64-bit IEEE double-precision number at \param{df-addr}. If the significand of the internal representation of \param{r} has more precision than the IEEE double-precision format, it will be rounded using the ``round to nearest'' rule. An ambiguous condition exists if the exponent of \param{r} is too large to be accommodated in IEEE double-precision format. \see \xref[12.3.1.1 Addresses]{float:addr}, \xref[12.3.2 Floating-point operations]{float:ops}. \end{worddef} \begin{worddef}{1204}{DF@}[d-f-fetch] \item \stack{df-addr}{} \stack[F]{}{r} or \stack{df-addr}{r} Fetch the 64-bit IEEE double-precision number stored at \param{df-addr} to the floating-point stack as \param{r} in the internal representation. If the IEEE double-precision significand has more precision than the internal representation it will be rounded to the internal representation using the ``round to nearest'' rule. An ambiguous condition exists if the exponent of the IEEE double-precision representation is too large to be accommodated by the internal representation. \see \xref[12.3.1.1 Addresses]{float:addr}, \xref[12.3.2 Floating-point operations]{float:ops}. \end{worddef} \begin{worddef}{1205}{DFALIGN}[d-f-align] \item \stack{}{} If the data-space pointer is not double-float aligned, reserve enough data space to make it so. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} \begin{worddef}{1207}{DFALIGNED}[d-f-aligned] \item \stack{addr}{df-addr} \param{df-addr} is the first double-float-aligned address greater than or equal to \param{addr}. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} % --------------------------------------------------------- \newpage \begin{worddef}{1207}[40]{DFFIELD:}[d-f-field-colon][X:structures] \item \stack{n_1 "name"}{n_2} Skip leading space delimiters. Parse \param{name} delimited by a space. \param{Offset} is the first double-float aligned value greater than or equal to \param{n_1}. \param{n_2 = offset + 1} double-float. Create a definition for \param{name} with the execution semantics given below. \execute[name] \stack{addr_1}{addr_2} Add the \param{offset} calculated during the compile-time action to \param{addr_1} giving the address \param{addr_2}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\ \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \rref{facility:FIELD:}{}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{1208}{DFLOAT+}[d-float-plus] \item \stack{df-addr_1}{df-addr_2} Add the size in address units of a 64-bit IEEE double-precision number to \param{df-addr_1}, giving \param{df-addr_2}. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} \begin{worddef}{1209}{DFLOATS}[d-floats] \item \stack{n_1}{n_2} \param{n_2} is the size in address units of \param{n_1} 64-bit IEEE double-precision numbers. \end{worddef} \begin{worddef}{1415}{F**}[f-star-star] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} Raise \param{r_1} to the power \param{r_2}, giving the product \param{r_3}. \end{worddef} \enlargethispage{4ex} \begin{worddef}[Fd]{1427}{F.{}}[f-dot] \item \stack{}{} \stack[F]{r}{} or \stack{r}{} Display, with a trailing space, the top number on the floating-point stack using fixed-point notation: \begin{quote} [\textbf{-}] \arg{digits}\textbf{.}\arg{digits0} \end{quote} An ambiguous condition exists if the value of \word[core]{BASE} is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer. \see \wref{floating:toFLOAT}{>FLOAT}, \rref{floating:Fd}{} \begin{rationale} % A.12.6.1.1427 F. For example, \texttt{1E3} \word{Fd} displays \texttt{1000.} \end{rationale} \end{worddef} % ========== x:stoftos ========== \begin{worddef}[FtoS]{1471}{F>S}[F to S][X:stoftos] \item \stack{}{n} \stack[F]{r}{} or \stack{r}{n} \param{n} is the single-cell signed-integer equivalent of the integer portion of \param{r}. The fractional portion of \param{r} is discarded. An ambiguous condition exists if the integer portion of \param{r} cannot be represented as a single-cell signed integer. \note Rounding the floating-point value prior to calling \word{FtoS} is advised, because \word{FtoS} rounds towards zero. \see \wref{floating:StoF}{}. \begin{implement} \word{:} \word{FtoS} \word{p} r -{}- n ) \\ \tab \word{FtoD} \word[double]{DtoS} \\ \word{;} \end{implement} \end{worddef} % ============================== \begin{worddef}{1474}{FABS}[f-abs] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the absolute value of \param{r_1}. \end{worddef} \begin{worddef}{1476}{FACOS}[f-a-cos] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the principal radian angle whose cosine is \param{r_1}. An ambiguous condition exists if \param{|r_1|} is greater than one. \end{worddef} \begin{worddef}{1477}{FACOSH}[f-a-cosh] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the floating-point value whose hyperbolic cosine is \param{r_1}. An ambiguous condition exists if \param{r_1} is less than one. \end{worddef} \begin{worddef}{1484}{FALOG}[f-a-log] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Raise ten to the power \param{r_1}, giving \param{r_2}. \end{worddef} \begin{worddef}{1486}{FASIN}[f-a-sine] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the principal radian angle whose sine is \param{r_1}. An ambiguous condition exists if \param{|r_1|} is greater than one. \end{worddef} % --------------------------------------------------------- \begin{worddef}{1487}{FASINH}[f-a-cinch] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the floating-point value whose hyperbolic sine is \param{r_1}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{1488}{FATAN}[f-a-tan] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the principal radian angle whose tangent is \param{r_1}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{1489}{FATAN2}[f-a-tan-two] \item \stack[F]{r_1 r_2}{r_3} or \stack{r_1 r_2}{r_3} \param{r_3} is the principal radian angle (between -$\pi$ and $\pi$) whose tangent is \param{r_1/r_2}. A system that returns false for ``\texttt{-0E 0E 0E \word{Ftilde}}'' shall return a value (approximating) $-\pi$ when \param{r_1} $=$ 0E and \param{r_2} is negative. An ambiguous condition exists if \param{r_1} and \param{r_2} are zero. \see \rref{floating:FATAN2}{}. \begin{rationale} % A.12.6.1.1489 FATAN2 \word{FSINCOS} and \word{FATAN2} are a complementary pair of operators which convert angles to 2-vectors and vice-versa. They are essential to most geometric and physical applications since they correctly and unambiguously handle this conversion in all cases except null vectors, even when the tangent of the angle would be infinite. \word{FSINCOS} returns a Cartesian unit vector in the direction of the given angle, measured counter-clockwise from the positive X-axis. The order of results on the stack, namely $y$ underneath $x$, permits the 2-vector data type to be additionally viewed and used as a ratio approximating the tangent of the angle. Thus the phrase \word{FSINCOS} \word{F/} is functionally equivalent to \word{FTAN}, but is useful over only a limited and discontinuous range of angles, whereas \word{FSINCOS} and \word{FATAN2} are useful for all angles. The argument order for \word{FATAN2} is the same, converting a vector in the conventional representation to a scalar angle. Thus, for all angles, \word{FSINCOS} \word{FATAN2} is an identity within the accuracy of the arithmetic and the argument range of \word{FSINCOS}. Note that while \word{FSINCOS} always returns a valid unit vector, \word{FATAN2} will accept any non-null vector. An ambiguous condition exists if the vector argument to \word{FATAN2} has zero magnitude. \end{rationale} \begin{testing}\ttfamily \word[tools]{[UNDEFINED]} ~NaN \word[tools]{[IF]} ~0e 0e \word{F/} \word{FCONSTANT} ~NaN \word[tools]{[THEN]} \\ \word[tools]{[UNDEFINED]} +Inf \word[tools]{[IF]} ~1e 0e \word{F/} \word{FCONSTANT} +Inf \word[tools]{[THEN]} \\ \word[tools]{[UNDEFINED]} -Inf \word[tools]{[IF]} -1e 0e \word{F/} \word{FCONSTANT} -Inf \word[tools]{[THEN]} \word{TRUE} verbose \word{!} \\ \word{DECIMAL} \textdf{The test harness default for \texttt{EXACT?} is TRUE. Uncomment the following line if your system needs it to be FALSE} \\ \word{bs} SET-NEAR \word{VARIABLE} \#errors 0 \#errors \word{!} \word{:NONAME} \word{p} c-addr u -{}- ) \\ \tab \word{p} \textdf{Display an error message followed by the line that had the error\@.} ) \\ \tab 1 \#errors \word{+!} error1 \word{;} error-xt \word{!} % \word[tools]{[UNDEFINED]} $\backslash\backslash$ \word[tools]{[IF]} \\ % \tab \word{:} $\backslash\backslash$ \word{p} -{}- ) % -1 \word{PARSE} \word{2DROP} \word{BEGIN} \word{REFILL} \word{0=} \word{UNTIL} \word{;} \\ % \word[tools]{[THEN]} \\ \word[tools]{[UNDEFINED]} pi \word[tools]{[IF]} \\ \tab 0.3141592653589793238463E1 \word{FCONSTANT} pi \\ \word[tools]{[THEN]} \word[tools]{[UNDEFINED]} -pi \word[tools]{[IF]} \\ \tab pi \word{FNEGATE} \word{FCONSTANT} -pi \\ \word[tools]{[THEN]} \word{FALSE} \word[tools]{[IF]} \\ \tab ~0.7853981633974483096157E0 \word{FCONSTANT} ~~pi/4 \\ \tab -0.7853981633974483096157E0 \word{FCONSTANT} ~-pi/4 \\ \tab ~0.1570796326794896619231E1 \word{FCONSTANT} ~~pi/2 \\ \tab -0.1570796326794896619231E1 \word{FCONSTANT} ~-pi/2 \\ \tab ~0.4712388980384689857694E1 \word{FCONSTANT} ~3pi/2 \\ \tab ~0.2356194490192344928847E1 \word{FCONSTANT} ~3pi/4 \\ \tab -0.2356194490192344928847E1 \word{FCONSTANT} -3pi/4 \\ \word[tools]{[ELSE]} \\ \tab ~pi~~ 4e \word{F/} \word{FCONSTANT} ~~pi/4 \\ \tab -pi~~ 4e \word{F/} \word{FCONSTANT} ~-pi/4 \\ \tab ~pi~~ 2e \word{F/} \word{FCONSTANT} ~~pi/2 \\ \tab -pi~~ 2e \word{F/} \word{FCONSTANT} ~-pi/2 \\ \tab ~pi/2 3e \word{F*} \word{FCONSTANT} ~3pi/2 \\ \tab ~pi/4 3e \word{F*} \word{FCONSTANT} ~3pi/4 \\ \tab -pi/4 3e \word{F*} \word{FCONSTANT} -3pi/4 \\ \word[tools]{[THEN]} verbose \word{@} \word[tools]{[IF]} \\ \tab \word[tools]{:NONAME} \word{p} -{}- fp.separate? ) \\ \tab[2] \word{DEPTH} \word{toR} 1e \word{DEPTH} \word{Rfrom} \word{FDROP} \word{2Rfrom} \word{=} \word{;} \word{EXECUTE} \\ \tab \word{CR} \word{.p} \textdf{floating-point and data stacks} ) \\ \tab \word[tools]{[IF]} \word{.p} \textdf{*separate*} ) \word[tools]{[ELSE]} \word{.p} \textdf{*not separate*} ) \word[tools]{[THEN]} \\ \tab \word{CR} \\ \word[tools]{[THEN]} TESTING normal values \word{bs} ~~y~~~x~~~~~~~~~~~~~~rad~~~~~~~~~deg \\ \test[R]{ 0e 1e \word{FATAN2}}{ 0e }\tab \word{bs} ~~0 \\ \test[R]{ 1e 1e \word{FATAN2}}{ pi/4}\tab \word{bs} ~45 \\ \test[R]{ 1e 0e \word{FATAN2}}{ pi/2}\tab \word{bs} ~90 \\ \test[R]{-1e -1e \word{FATAN2}}{-3pi/4}\tab \word{bs} 135 \\ \test[R]{ 0e -1e \word{FATAN2}}{ pi }\tab \word{bs} 180 \\ \test[R]{-1e 1e \word{FATAN2}}{ -pi/4}\tab \word{bs} 225 \\ \test[R]{-1e 0e \word{FATAN2}}{ -pi/2}\tab \word{bs} 270 \\ \test[R]{-1e 1e \word{FATAN2}}{ -pi/4}\tab \word{bs} 315 TESTING Single UNIX 3 special values spec \word{bs} \textdf{ISO C / Single UNIX Specification Version 3:} \\ \word{bs} \tab \url{http://www.unix.org/single_unix_specification/} \\ \word{bs} \textdf{Select ``Topic'', then ``Math Interfaces'', then ``\texttt{atan2()}'':} \\ \word{bs} \tab \href{http://www.opengroup.org/onlinepubs/009695399/functions/atan2f.html} {http://www.opengroup.org/onlinepubs/009695399/} \\ \word{bs} \tab \href{http://www.opengroup.org/onlinepubs/009695399/functions/atan2f.html} {functions/atan2f.html} \word{bs} \textdf{If $y$ is +/-0 and $x$ is < 0, +/-pi shall be returned.} \\ \test[R]{ 0e -1e \word{FATAN2}}{ pi} \\ \test[R]{-0e -1e \word{FATAN2}}{-pi} \word{bs} \textdf{If $y$ is +/-0 and $x$ is > 0, +/-0 shall be returned.} \\ \test[R]{ 0e 1e \word{FATAN2}}{ 0e}\\ \test[R]{-0e 1e \word{FATAN2}}{-0e}\\ \word{bs} \textdf{If $y$ is < 0 and $x$ is +/-0, -pi/2 shall be returned.} \\ \test[R]{-1e 0e \word{FATAN2}}{-pi/2} \\ \test[R]{-1e -0e \word{FATAN2}}{-pi/2} \\ \word{bs} \textdf{If $y$ is > 0 and $x$ is +/-0, pi/2 shall be returned.} \\ \test[R]{ 1e 0e \word{FATAN2}}{pi/2} \\ \test[R]{ 1e -0e \word{FATAN2}}{pi/2} \\ TESTING Single UNIX 3 special values optional spec \word{bs} \textdf{Optional ISO C / single UNIX specs:} \word{bs} \textdf{If either $x$ or $y$ is NaN, a NaN shall be returned.} \\ \test[R]{NaN 1e \word{FATAN2}}{NaN}\\ \test[R]{ 1e NaN \word{FATAN2}}{NaN}\\ \test[R]{NaN NaN \word{FATAN2}}{NaN} \word{bs} \textdf{If $y$ is +/-0 and $x$ is -0, +/-pi shall be returned.} \\ \test[R]{ 0e -0e \word{FATAN2}}{ pi}\\ \test[R]{-0e -0e \word{FATAN2}}{-pi} \word{bs} \textdf{If $y$ is +/-0 and $x$ is +0, +/-0 shall be returned.} \\ \test[R]{ 0e 0e \word{FATAN2}}{+0e}\\ \test[R]{-0e 0e \word{FATAN2}}{-0e} \word{bs} \textdf{For finite values of +/-$y$ > 0, if $x$ is -Inf, +/-pi shall be returned.} \\ \test[R]{ 1e -Inf \word{FATAN2}}{ pi}\\ \test[R]{-1e -Inf \word{FATAN2}}{-pi} \word{bs} \textdf{For finite values of +/-$y$ > 0, if $x$ is +Inf, +/-0 shall be returned.} \\ \test[R]{ 1e +Inf \word{FATAN2}}{+0e}\\ \test[R]{-1e +Inf \word{FATAN2}}{-0e} \word{bs} \textdf{For finite values of $x$, if $y$ is +/-Inf, +/-pi/2 shall be returned.} \\ \test[R]{+Inf 1e \word{FATAN2}}{ pi/2}\\ \test[R]{+Inf -1e \word{FATAN2}}{ pi/2}\\ \test[R]{+Inf 0e \word{FATAN2}}{ pi/2}\\ \test[R]{+Inf -0e \word{FATAN2}}{ pi/2}\\ \test[R]{-Inf 1e \word{FATAN2}}{-pi/2}\\ \test[R]{-Inf -1e \word{FATAN2}}{-pi/2}\\ \test[R]{-Inf 0e \word{FATAN2}}{-pi/2}\\ \test[R]{-Inf -0e \word{FATAN2}}{-pi/2} \word{bs} \textdf{If $y$ is +/-Inf and $x$ is -Inf, +/-3pi/4 shall be returned.} \\ \test[R]{+Inf -Inf \word{FATAN2}}{ 3pi/4}\\ \test[R]{-Inf -Inf \word{FATAN2}}{-3pi/4} \word{bs} \textdf{If $y$ is +/-Inf and $x$ is +Inf, +/-pi/4 shall be returned.} \\ \test[R]{+Inf +Inf \word{FATAN2}}{ pi/4}\\ \test[R]{-Inf +Inf \word{FATAN2}}{-pi/4} verbose \word{@} \word[tools]{[IF]} \\ \tab \word{CR} \word{.p} \textdf{\#ERRORS:} ) \#errors \word{@} \word{d} \word{CR} \\ \word[tools]{[THEN]} \end{testing} \end{worddef} % --------------------------------------------------------- \begin{worddef}{1491}{FATANH}[f-a-tan-h] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the floating-point value whose hyperbolic tangent is \param{r_1}. An ambiguous condition exists if \param{r_1} is outside the range of -1E0 to 1E0. \end{worddef} \begin{worddef}{1493}{FCOS}[f-cos] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the cosine of the radian angle \param{r_1}. \end{worddef} \begin{worddef}{1494}{FCOSH}[f-cosh] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the hyperbolic cosine of \param{r_1}. \end{worddef} \newpage \begin{worddef}[FEd]{1513}{FE.{}}[f-e-dot] \item \stack{}{} \stack[F]{r}{} or \stack{r}{} Display, with a trailing space, the top number on the floating-point stack using engineering notation, where the significand is greater than or equal to 1.0 and less than 1000.0 and the decimal exponent is a multiple of three. An ambiguous condition exists if the value of \word[core]{BASE} is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer. \see \wref{core:BASE}{BASE}, \xref[12.3.2 Floating-point operations]{float:ops}, \wref{floating:REPRESENT}{REPRESENT}. \end{worddef} \begin{worddef}{1515}{FEXP}[f-e-x-p] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Raise $e$ to the power \param{r_1}, giving \param{r_2}. \end{worddef} \begin{worddef}{1516}{FEXPM1}[f-e-x-p-m-one] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Raise $e$ to the power \param{r_1} and subtract one, giving \param{r_2}. \see \rref{floating:FEXPM1}{}. \begin{rationale} % A.12.6.1.1516 FEXPM1 This function allows accurate computation when its arguments are close to zero, and provides a useful base for the standard exponential functions. Hyperbolic functions such as \textsf{sinh($x$)} can be efficiently and accurately implemented by using \word{FEXPM1}; accuracy is lost in this function for small values of $x$ if the word \word{FEXP} is used. An important application of this word is in finance; say a loan is repaid at 15\% per year; what is the daily rate? On a computer with single-precision (six decimal digit) accuracy: \begin{enumerate} \item[1.] Using \word{FLN} and \word{FEXP}: \word{FLN} of 1.15 = 0.139762, \\ divide by 365 = 3.82910E-4, \\ form the exponent using \word{FEXP} = 1.00038, and \\ subtract one (1) and convert to percentage = 0.038\%. \end{enumerate} Thus we only have two-digit accuracy. \begin{enumerate} \item[2.] Using \word{FLNP1} and \word{FEXPM1}: \word{FLNP1} of 0.15 = 0.139762, (this is the same value as in the first example, although with the argument closer to zero it may not be so) \\ divide by 365 = 3.82910E-4, \\ form the exponent and subtract one (1) using \word{FEXPM1} = 3.82983E-4, and \\ convert to percentage = 0.0382983\%. \end{enumerate} This calculation method allows the hyperbolic functions to be computed with six-digit accuracy. For example, \textsf{sinh} can be defined as: \begin{quote}\ttfamily \word[core]{:} \word{FSINH}~ \word[core]{p} r1 -{}- r2 ) \\ \tab \word{FEXPM1}~ \word{FDUP}~ \word{FDUP} 1.0E0 \word{F+}~ \word{F/}~ \word{F+}~ 2.0E0 \word{F/} \word[core]{;} \end{quote} \end{rationale} \end{worddef} % --------------------------------------------------------- \begin{worddef}{1517}{FFIELD:}[f-field-colon][X:structures] \item \stack{n_1 "name"}{n_2} Skip leading space delimiters. Parse \param{name} delimited by a space. \param{Offset} is the first float aligned value greater than or equal to \param{n_1}. \param{n_2 = offset + 1} float. Create a definition for \param{name} with the execution semantics given below. \execute[name] \stack{addr_1}{addr_2} Add the \param{offset} calculated during the compile-time action to \param{addr_1} giving the address \param{addr_2}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\ \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \rref{facility:FIELD:}{}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{1553}{FLN}[f-l-n] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the natural logarithm of \param{r_1}. An ambiguous condition exists if \param{r_1} is less than or equal to zero. \end{worddef} \begin{worddef}{1554}{FLNP1}[f-l-n-p-one] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the natural logarithm of the quantity \param{r_1} plus one. An ambiguous condition exists if \param{r_1} is less than or equal to negative one. \see \rref{floating:FLNP1}{}. \begin{rationale} % A.12.6.1.1554 FLNP1 This function allows accurate compilation when its arguments are close to zero, and provides a useful base for the standard logarithmic functions. For example, \word{FLN} can be implemented as: \begin{quote}\ttfamily \word[core]{:} \word{FLN} ~ 1.0E0 \word{F-} ~ \word{FLNP1} \word[core]{;} \end{quote} \see \rref{floating:FEXPM1}{FEXPM1}. \end{rationale} \end{worddef} \begin{worddef}{1557}{FLOG}[f-log] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the base-ten logarithm of \param{r_1}. An ambiguous condition exists if \param{r_1} is less than or equal to zero. \end{worddef} \begin{worddef}[FSd]{1613}{FS.{}}[f-s-dot] \item \stack{}{} \stack[F]{r}{} or \stack{r}{} Display, with a trailing space, the top number on the floating-point stack in scientific notation: \arg{significand}\arg{exponent} where: \begin{center} \begin{tabular}{r@{ \textsf{:=} }l} \arg{significand} & [\textbf{-}]\arg{digit}\textbf{.}\arg{digits0} \\ \arg{exponent} & \textbf{E}[\textbf{-}]\arg{digits} \end{tabular} \end{center} An ambiguous condition exists if the value of \word[core]{BASE} is not (decimal) ten or if the character string representation exceeds the size of the pictured numeric output string buffer. \see \wref{core:BASE}{BASE}, \xref[12.3.2 Floating-point operations]{float:ops}, \wref{floating:REPRESENT}{REPRESENT}. \end{worddef} \begin{worddef}{1614}{FSIN}[f-sine] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the sine of the radian angle \param{r_1}. \end{worddef} \begin{worddef}{1616}{FSINCOS}[f-sine-cos] \item \stack[F]{r_1}{r_2 r_3} or \stack{r_1}{r_2 r_3} \param{r_2} is the sine of the radian angle \param{r_1}. \param{r_3} is the cosine of the radian angle \param{r_1}. \see \rref{floating:FATAN2}{FATAN2}. \end{worddef} \vspace*{-2ex} \begin{worddef}{1617}{FSINH}[f-cinch] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the hyperbolic sine of \param{r_1}. \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1618}{FSQRT}[f-square-root] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the square root of \param{r_1}. An ambiguous condition exists if \param{r_1} is less than zero. \end{worddef} \vspace*{-0.5ex} \begin{worddef}{1625}{FTAN}[f-tan] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the tangent of the radian angle \param{r_1}. An ambiguous condition exists if $\cos(r_1)$ is zero. \end{worddef} \begin{worddef}{1626}{FTANH}[f-tan-h] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} \param{r_2} is the hyperbolic tangent of \param{r_1}. \end{worddef} % --------------------------------------------------------- \vspace*{-0.5ex} \begin{worddef}{1627}{FTRUNC}[f-trunc][X:ftrunc] \item \stack[F]{r_1}{r_2} or \stack{r_1}{r_2} Round \param{r_1} to an integral value using the ``round towards zero'' rule, giving \param{r_2}. \see \xref{float:ops}, \wref{floating:FROUND}{}, \wref{floating:FLOOR}{}. \begin{implement} \word{:} \word{FTRUNC} \word{p} r1 -{}- r2 ) \\ \tab[3.8] \word{FDUP} \word{F0=} \word{0=} \\ \tab \word{IF} \tab[1] \word{FDUP} \word{F0less} \\ \tab \word{IF} \tab[1] \word{FNEGATE} \word{FLOOR} \word{FNEGATE} \\ \tab \word{ELSE}\tab \word{FLOOR} \\ \tab \word{THEN} \\ \tab \word{THEN}\tab \word{;} \end{implement} \begin{testing} \texttt{SET-EXACT} \test{-0E \word{FTRUNC} \word{F0=}}{} \\ \test{-1E-9 \word{FTRUNC} \word{F0=}}{} \\ \test{-0.9E \word{FTRUNC} \word{F0=}}{} \\ \test{-1E 1E-5 F+ \word{FTRUNC} \word{F0=}}{} \\ \test[R]{0E \word{FTRUNC} }{ 0E } \\ \test[R]{1E-9 \word{FTRUNC} }{ 0E } \\ \test[R]{-1E -1E-5 F+ \word{FTRUNC} }{-1E } \\ \test[R]{3.14E \word{FTRUNC} }{ 3E } \\ \test[R]{3.99E \word{FTRUNC} }{ 3E } \\ \test[R]{4E \word{FTRUNC} }{ 4E } \\ \test[R]{-4E \word{FTRUNC} }{-4E } \\ \test[R]{-4.1E \word{FTRUNC} }{-4E } \end{testing} \end{worddef} % --------------------------------------------------------- \enlargethispage{6ex} \begin{worddef}{1628}{FVALUE}[f-value][X:fvalue] \item \stack[F]{r}{} \stack{"name"}{} or \stack{r "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{r}. \param{name} is referred to as a ``f-value''. \execute[name] \stack[F]{}{r} or \stack{}{r} Place \param{r} on the floating point stack. The value of \param{r} is that given when \param{name} was created, until the phrase ``\param{r} \word{TO} \param{name}'' is executed, causing a new value of \param{r} to be assigned to \param{name}. \runtime[\word{TO} \param{name}] \stack[F]{r}{} or \stack{r}{} Assign the value \param{r} to \param{name}. \see \xref{usage:parsing}, \wref{core:TO}{} \begin{implement} \dffamily The implementation of \word{FVALUE} requires detailed knowledge of the host implementation of \word{VALUE} and \word{TO}. \begin{quote}\ttfamily \word{VARIABLE} \%var \\ \word{:} \word{TO} 1 \%var \word{!} \word{;} \word{:} \word{FVALUE} \word{p} F: r -{}- ) \word{p} "name" -{}- ) \\ \tab \word{CREATE} F, \\ \tab \word{DOES} \%var \word{@} \word{IF} \word{F!} \word{ELSE} \word{F@} \word{THEN} \\ \tab[4] 0 \%var \word{!} \word{;} \word{:} \word{VALUE} \word{p} x "name" -{}- ) \\ \tab \word{CREATE} \word{,} \\ \tab \word{DOES} \%var \word{@} \word{IF} ~\word{!} \word{ELSE} ~\word{@} \word{THEN} \\ \tab[4] 0 \%var \word{!} \word{;} \end{quote} \end{implement} \begin{testing}\ttfamily \test{0e0 \word{FVALUE} Tval}{} \\ \test[R]{Tval}{0e0} \\ \test{1e0 \word{TO} Tval}{} \\ \test[R]{Tval}{1e0} \\[2ex] \word{:} setTval Tval \word{FSWAP} \word{TO} Tval \word{;} \\ \test[RR]{2e0 setTval Tval}{1e0 2e0} \\[2ex] \test{5e0 \word{TO} Tval}{} \\ \word{:} [execute] \word{EXECUTE} \word{;} \word{IMMEDIATE} \\ \test[R]{\word{'} Tval \word{]} [execute] \word{[}}{2e0} \end{testing} \end{worddef} % --------------------------------------------------------- \begin{worddef}[Ftilde]{1640}{F\tilde}[f-proximate] \item \stack{}{flag} \stack[F]{r_1 r_2 r_3}{} or \stack{r_1 r_2 r_3}{flag} If \param{r_3} is positive, \emph{flag} is true if the absolute value of (\param{r_1} minus \param{r_2}) is less than \param{r_3}. If \param{r_3} is zero, \emph{flag} is true if the implementation-dependent encoding of \param{r_1} and \param{r_2} are exactly identical (positive and negative zero are unequal if they have distinct encodings). If \param{r_3} is negative, \emph{flag} is true if the absolute value of (\param{r_1} minus \param{r_2}) is less than the absolute value of \param{r_3} times the sum of the absolute values of \param{r_1} and \param{r_2}. \see \rref{floating:Ftilde}{}. \begin{rationale} % A.12.6.1.1640 F\tilde This provides the three types of ``floating point equality'' in common use --- ``close'' in absolute terms, exact equality as represented, and ``relatively close''. \end{rationale} \end{worddef} \begin{worddef}{2035}{PRECISION} \item \stack{}{u} Return the number of significant digits currently used by \word{Fd}, \word{FEd}, or \word{FSd} as \param{u}. \end{worddef} % ========== x:stoftos ========== \begin{worddef}[StoF]{2175}{S>F}[S to F][X:stoftos] \item \stack{n}{} \stack[F]{}{r} or \stack{n}{r} \param{r} is the floating-point equivalent of the single-cell value \param{n}. An ambiguous condition exists if \param{n} can not be precisely represented as a floating-point value. \see \wref{floating:FtoS}{F>S}. \begin{implement} \word{:} \word{StoF} \word{p} n -{}- r ) \\ \tab \word{StoD} \word{DtoF} \\ \word{;} \end{implement} \end{worddef} % ============================== \begin{worddef}{2200}{SET-PRECISION} \item \stack{u}{} Set the number of significant digits currently used by \word{Fd}, \word{FEd}, or \word{FSd} to \param{u}. \end{worddef} \begin{worddef}{2202}{SF!}[s-f-store] \item \stack{sf-addr}{} \stack[F]{r}{} or \stack{r sf-addr}{} Store the floating-point number \param{r} as a 32-bit IEEE single-precision number at \param{sf-addr}. If the significand of the internal representation of \param{r} has more precision than the IEEE single-precision format, it will be rounded using the ``round to nearest'' rule. An ambiguous condition exists if the exponent of \param{r} is too large to be accommodated by the IEEE single-precision format. \see \xref[12.3.1.1 Addresses]{float:addr}, \xref[12.3.2 Floating-point operations]{float:ops}. \end{worddef} \begin{worddef}{2203}{SF@}[s-f-fetch] \item \stack{sf-addr}{} \stack[F]{}{r} or \stack{sf-addr}{r} Fetch the 32-bit IEEE single-precision number stored at \param{sf-addr} to the floating-point stack as \param{r} in the internal representation. If the IEEE single-precision significand has more precision than the internal representation, it will be rounded to the internal representation using the ``round to nearest'' rule. An ambiguous condition exists if the exponent of the IEEE single-precision representation is too large to be accommodated by the internal representation. \see \xref[12.3.1.1 Addresses]{float:addr}, \xref[12.3.2 Floating-point operations]{float:ops}. \end{worddef} \begin{worddef}{2204}{SFALIGN}[s-f-align] \item \stack{}{} If the data-space pointer is not single-float aligned, reserve enough data space to make it so. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} \begin{worddef}{2206}{SFALIGNED}[s-f-aligned] \item \stack{addr}{sf-addr} \param{sf-addr} is the first single-float-aligned address greater than or equal to \param{addr}. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{2206}[40]{SFFIELD:}[s-f-field-colon][X:structures] \item \stack{n_1 "name"}{n_2} Skip leading space delimiters. Parse \param{name} delimited by a space. \param{Offset} is the first single-float aligned value greater than or equal to \param{n_1}. \param{n_2 = offset + 1} single-float. Create a definition for \param{name} with the execution semantics given below. \execute[name] \stack{addr_1}{addr_2} Add the \param{offset} calculated during the compile-time action to \param{addr_1} giving the address \param{addr_2}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\ \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \rref{facility:FIELD:}{}. \end{worddef} % --------------------------------------------------------- \begin{worddef}{2207}{SFLOAT+}[s-float-plus] \item \stack{sf-addr_1}{sf-addr_2} Add the size in address units of a 32-bit IEEE single-precision number to \param{sf-addr_1}, giving \param{sf-addr_2}. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef} \begin{worddef}{2208}{SFLOATS}[s-floats] \item \stack{n_1}{n_2} \param{n_2} is the size in address units of \param{n_1} 32-bit IEEE single-precision numbers. \see \xref[12.3.1.1 Addresses]{float:addr}. \end{worddef}