Floating-Point Conditionals

Conditional tests of floating-point numbers consume their argument(s) on the floating-point stack and return a truth flag to the data stack. The word F~ provides both exact and near-equality testing. F~ is usually preferable to F0=, since a floating-point number may fail to be zero by an infinitesimal amount.

Test for equality or near equality, on an absolute or relative basis. If the increment r3 is positive, return true if and only if the absolute value of [r1 - r2] is less than r3. If the increment r3 is zero, return true if and only if r1 and r2 are exactly identical (be aware that some implementations may encode positive zero and negative zero differently). If the increment r3 is negative, return true if and only if the absolute value of [r1 - r2] is less than the absolute value of r3 times the sum of the absolute values of r1 and r2. “F-proximate”

System Functions 111

Forth Programmer’s Handbook

3.8.9 Logarithmic and Trigonometric Functions

The words in this section provide a full set of logarithmic, exponential, and trigonometric functions. All angles are in radians. The function FSINCOS is a little unusual; it returns the sine and the cosine of the given angle (cosine on top). FSINCOS and FATAN2 are complementary operators that convert angles to 2-vectors and vice versa. They correctly handle the conversion even when the tangent of the angle would be infinite. The pair of values returned by FSINCOS are a Cartesian unit 2-vector in the direction of the given angle, measured counter-clockwise from the positive X-axis. FATAN2 takes arguments in the same order, converting a 2-vector back to a scalar angle; for all principal angles (-pi to +pi radians), the phrase FSINCOS FATAN2 is an identity operation within the accuracy and range of the operators. The phrase FSINCOS F/ is functionally equivalent to FTAN, but is useful only over a limited range of angles, whereas FSINCOS and FATAN2 are useful for all angles.

Glossary

Return r3, the principal radian angle (-pi to +pi) whose tangent is r1/r2. The

112 System Functions

Forth Programmer’s Handbook

values r1 and r2 may be, but need not be, components of a unit vector. An error will occur if both r1 and r2 are zero (vector of zero magnitude). “F-A-tan-two”

System Functions 113

3.8.10 Address Management

The floating-point command set introduces three new data types: internal floating point, 32-bit IEEE single-precision floating point, and 64-bit IEEE dou- ble-precision floating point. An application creating data structures using any of these types should use the support words described in this section to manage the address space. For example, the length of an internal floating-point number should always be referred to indirectly with words such as FLOAT+ or FLOATS, since the size may vary in different implementations.

When defining custom data structures, be aware that CREATE does not necessarily leave the data-space pointer aligned for the various floating-point data types. You can ensure alignment by explicitly specifying it both at compile time and execution time. An example from Standard Forth is:

In this example, the FALIGN after CREATE ensures that the address returned by HERE is float-aligned for the F! operation. FALIGN may have needed to reserve extra data space to do this, so, when an example of FCONSTANT is executed (using the code following DOES>) and the example’s address is returned, the word FALIGNED is needed to skip over that same space (if any) and access the floating-point value properly with F@.

In many implementations, alignment of floating-point data types requires nothing more than ordinary cell alignment, in which case, words such as FALIGN and FALIGNED may simply be aliases for ALIGN and ALIGNED. An application should not rely on this equivalence, however, and should use the floating-point words in this section.

114 System Functions

Return sf-addr, the first single-float-aligned address equal to or greater than addr. “S-F-aligned”

System Functions 115