Thread: [Win32forth-cvs] win32forth/doc p-numconv.htm,NONE,1.1 p-advanced.htm,1.1,1.2

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/win32forth/win32forth/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16146/doc

Modified Files:
	p-advanced.htm 
Added Files:
	p-numconv.htm 
Log Message:
arm: added documentation for number conversion routines

Index: p-advanced.htm
===================================================================
RCS file: /cvsroot/win32forth/win32forth/doc/p-advanced.htm,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** p-advanced.htm	21 Dec 2004 00:18:55 -0000	1.1
--- p-advanced.htm	16 May 2005 20:56:24 -0000	1.2
***************
*** 44,47 ****
--- 44,48 ----
    <li><a href="p-using-if.htm">Using -IF</a></li>
    <li><a href="p-structures.htm">Structures in Win32Forth</a></li>
+   <li><a href="p-numconv.htm">Number Conversion</a></li>
  </ul>
  <hr>

--- NEW FILE: p-numconv.htm ---
<html>

<head>
<meta http-equiv="Content-Language" content="en-gb">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Win32Forth</title>
<style>
<!--
h1           { font-family: Tahoma; font-size: 24pt; font-weight: bold }
h2           { font-family: Tahoma; font-size: 18pt; font-weight: bold }
span.MacroChar
	{font-family:"Courier";
	font-size:10pt}
-->
</style>
</head>

<body>

<h1 align="center"><img border="0" src="FORTHPRO.gif" width="32" height="32">&nbsp;&nbsp; 
Win32Forth</h1>
<h2 align="center"><font face="Tahoma">
<a href="mailto:win...@ya...?subject=DOC: Doc error in $Id: p-numconv.htm,v 1.1 2005/05/16 20:56:24 alex_mcdonald Exp $">
<img border="0" src="TELLUS.gif" align="left" width="32" height="32"></a></font>Number 
Conversion</h2>
<h2>Introduction</h2>
<p>Part of the job of the interpreter in Forth is to look up words in the 
dictionary. When a word is not found, the interpreter attempts to convert the 
word to a number and put it on the stack. Win32Forth has a simple but effective 
number conversion system that allows pluggable words to process numbers. Several 
number conversions are provided with the installed system.</p>
<h2>Standard number conversions</h2>
<p><a href="dpans/DPANS3.HTM#3.2.1.2">Standard numbers</a> and
<a href="dpans/DPANS8.HTM">double numbers</a> (base 2 through 36) are supported, 
and the maximum values for each is specified in <span class="MacroChar">
<a href="../src/ENVIRON.F">ENVIRON.F</a></span> (environment word set). 
Optionally, numbers may be prefixed with a negative sign (-).
<a href="dpans/DPANS12.HTM#12.3.7">Floating point numbers</a> are supported in 
base 10 (<span class="MacroChar">DECIMAL</span>).</p>
<h2>Extended numbers</h2>
<p>Win32Forth supports a set of extended numbers, commonly supported by Forths 
such as gforth.</p>
<h3>Base modifiers % &amp; $</h3>
<h4>Binary % modifier (in any base)</h4>
<p>Binary numbers can be entered in any base by prefixing the number with a % 
sign, and an optional negative sign (-) either before or after the %. The 
following are valid binary numbers with their equivalent in decimal; </p>
<blockquote>
<p><span class="MacroChar">%0 (0) <br>
%10101 (21) <br>
-%01 (-1)<br>
%-101 (-5)</span></p>
</blockquote>
<h4>Decimal &amp; modifier (in any base)</h4>
<p>Decimal numbers can be entered in any base by prefixing the number with an &amp; 
sign, and an optional negative sign (-) either before or after the &amp;. The 
following are valid decimal numbers; </p>
<blockquote>
<p><span class="MacroChar">&amp;193<br>
&amp;-22<br>
-&amp;35</span></p>
</blockquote>
<h4>Hex $ modifier (in any base)</h4>
<p>Hex numbers can be entered in any base by prefixing the number with a $ sign, 
and an optional negative sign (-) either before or after the $. The following 
are valid hex numbers with their equivalent in decimal; </p>
<blockquote>
  <p><span class="MacroChar">$123 (291)<br>
  $FFFFFFFF (-1)<br>
  $-245 (-581)<br>
  -$34 (-52)</span></p>
</blockquote>
<p>Additionally, any hex string followed with an h or H, or the string 0x 
followed by a hex string are interpreted as hex numbers. The hex string can be 
prefixed with an optional negative sign (-). The following are valid hex numbers 
with their equivalent in decimal; </p>
<blockquote>
  <p><span class="MacroChar">0x123 (291)<br>
  FFFFFFFFh (-1)<br>
  -245h (-581)<br>
  -0x34 (-52)<br>
  0x-34 (-52)</span></p>
</blockquote>
<h3>Floating point (in any base)</h3>
<p>Floating point numbers can be entered in any base by prefixing the number 
with the F# word (not a leading string, but a separate word). For example;
<span class="MacroChar">F# 1.0e-2</span></p>
<h3>Dotted IP notation (a.b.c.d)</h3>
<p>IP addresses of the form a.b.c.d can be entered in any base. However, they 
must not be signed, and they must not have a leading base modifier (as in %, $ 
or &amp;). </p>
<h2>Adding your own conversion words</h2>
<p>The chain number conversion technique allow number conversion to be easily 
extended to support additional forms of number conversion. </p>
<p>Win32Forth uses <a href="p-chains.htm">chains</a> to provide a pluggable 
number conversion system. The number conversion chain is called
<span class="MacroChar">number?-chain</span>. Each number conversion routine on 
the chain is sent a string<span class="MacroChar"> ( addr len )</span> and can 
attempt to convert the number. If the conversion fails the word performs a
<span class="MacroChar">-1 THROW</span> to indicate that it can't convert the 
string; the next word is then tried until success or the chain is exhausted. If 
the chain is exhausted, then a <span class="MacroChar">-13 THROW</span> 
(undefined) is executed.<br>
<br>
If conversion succeeds, then a double number <b>must</b> be returned. If the 
number is truly a double, then set the <span class="MacroChar">DOUBLE?</span> 
flag to true, otherwise the number will be considered a single, and the high 
order cell will be discarded. For numbers with a decimal point, the value
<span class="MacroChar">DP-LOCATION</span> can be set to indicate where it's 
located in the input string. If desired, the flag <span class="MacroChar">-VE-NUM?</span> 
can be set to true; the number will be negated before it is used. This is to 
avoid keeping flags to indicate that the sign has been detected in each routine 
separately.<br>
<br>
Floating point numbers are returned in the floating point stack; there is no 
return value, and the variable <span class="MacroChar">FLOAT?</span> is set. See
<a href="../src/FLOAT.F">FLOAT.F</a> for details. <b>NOTE</b> - even floating 
point routines must return a double value; it's ignored and dropped if
<span class="MacroChar">FLOAT?</span> is set.<br>
<br>
The stack effects of any number conversion word must be <span class="MacroChar">
( addr len -- d )</span> where <span class="MacroChar">addr len</span> is the 
input string, and <span class="MacroChar">d </span>is the double number output. 
If you can't convert your form of string input, then execute a
<span class="MacroChar">-1 THROW</span>. To install your routine, you will need 
to specify</p>
<blockquote>
  <p><span class="MacroChar">number?-chain chain-add 
  &lt;your-number-conversion-word&gt;</span></p>
</blockquote>
<p>to add your word to the end of the chain. Your word will be called after all 
the built-in number conversions have been executed; to be executed before any of 
the standard words, specify</p>
<blockquote>
  <p><span class="MacroChar">number?-chain chain-add-before 
  &lt;your-number-conversion-word&gt;</span></p>
</blockquote>

<hr>
<p>Document $Id: p-numconv.htm,v 1.1 2005/05/16 20:56:24 alex_mcdonald Exp $</p>

</body>

</html>

Thread: [Win32forth-cvs] win32forth/doc p-numconv.htm,NONE,1.1 p-advanced.htm,1.1,1.2

win32forth-cvs