6.8 HLA Standard Library Support for Floating Point Arithmetic

The HLA Standard Library provides several routines that support the use of real numbers. In Chapters 1 and 2 you saw, with one exception, how the standard input and output routines operate. This section will not repeat that discussion; see those chapters for more details. One input function that Chapter 2 only mentioned briefly was the stdin.getf function. This section will elaborate on that function. The HLA Standard Library also includes the math.hhf module that provides several mathematical functions that the FPU doesn't directly support. This section will discuss those functions, as well.

6.8.1 The stdin.getf and fileio.getf Functions

The stdin.getf function reads a floating point value from the standard input device. It leaves the converted value in ST0 (i.e., on the top of the floating point stack). The only reason Chapter 2 did not discuss this function thoroughly was because you hadn't seen the FPU and FPU registers at that point.

The stdin.getf function accepts the same inputs that "stdin.get( fp_variable );" would except. The only difference between the two is where these functions store the floating point value.

6.8.2 Trigonometric Functions in the HLA Math Library

The FPU provides a small handful of trigonometric functions. It does not, however, support the full range of trig functions. The HLA math.hhf module fills in many of the missing functions. The trigonometric functions that HLA provides include

math.acos( arc cosine)
math.acot (arc cotangent)
math.acsc( arc cosecant )
math.asec (arc secant)
math.asin (arc sin)
math.cot (cotangent)
math.csc (cosecant)
math.sec (secant)

The HLA Standard Library actually provides five different routines you can call for each of these functions. For example, the prototypes for the first four math.cot(cotangent) routines are:

      procedure cot32( r32: real32 );      procedure cot64( r64: real64 );      procedure cot80( r80: real80 );      procedure _cot();

The first three routines push their parameter onto the FPU stack and compute the cotangent of the result. The fourth routine above (math._cot) computes the cotangent of the value currently held in ST0.

The fifth routine is actually an overloaded procedure that calls one of the four routines above depending on the parameter. This call uses the following syntax:

      math.cot();           // Calls _cot() to compute cot(ST0).      math.cot( r32 );      // Calls cot32 to compute the cotangent of r32.      math.cot( r64 );      // Calls cot64 to compute the cotangent of r64.      math.cot( r80 );      // Calls cot80 to compute the cotangent of r80.

Using this fifth form is probably preferable because it is much more convenient. Note that there is no efficiency loss when you use math.cot rather than one of the other cotangent routines. HLA actually translates this statement directly into one of the other calls.

The HLA trigonometric functions that require an angle expressed in radians, not degrees. Keep in mind that some of these functions produce undefined results for certain input values. If you've enabled exceptions on the FPU, these functions will raise the appropriate FPU exception if an error occurs.

6.8.3 Exponential and Logarithmic Functions in the HLA Math Library

The HLA math.hhf module provides several exponential and logarithmic functions in addition to the trigonometric functions. Like the trig functions, the exponential and logarithmic functions provide five different interfaces to each function depending on the size and location of the parameter. Table 6-12 lists the functions that math.hhf supports.

Table 6-12: Functions That Support *math.hhf*
Function	Description

`math`.TwoToX	Raises 2.0 to the specified power.
`math`.TenToX	Raises 10.0 to the specified power.
`math`.exp	Raises e [2.718281828…] to the specified power.
`math`.YtoX	Raises first parameter to the power specified by the second parameter.
`math`.log	Computes base 10 logarithm.
`math`.ln	Computes base e logarithm.

Except for the math.YtoX function, all these functions provide the same sort of interface as the math.cot function mentioned in the previous section. For example, the math.exp function provides the following prototypes:

      procedure math.exp32( r32: real32 );      procedure math.exp64( r64: real64 );      procedure math.exp80( r80: real80 );      procedure math._exp();

The math.exp function, by itself, automatically calls one of the above functions depending on the parameter type (and presence of a parameter):

      math.exp();                     // Calls _exp() to compute exp(ST0).      math.exp( r32 );                // Calls exp32 to compute the e**r32.      math.exp( r64 );                // Calls exp64 to compute the e**r64.      math.exp( r80 );                // Calls exp80 to compute the e**r80.

The lone exception to the preceding is the math.YtoX function. math.YtoX has its own rules because it has two parameters rather than one (Y and X). math.YtoX provides the following function prototypes:

      procedure math.YtoX32( y: real32; x: real32 );      procedure math.YtoX64( y: real64; x: real64 );      procedure Ymath.toX80( y: real80; x: real80 );      procedure math._YtoX();

The math._YtoX function computes ST1**ST0 (i.e., ST1 raised to the ST0 power).

The math.YtoX function provides the following interface:

      math.YtoX();                     // Calls _YtoX() to compute exp(ST0).      math.YtoX( y32, x32);            // Calls YtoX32 to compute y32**x32.      math.YtoX( y64, x64 );           // Calls YtoX64 to compute y64**x64.      math.YtoX( y80, x80 );           // Calls YtoX80 to compute y80**x80.