Commit e3dff8e0 authored by pknaggs's avatar pknaggs
Browse files

Added Ambigous conditions for x:substitute 

Replaced F94 with F12
Revised rational for /STRING, CMOVE, CMOVE>
Removed rational for COMPARE, SEARCH
Added numbers for REPLACES, SUBSTITUTE, UNESCAPE
Revised definition/rational of SUBSTITUTE (x:substitute)
parent 76497382

string.tex

+73 −49
Original line number Diff line number Diff line
@@ -15,45 +15,41 @@ None. 
\section{Additional documentation requirements} % 17.4

\label{string:document}



\remove{x:substitute}{None.}



\subsection{System documentation}

\subsubsection{Implementation-defined options}

\begin{itemize}

\item \place{x:substitute}{no additional options.}

\item no additional options.

\end{itemize}



\subsubsection{Ambiguous conditions}

\begin{itemize}

\item \place{x:substitute}{The substitution cannot be created (\word{REPLACES});}

\item \place{x:substitute}{The name of a substitution contains the `\texttt{\%}' delimiter character (\word{REPLACES});}

\item \place{x:substitute}{Result of a substitution is too long to fit into the given buffer (\word{SUBSTITUTE} and \word{UNESCAPE});}

\item \place{x:substitute}{Source and destination buffers for \word{SUBSTITUTE} are the same.}

\item The substitution cannot be created (\word{REPLACES});

\item The name of a substitution contains the `\texttt{\%}' delimiter character (\word{REPLACES});

\item Result of a substitution is too long to fit into the given buffer (\word{SUBSTITUTE} and \word{UNESCAPE});

\item Source and destination buffers for \word{SUBSTITUTE} are the same.

\end{itemize}



\subsubsection{Other system documentation}

\begin{itemize}

\item \place{x:substitute}{no additional requirements.}

\item no additional requirements.

\end{itemize}



\subsection{Program documentation}



\subsubsection{Environmental dependencies}

\begin{itemize}

\item \place{x:substitute}{no additional dependencies.}

\item no additional dependencies.

\end{itemize}



\subsubsection{Other program documentation}

\begin{itemize}

\item \place{x:substitute}{no additional requirements.}

\item no additional requirements.

\end{itemize}



\section{Compliance and labeling} % 17.5



\subsection{Compliance and labeling} % 17.5.1



\cbstart\patch{F94}

\subsection[Forth systems]{ANS\strike{3.5}{25} Forth systems} % 17.5.1

\cbstart\patch{F12}

\subsection[Forth-\snapshot systems]{Forth-\snapshot\strike{-1}{25} systems} % 17.5.1

\cbend



The phrase ``Providing the String word set'' shall be appended to
@@ -68,8 +64,8 @@ The phrase ``Providing the String Extensions word set'' shall be 
appended to the label of any Standard System that provides all of

the String and String Extensions word sets.



\cbstart\patch{F94}

\subsection[Forth programs]{ANS\strike{3.5}{25} Forth programs} % 17.5.2

\cbstart\patch{F12}

\subsection[Forth-\snapshot programs]{Forth-\snapshot\strike{-1}{25} programs} % 17.5.2

\cbend



The phrase ``Requiring the String word set'' shall be appended to
@@ -126,11 +122,14 @@ to provide all of the String and String Extensions word sets. 


	\begin{rationale} % A.17.6.1.0245 /STRING

		\word{/STRING} is used to remove or add characters relative

		to the ``left'' end of the character string. Positive values

		to the \replace{ed12}{``left'' end of}{ current position in} the character string. Positive values

		of \param{n} will exclude characters from the string while

		negative values of \param{n} will include characters to the

		left of the string. \word{/STRING} is a natural factor of

		\word[core]{WORD} and commonly available.

		left of the string. \remove{ed12}{\word{/STRING} is a natural factor of

		\word[core]{WORD} and commonly available.}



		\place{ed12}{\word{Sq} ABC" 2 \word{/STRING} \word{2DUP} \word{TYPE} \word{bs} outputs ``C''} \\

		\place{ed12}{-1 \word{/STRING} \word{TYPE} \word{bs} outputs ``BC''}

	\end{rationale}



	\begin{testing}
@@ -174,15 +173,15 @@ to provide all of the String and String Extensions word sets. 
		\param{c-addr_2} is less than the quantity \param{c-addr_1 u}

		\word[core]{CHARS} \word[core]{+}), memory propagation occurs.



		Typical use: Assume a character string at address

		\remove{ed12}{Typical use: }Assume a character string at address

		100: ``ABCD''. Then after

		\begin{quote}\ttfamily

			100 \word[core]{DUP} ~ \word[core]{CHAR+} ~ 3 \word{CMOVE}

		\end{quote}

		the string at address 100 is ``AAAA''.



		Rationale for \word{CMOVE} and \word{CMOVEtop} follows

		\word[core]{MOVE}.

		\replace{ed12}{Rationale for \word{CMOVE} and \word{CMOVEtop} follows

		\word[core]{MOVE}.}{See \rref{core:MOVE}{}.}

	\end{rationale}

\end{worddef}
@@ -204,13 +203,15 @@ to provide all of the String and String Extensions word sets. 
		quantity \param{c-addr_1 u} \word[core]{CHARS}

		\word[core]{+}), memory propagation	occurs.



		Typical use: Assume a character string at address

		\remove{ed12}{Typical use: }Assume a character string at address

		100: ``ABCD''. Then after

		\begin{quote}\ttfamily

			100 \word[core]{DUP} \word[core]{CHAR+} \word[core]{SWAP}

			3 \word{CMOVEtop}

		\end{quote}

		the string at address 100 is ``DDDD''.



		\place{ed12}{See \rref{core:MOVE}{}.}

	\end{rationale}

\end{worddef}
@@ -232,13 +233,14 @@ to provide all of the String and String Extensions word sets. 
	numeric value than the corresponding character in the string

	specified by \param{c-addr_2 u_2} and one (1) otherwise.



\see \rref{string:COMPARE}{}.

\see \remove{ed12}{\rref{string:COMPARE}{}.}



	\begin{rationale} % A.17.6.1.0935 COMPARE

\remove{ed12}{%

		Existing Forth systems perform string comparison operations

		using words that differ in spelling, input and output

		arguments, and case sensitivity. One in widespread use

		was chosen.

		was chosen.}

	\end{rationale}



	\begin{testing}\ttfamily
@@ -281,13 +283,14 @@ to provide all of the String and String Extensions word sets. 
	match and \param{c-addr_3} is \param{c-addr_1} and \param{u_3}

	is \param{u_1}.



\see \rref{string:SEARCH}{}.

\see \remove{ed12}{\rref{string:SEARCH}{}.}



	\begin{rationale} % A.17.6.1.2191 SEARCH

\remove{ed12}{%

		Existing Forth systems perform string searching operations

		using words that differ in spelling, input and output

		arguments, and case sensitivity. One in widespread use was

		chosen.

		chosen.}

	\end{rationale}



	\begin{testing}
@@ -351,9 +354,7 @@ to provide all of the String and String Extensions word sets. 
\subsection{String extension words} % 17.6.2

\extended



\remove{x:substitute}{None.}



\begin{worddef*}{}{REPLACES}[][x:substitute]

\begin{worddef}{2141}{REPLACES}[][x:substitute]

\item \stack{c-addr_1 u_1 c-addr_2 u_2}{}



	Set the string \param{c-addr_1 u_1} as the text to substitute for
@@ -435,37 +436,54 @@ to provide all of the String and String Extensions word sets. 
		\tab place \tab[8] \word{bs} \textdf{copy as counted string} \\

		\word{;}

	\end{implement}

\end{worddef*}

\end{worddef}



\begin{worddef*}{}{SUBSTITUTE}[][x:substitute]

\begin{worddef}{2255}{SUBSTITUTE}[][x:substitute]

\item \stack{c-addr_1 u_1 c-addr_2 u_2}{c-addr_2 u_3 n}



	Perform substitution on the string \param{c-addr_1 u_1} placing the

	result at string \param{c-addr_2 u_2}, returning \param{c-addr_2} and

	\param{u_3}, the length of the resulting string.

	result at string

\cbstart\patch{x:subtitute}

\param{c-addr_2 u_{\sout{2} \uline{3}}}, %

\sout{returning }\param{\sout{c-addr}_{\sout{2}}}\sout{ and }\param{\sout{u}_{\sout{3}}}\sout{,}

\cbend

	the length of the resulting string.

	An ambiguous condition occurs if the resulting string will not fit into

	\param{c-addr_2 u_2} or if \param{c-addr_2} is the same as \param{c-addr_1}.

	The return value \param{n} is positive on success and indicates the number

	of substitutions made.

	A negative value for \param{n} indicates that an error occurred, leaving

	\param{c-addr_2 u_3} undefined.  Substitution occurs from the

	start of \param{c-addr_1} in one pass and is non-recursive.

	\param{c-addr_2 u_3} undefined.

\place{x:subtitute}{Negative values of \param{n} are implementation defined except for

	values in table~\xref{table:throw}.}



	When a substitution name, surrounded by `\texttt{\%}' (ASCII \$25) delimiters

	Substitution occurs

\place{x:subtitute}{left-to-right}

	from the start of \param{c-addr_1} in one pass and is non-recursive.



	When \replace{x:subtitute}{a}{ text of a potential} substitution name, surrounded by `\texttt{\%}' (ASCII \$25) delimiters

	is encountered by \word{SUBSTITUTE}, the following occurs:



	\begin{enumerate}

	\item If the name is null, a single delimiter character is substituted,

		i.e., \texttt{\%\%} is replaced by \texttt{\%}.

	\item If the name is null, a single delimiter character is \replace{x:subtitute}{substituted}{ passed to the output},

		i.e., \texttt{\%\%} is replaced by \texttt{\%}. \place{x:subtitute}{The current number of substitutions is not changed.}



	\item If the name is a valid substitution name, the leading and trailing

		delimiter characters and the enclosed substitution name are replaced by

		the substitution text.

	\item If the \replace{x:subtitute}{name}{ text} is a valid substitution name \place{x:subtitute}{acceptable to \wref{string:REPLACES}{}},

		the leading and trailing delimiter characters and the enclosed substitution name are replaced by

		the substitution text.  \place{x:subtitute}{The current number of substitutions is incremented.}



	\item If the name is not a valid substitution name, the name with leading

	\item If the \replace{x:subtitute}{name}{ text} is not a valid substitution name, the name with leading

		and trailing delimiters is passed unchanged to the output.

		\place{x:subtitute}{The current number of substitutions is not changed.}



	\item \place{x:subtitute}{Parsing of the input string resumes after the trailing delimiter.}

	\end{enumerate}



\place{x:subtitute}{%

	If after processing any pairs of delimiters, the residue of the input string contains

	a single delimiter, the residue is passed unchanged to the output.

}



\see \wref{string:REPLACES}{}, \wref{string:UNESCAPE}{}, \rref{string:SUBSTITUTE}{}.



	\begin{rationale}
@@ -536,12 +554,16 @@ to provide all of the String and String Extensions word sets. 
}

\makeatother



\cbstart\patch{x:subtitute}

		\begin{quote}\ttfamily

			\begin{tabbing}

				\word{Sq} \pdate" \= \word{Sq} date" \word{REPLACES} \\

				\word{Sq} \ptime" \> \word{Sq} time" \word{REPLACES}

				\uline{\word{:} date \word{Sq} \pdate" \word{;}} \\

				\uline{\word{:} time \word{Sq} \ptime" \word{;}} \\

				\sout{\word{Sq} \pdate"} \uline{date}\ \= \word{Sq} date" \word{REPLACES} \\

				\sout{\word{Sq} \ptime"} \uline{time}\ \> \word{Sq} time" \word{REPLACES}

			\end{tabbing}

		\end{quote}

\cbend



		The substitution name ``date'' is defined to be replaced with the string

		``\pdate'' and ``time'' to be replaced with ``\ptime''.  Thus
@@ -554,7 +576,9 @@ to provide all of the String and String Extensions word sets. 
		As the substitution name ``currencyvalue'' has not been defined, it is

		left unchanged in the resulting string.



		The return value \param{n} is positive \{\{(0 \ldots +n\}\} on success

		The return value \param{n} is positive

\replace{ed12}{ \{\{(0 \ldots +n\}\}}{\{0 {\ldots} +n\}}

		on success

		and indicates the number of substitutions made.  In the above example,

		this would be two.  A negative value indicates that an error occurred.

		As substitution is non-recursive, the return value could be used to
@@ -699,9 +723,9 @@ to provide all of the String and String Extensions word sets. 
		\word{:} sub6 \word{Sq} aaa\%bbb" \word{;} \\

		\test{sub5 subbuff 30 \word{SUBSTITUTE} \word{ROT} \word{ROT} sub6 \word{COMPARE}}{0 0} \\

	\end{testing}

\end{worddef*}

\end{worddef}



\begin{worddef*}{}{UNESCAPE}[][x:substitute]

\begin{worddef}{2375}{UNESCAPE}[][x:substitute]

\item \stack{c-addr_1 u_1 c-addr_2}{c-addr_2 u_2}



	Replace each `\texttt{\%}' character in the input string
@@ -733,5 +757,5 @@ to provide all of the String and String Extensions word sets. 


		\test{sub6 subbuff \word{UNESCAPE} sub5 \word{COMPARE}}{0}

	\end{testing}

\end{worddef*}

\end{worddef}

\endinput