< The optional Block word set

The optional Exception word set >

8 The optional Double-Number word set

8.1 Introduction

Sixteen-bit Forth systems often use double-length numbers. However, many Forths on small embedded systems do not, and many users of Forth on systems with a cell size of 32 bits or more find that the use of double-length numbers is much diminished. Therefore, the words that manipulate double-length entities have been placed in this optional word set.

8.2 Additional terms and notation

None.

8.3 Additional usage requirements

8.3.1 Text interpreter input number conversion

When the text interpreter processes a number, except a <cnum>, that is immediately followed by a decimal point and is not found as a definition name, the text interpreter shall convert it to a double-cell number.

For example, entering DECIMAL 1234 leaves the single-cell number 1234 on the stack, and entering DECIMAL 1234. leaves the double-cell number 1234 0 on the stack.

See: 3.4.1.3 Text interpreter input number conversion.

8.4 Additional documentation requirements

8.4.1 System documentation

8.4.1.1 Implementation-defined options

no additional requirements.

8.4.1.2 Ambiguous conditions

d outside range of n in 8.6.1.1140 D>S.

8.4.1.3 Other system documentation

no additional requirements.

8.4.2 Program documentation

no additional requirements.

8.5 Compliance and labeling

8.5.1 Forth-2012 systems

The phrase "Providing the Double-Number word set" shall be appended to the label of any Standard System that provides all of the Double-Number word set.

The phrase "Providing name(s) from the Double-Number Extensions word set" shall be appended to the label of any Standard System that provides portions of the Double-Number Extensions word set.

The phrase "Providing the Double-Number Extensions word set" shall be appended to the label of any Standard System that provides all of the Double-Number and Double-Number Extensions word sets.

8.5.2 Forth-2012 programs

The phrase "Requiring the Double-Number word set" shall be appended to the label of Standard Programs that require the system to provide the Double-Number word set.

The phrase "Requiring name(s) from the Double-Number Extensions word set" shall be appended to the label of Standard Programs that require the system to provide portions of the Double-Number Extensions word set.

The phrase "Requiring the Double-Number Extensions word set" shall be appended to the label of Standard Programs that require the system to provide all of the Double-Number and Double-Number Extensions word sets.

8.6 Glossary

8.6.1 Double-Number words

2CONSTANT

two-constant

DOUBLE

( x₁ x₂ "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name with the execution semantics defined below.

name is referred to as a "two-constant".

name Execution

( -- x₁ x₂ )

Place cell pair x₁ x₂ on the stack.

See

3.4.1 Parsing, A.8.6.1.0360 2CONSTANT.

Typical use: x1 x2 2CONSTANT name

T{ 1 2 2CONSTANT 2c1 -> }T
T{ 2c1 -> 1 2 }T

T{ : cd1 2c1 ; -> }T
T{ cd1 -> 1 2 }T

T{ : cd2 2CONSTANT ; -> }T
T{ -1 -2 cd2 2c2 -> }T
T{ 2c2 -> -1 -2 }T

T{ 4 5 2CONSTANT 2c3 IMMEDIATE 2c3 -> 4 5 }T
T{ : cd6 2c3 2LITERAL ; cd6 -> 4 5 }T

2LITERAL

two-literal

DOUBLE

Interpretation

Interpretation semantics for this word are undefined.

Compilation

( x₁ x₂ -- )

Append the run-time semantics below to the current definition.

Run-time

( -- x₁ x₂ )

Place cell pair x₁ x₂ on the stack.

See

A.8.6.1.0390 2LITERAL.

Typical use: : X ... [ x1 x2 ] 2LITERAL ... ;

T{ : cd1 [ MAX-2INT ] 2LITERAL ; -> }T
T{ cd1 -> MAX-2INT }T

T{ 2VARIABLE 2v4 IMMEDIATE 5 6 2v4 2! -> }T
T{ : cd7 2v4 [ 2@ ] 2LITERAL ; cd7 -> 5 6 }T
T{ : cd8 [ 6 7 ] 2v4 [ 2! ] ; 2v4 2@ -> 6 7 }T

2VARIABLE

two-variable

DOUBLE

( "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name with the execution semantics defined below. Reserve two consecutive cells of data space.

name is referred to as a "two-variable".

name Execution

( -- a-addr )

a-addr is the address of the first (lowest address) cell of two consecutive cells in data space reserved by 2VARIABLE when it defined name. A program is responsible for initializing the contents.

See

3.4.1 Parsing, 6.1.2410 VARIABLE, A.8.6.1.0440 2VARIABLE.

Typical use: 2VARIABLE name

T{ 2VARIABLE 2v1 -> }T
T{ 0. 2v1 2! ->    }T
T{    2v1 2@ -> 0. }T
T{ -1 -2 2v1 2! ->       }T
T{       2v1 2@ -> -1 -2 }T

T{ : cd2 2VARIABLE ; -> }T
T{ cd2 2v2 -> }T
T{ : cd3 2v2 2! ; -> }T
T{ -2 -1 cd3 -> }T
T{ 2v2 2@ -> -2 -1 }T

T{ 2VARIABLE 2v3 IMMEDIATE 5 6 2v3 2! -> }T
T{ 2v3 2@ -> 5 6 }T

D+

d-plus

DOUBLE

( d₁ | ud₁ d₂ | ud₂ -- d₃ | ud₃ )

Add d₂ | ud₂ to d₁ | ud₁, giving the sum d₃ | ud₃.

T{ 0.  5. D+ -> 5. }T                         \ small integers
T{ -5.  0. D+ -> -5. }T
T{ 1.  2. D+ -> 3. }T
T{ 1. -2. D+ -> -1. }T
T{ -1.  2. D+ -> 1. }T
T{ -1. -2. D+ -> -3. }T
T{ -1.  1. D+ -> 0. }T

T{ 0  0  0  5 D+ -> 0  5 }T                  \ mid range integers
T{ -1  5  0  0 D+ -> -1  5 }T
T{ 0  0  0 -5 D+ -> 0 -5 }T
T{ 0 -5 -1  0 D+ -> -1 -5 }T
T{ 0  1  0  2 D+ -> 0  3 }T
T{ -1  1  0 -2 D+ -> -1 -1 }T
T{ 0 -1  0  2 D+ -> 0  1 }T
T{ 0 -1 -1 -2 D+ -> -1 -3 }T
T{ -1 -1  0  1 D+ -> -1  0 }T

T{ MIN-INT 0 2DUP D+ -> 0 1 }T
T{ MIN-INT S>D MIN-INT 0 D+ -> 0 0 }T

T{ HI-2INT       1. D+ -> 0 HI-INT 1+ }T    \ large double integers
T{ HI-2INT     2DUP D+ -> 1S 1- MAX-INT }T
T{ MAX-2INT MIN-2INT D+ -> -1. }T
T{ MAX-2INT  LO-2INT D+ -> HI-2INT }T
T{ LO-2INT     2DUP D+ -> MIN-2INT }T
T{ HI-2INT MIN-2INT D+ 1. D+ -> LO-2INT }T

D-

d-minus

DOUBLE

( d₁ | ud₁ d₂ | ud₂ -- d₃ | ud₃ )

Subtract d₂ | ud₂ from d₁ | ud₁, giving the difference d₃ | ud₃.

T{ 0.  5. D- -> -5. }T              \ small integers
T{ 5.  0. D- -> 5. }T
T{ 0. -5. D- -> 5. }T
T{ 1.  2. D- -> -1. }T
T{ 1. -2. D- -> 3. }T
T{ -1.  2. D- -> -3. }T
T{ -1. -2. D- -> 1. }T
T{ -1. -1. D- -> 0. }T
T{ 0  0  0  5 D- -> 0 -5 }T       \ mid-range integers
T{ -1  5  0  0 D- -> -1  5 }T
T{ 0  0 -1 -5 D- -> 1  4 }T
T{ 0 -5  0  0 D- -> 0 -5 }T
T{ -1  1  0  2 D- -> -1 -1 }T
T{ 0  1 -1 -2 D- -> 1  2 }T
T{ 0 -1  0  2 D- -> 0 -3 }T
T{ 0 -1  0 -2 D- -> 0  1 }T
T{ 0  0  0  1 D- -> 0 -1 }T

T{ MIN-INT 0 2DUP D- -> 0. }T
T{ MIN-INT S>D MAX-INT 0D- -> 1 1s }T
T{ MAX-2INT max-2INT D- -> 0. }T    \ large integers
T{ MIN-2INT min-2INT D- -> 0. }T
T{ MAX-2INT  hi-2INT D- -> lo-2INT DNEGATE }T
T{ HI-2INT  lo-2INT D- -> max-2INT }T
T{ LO-2INT  hi-2INT D- -> min-2INT 1. D+ }T
T{ MIN-2INT min-2INT D- -> 0. }T
T{ MIN-2INT  lo-2INT D- -> lo-2INT }T

D.

d-dot

DOUBLE

( d -- )

Display d in free field format.

See F.8.6.1.1070 D.R.

D.R

d-dot-r

DOUBLE

( d n -- )

Display d right aligned in a field n characters wide. If the number of characters required to display d is greater than n, all digits are displayed with no leading spaces in a field as wide as necessary.

See

A.8.6.1.1070 D.R.

In D.R, the "R" is short for RIGHT.

MAX-2INT 71 73 M*/ 2CONSTANT dbl1
MIN-2INT 73 79 M*/ 2CONSTANT dbl2

: d>ascii ( d -- caddr u )
DUP >R <# DABS #S R> SIGN #> ( -- caddr1 u )
HERE SWAP 2DUP 2>R CHARS DUP ALLOT MOVE 2R>
;

dbl1 d>ascii 2CONSTANT "dbl1"
dbl2 d>ascii 2CONSTANT "dbl2"

: DoubleOutput
   CR ." You should see lines duplicated:" CR
   5 SPACES "dbl1" TYPE CR
   5 SPACES dbl1 D. CR
   8 SPACES "dbl1" DUP >R TYPE CR
   5 SPACES dbl1 R> 3 + D.R CR
   5 SPACES "dbl2" TYPE CR
   5 SPACES dbl2 D. CR
   10 SPACES "dbl2" DUP >R TYPE CR
   5 SPACES dbl2 R> 5 + D.R CR
;

T{ DoubleOutput -> }T

D0<

d-zero-less

DOUBLE

( d -- flag )

flag is true if and only if d is less than zero.

T{                0. D0< -> <FALSE> }T
T{                1. D0< -> <FALSE> }T
T{ MIN-INT        0 D0< -> <FALSE> }T
T{        0  MAX-INT D0< -> <FALSE> }T
T{          MAX-2INT D0< -> <FALSE> }T
T{               -1. D0< -> <TRUE> }T
T{          MIN-2INT D0< -> <TRUE> }T

D0=

d-zero-equals

DOUBLE

( xd -- flag )

flag is true if and only if xd is equal to zero.

T{               1. D0= -> <FALSE> }T
T{ MIN-INT        0 D0= -> <FALSE> }T
T{         MAX-2INT D0= -> <FALSE> }T
T{      -1  MAX-INT D0= -> <FALSE> }T
T{               0. D0= -> <TRUE> }T
T{              -1. D0= -> <FALSE> }T
T{       0  MIN-INT D0= -> <FALSE> }T

D2*

d-two-star

DOUBLE

( xd₁ -- xd₂ )

xd₂ is the result of shifting xd₁ one bit toward the most-significant bit, filling the vacated least-significant bit with zero.

T{              0. D2* -> 0. D2* }T
T{ MIN-INT       0 D2* -> 0 1 }T
T{         HI-2INT D2* -> MAX-2INT 1. D- }T
T{         LO-2INT D2* -> MIN-2INT }T

D2/

d-two-slash

DOUBLE

( xd₁ -- xd₂ )

xd₂ is the result of shifting xd₁ one bit toward the least-significant bit, leaving the most-significant bit unchanged.

T{       0. D2/ -> 0.        }T
T{       1. D2/ -> 0.        }T
T{      0 1 D2/ -> MIN-INT 0 }T
T{ MAX-2INT D2/ -> HI-2INT   }T
T{      -1. D2/ -> -1.       }T
T{ MIN-2INT D2/ -> LO-2INT   }T

D<

d-less-than

DOUBLE

( d₁ d₂ -- flag )

flag is true if and only if d₁ is less than d₂.

T{       0.       1. D< -> <TRUE> }T
T{       0.       0. D< -> <FALSE> }T
T{       1.       0. D< -> <FALSE> }T
T{      -1.       1. D< -> <TRUE> }T
T{      -1.       0. D< -> <TRUE> }T
T{      -2.      -1. D< -> <TRUE> }T
T{      -1.      -2. D< -> <FALSE> }T
T{      -1. MAX-2INT D< -> <TRUE> }T
T{ MIN-2INT MAX-2INT D< -> <TRUE> }T
T{ MAX-2INT      -1. D< -> <FALSE> }T
T{ MAX-2INT MIN-2INT D< -> <FALSE> }T

T{ MAX-2INT 2DUP -1. D+ D< -> <FALSE> }T
T{ MIN-2INT 2DUP 1. D+ D< -> <TRUE> }T

D=

d-equals

DOUBLE

( xd₁ xd₂ -- flag )

flag is true if and only if xd₁ is bit-for-bit the same as xd₂.

T{      -1.      -1. D= -> <TRUE> }T
T{      -1.       0. D= -> <FALSE> }T
T{      -1.       1. D= -> <FALSE> }T
T{       0.      -1. D= -> <FALSE> }T
T{       0.       0. D= -> <TRUE> }T
T{       0.       1. D= -> <FALSE> }T
T{       1.      -1. D= -> <FALSE> }T
T{       1.       0. D= -> <FALSE> }T
T{       1.       1. D= -> <TRUE> }T

T{   0   -1    0  -1 D= -> <TRUE> }T
T{   0   -1    0   0 D= -> <FALSE> }T
T{   0   -1    0   1 D= -> <FALSE> }T
T{   0    0    0  -1 D= -> <FALSE> }T
T{   0    0    0   0 D= -> <TRUE> }T
T{   0    0    0   1 D= -> <FALSE> }T
T{   0    1    0  -1 D= -> <FALSE> }T
T{   0    1    0   0 D= -> <FALSE> }T
T{   0    1    0   1 D= -> <TRUE> }T

T{ MAX-2INT MIN-2INT D= -> <FALSE> }T
T{ MAX-2INT       0. D= -> <FALSE> }T
T{ MAX-2INT MAX-2INT D= -> <TRUE> }T
T{ MAX-2INT HI-2INT  D= -> <FALSE> }T
T{ MAX-2INT MIN-2INT D= -> <FALSE> }T
T{ MIN-2INT MIN-2INT D= -> <TRUE> }T
T{ MIN-2INT LO-2INT  D= -> <FALSE> }T
T{ MIN-2INT MAX-2INT D= -> <FALSE> }T

D>S

d-to-s

DOUBLE

( d -- n )

n is the equivalent of d. An ambiguous condition exists if d lies outside the range of a signed single-cell number.

See

A.8.6.1.1140 D>S.

There exist number representations, e.g., the sign-magnitude representation, where reduction from double- to single-precision cannot simply be done with DROP. This word, equivalent to DROP on two's complement systems, desensitizes application code to number representation and facilitates portability.

T{    1234  0 D>S -> 1234   }T
T{   -1234 -1 D>S -> -1234   }T
T{ MAX-INT  0 D>S -> MAX-INT }T
T{ MIN-INT -1 D>S -> MIN-INT }T

DABS

d-abs

DOUBLE

( d -- ud )

ud is the absolute value of d.

T{ 1. DABS -> 1. }T
T{ -1. DABS -> 1. }T
T{ MAX-2INT DABS -> MAX-2INT }T
T{ MIN-2INT 1. D+ DABS -> MAX-2INT }T

DMAX

d-max

DOUBLE

( d₁ d₂ -- d₃ )

d₃ is the greater of d₁ and d₂.

T{       1.       2. DMAX -> 2.      }T
T{       1.       0. DMAX -> 1.      }T
T{       1.      -1. DMAX -> 1.      }T
T{       1.       1. DMAX -> 1.      }T
T{       0.       1. DMAX -> 1.      }T
T{       0.      -1. DMAX -> 0.      }T
T{      -1.       1. DMAX -> 1.      }T
T{      -1.      -2. DMAX -> -1.      }T

T{ MAX-2INT HI-2INT DMAX -> MAX-2INT }T
T{ MAX-2INT MIN-2INT DMAX -> MAX-2INT }T
T{ MIN-2INT MAX-2INT DMAX -> MAX-2INT }T
T{ MIN-2INT LO-2INT DMAX -> LO-2INT }T

T{ MAX-2INT       1. DMAX -> MAX-2INT }T
T{ MAX-2INT      -1. DMAX -> MAX-2INT }T
T{ MIN-2INT       1. DMAX -> 1.      }T
T{ MIN-2INT      -1. DMAX -> -1.      }T

DMIN

d-min

DOUBLE

( d₁ d₂ -- d₃ )

d₃ is the lesser of d₁ and d₂.

T{       1.       2. DMIN -> 1.      }T
T{       1.       0. DMIN -> 0.      }T
T{       1.      -1. DMIN -> -1.      }T
T{       1.       1. DMIN -> 1.      }T
T{       0.       1. DMIN -> 0.      }T
T{       0.      -1. DMIN -> -1.      }T
T{      -1.       1. DMIN -> -1.      }T
T{      -1.      -2. DMIN -> -2.      }T

T{ MAX-2INT HI-2INT DMIN -> HI-2INT }T
T{ MAX-2INT MIN-2INT DMIN -> MIN-2INT }T
T{ MIN-2INT MAX-2INT DMIN -> MIN-2INT }T
T{ MIN-2INT LO-2INT DMIN -> MIN-2INT }T

T{ MAX-2INT       1. DMIN -> 1.      }T
T{ MAX-2INT      -1. DMIN -> -1.      }T
T{ MIN-2INT       1. DMIN -> MIN-2INT }T
T{ MIN-2INT      -1. DMIN -> MIN-2INT }T

DNEGATE

d-negate

DOUBLE

( d₁ -- d₂ )

d₂ is the negation of d₁.

T{ 0. DNEGATE -> 0. }T
T{ 1. DNEGATE -> -1. }T
T{ -1. DNEGATE -> 1. }T
T{ max-2int DNEGATE -> min-2int SWAP 1+ SWAP }T
T{ min-2int SWAP 1+ SWAP DNEGATE -> max-2int }T

M*/

m-star-slash

DOUBLE

( d₁ n₁ +n₂ -- d₂ )

Multiply d₁ by n₁ producing the triple-cell intermediate result t. Divide t by +n₂ giving the double-cell quotient d₂. An ambiguous condition exists if +n₂ is zero or negative, or the quotient lies outside of the range of a double-precision signed integer.

See

A.8.6.1.1820 M*/.

M*/ was once described by Chuck Moore as the most useful arithmetic operator in Forth. It is the main workhorse in most computations involving double-cell numbers. Note that some systems allow signed divisors. This can cost a lot in performance on some CPUs. The requirement for a positive divisor has not proven to be a problem.

To correct the result if the division is floored, only used when necessary, i.e., negative quotient and remainder <>= 0.

: ?floored [ -3 2 / -2 = ] LITERAL IF 1. D- THEN ;

T{       5.       7             11 M*/ -> 3. }T
T{       5.      -7             11 M*/ -> -3. ?floored }T
T{      -5.       7             11 M*/ -> -3. ?floored }T
T{      -5.      -7             11 M*/ -> 3. }T
T{ MAX-2INT       8             16 M*/ -> HI-2INT }T
T{ MAX-2INT      -8             16 M*/ -> HI-2INT DNEGATE ?floored }T
T{ MIN-2INT       8             16 M*/ -> LO-2INT }T
T{ MIN-2INT      -8             16 M*/ -> LO-2INT DNEGATE }T

T{ MAX-2INT MAX-INT        MAX-INT M*/ -> MAX-2INT }T
T{ MAX-2INT MAX-INT 2/     MAX-INT M*/ -> MAX-INT 1- HI-2INT NIP }T
T{ MIN-2INT LO-2INT NIP DUP NEGATE M*/ -> MIN-2INT }T
T{ MIN-2INT LO-2INT NIP 1- MAX-INT M*/ -> MIN-INT 3 + HI-2INT NIP 2 + }T
T{ MAX-2INT LO-2INT NIP DUP NEGATE M*/ -> MAX-2INT DNEGATE }T
T{ MIN-2INT MAX-INT            DUP M*/ -> MIN-2INT }T

M+

m-plus

DOUBLE

( d₁ | ud₁ n -- d₂ | ud₂ )

Add n to d₁ | ud₁, giving the sum d₂ | ud₂.

See

A.8.6.1.1830 M+.

M+ is the classical method for integrating.

T{ HI-2INT   1 M+ -> HI-2INT   1. D+ }T
T{ MAX-2INT -1 M+ -> MAX-2INT -1. D+ }T
T{ MIN-2INT  1 M+ -> MIN-2INT  1. D+ }T
T{ LO-2INT  -1 M+ -> LO-2INT  -1. D+ }T

8.6.2 Double-Number extension words

2ROT

two-rote

DOUBLE EXT

( x₁ x₂ x₃ x₄ x₅ x₆ -- x₃ x₄ x₅ x₆ x₁ x₂ )

Rotate the top three cell pairs on the stack bringing cell pair x₁ x₂ to the top of the stack.

T{ 1. 2. 3. 2ROT -> 2. 3. 1. }T
T{ MAX-2INT MIN-2INT 1. 2ROT -> MIN-2INT 1. MAX-2INT }T

2VALUE

two-value

DOUBLE EXT

X:2value

( x₁ x₂ "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Create a definition for name with the execution semantics defined below, with an initial value of x₁ x₂.

name is referred to as a "two-value".

name Execution

( -- x₁ x₂ )

Place cell pair x₁ x₂ on the stack. The value of x₁ x₂ is that given when name was created, until the phrase "x₁ x₂ TO name" is executed, causing a new cell pair x₁ x₂ to be assigned to name.

TO name Run-time

( x₁ x₂ -- )

Assign the cell pair x₁ x₂ to name.

See

3.4.1 Parsing and 6.2.2295 TO, A.8.6.2.0435 2VALUE.

Typical use:

: fn1 S" filename" ;
fn1 2VALUE myfile
myfile INCLUDED
: fn2 S" filename2" ;
fn2 TO myfile
myfile INCLUDED

The implementation of TO to include 2VALUEs requires detailed knowledge of the host implementation of VALUE and TO, which is the main reason why 2VALUE should be standardized. The order in which the two cells are stored in memory is not specified in the definition for 2VALUE but this reference implementation has to assume one ordering — this is not intended to be definitive.

: 2VALUE ( x1 x2 -- )
CREATE , ,
DOES> 2@ ( -- x1 x2 )
;

The corresponding implementation of TO disregards the issue that TO must also work for integer VALUEs and locals.

: TO ( x1 x2 "<spaces>name" -- )
   ' >BODY
   STATE @ IF
     POSTPONE 2LITERAL POSTPONE 2!
   ELSE
     2!
   THEN
; IMMEDIATE

T{ 1 2 2VALUE t2val -> }T
T{ t2val -> 1 2 }T
T{ 3 4 TO t2val -> }T
T{ t2val -> 3 4 }T
: sett2val t2val 2SWAP TO t2val ;
T{ 5 6 sett2val t2val -> 3 4 5 6 }T

DU<

d-u-less

DOUBLE EXT

( ud₁ ud₂ -- flag )

flag is true if and only if ud₁ is less than ud₂.

T{       1.       1. DU< -> <FALSE> }T
T{       1.      -1. DU< -> <TRUE> }T
T{      -1.       1. DU< -> <FALSE> }T
T{      -1.      -2. DU< -> <FALSE> }T

T{ MAX-2INT HI-2INT DU< -> <FALSE> }T
T{ HI-2INT MAX-2INT DU< -> <TRUE> }T
T{ MAX-2INT MIN-2INT DU< -> <TRUE> }T
T{ MIN-2INT MAX-2INT DU< -> <FALSE> }T
T{ MIN-2INT LO-2INT DU< -> <TRUE> }T

< The optional Block word set

The optional Exception word set >