TOC PREV NEXT INDEX

Put your logo here!


26 Standard Output Routines (stdout.hhf)


The Standard output unit (see stdio.hhf, stdin.hhf, and stdout.hhf) is probably the largest and most sophisticated module in the HLA Standard Library. It currently contains several defined constants (see the stdio.hhf header file for details), routines for sending data to the standard output, routines for send data to a file, and routines for reading data from the standard input (reading from files is coming, it's just not written yet).

Many routines have a "Size" suffix. For example, consider the stdout.putcsize routine:

stdout.putcSize( c:char; width:int32; fill:char )

Routines with the Size suffix output their value (typically the first parameter) in a minimum field width specified by the width parameter. If the number of screen print positions needed to print the value is less than the value of this width parameter, the routine will pad the output with extra characters so that the output is at least width characters long. These routines use the fill character as the padding character. If the width value is positive and greater than the number of print positions required to print the value, then the value is output right-justified in the print field (that is, the routine prints the padding characters first). If the width value is negative, then the routine outputs its value left justified, printing the padding characters after the value.

The Standard I/O unit provides the following routines.

26.1 General Output Functions

stdout.handle; @returns( "eax" );
 

This routine returns the LInux/Windows handle for the Standard Output Device in the EAX register. You may use this handle with the file I/O routines to write data to the standard output device.

stdout.write( Handle:dword; var buffer:byte; count:uns32 )
 

This procedure writes the number of bytes specified by the count variable to the standard output device. The bytes starting at the address of the buffer byte are written. No range checking is done on the buffer, it is your responsibility to ensure that the buffer contains at least count valid data bytes.

stdout.newln;
 

This routine writes a newline sequence to the standard output device. Under Windows, the newline sequence is a carriage return followed by a line feed. For Linux, this is just a line feed.

Note: the stdio.hhf header file also defines the string constant nl that you can print to print a newline sequence.

26.2 Boolean Output

stdout.putbool( b:boolean );
 

This routine outputs the string "true" or "false" to the standard output device.

26.3 Character, String, and Cset Output

stdout.putcset( cs:cset );
 

This routine outputs its character set parameter to the standard output device. In theory, the routine may output its data in any order, in practice, it outputs the members of its sets in lexicographical order.

stdout.putc( c:char );
 

This routine outputs a single character to the standard output device.

stdout.putcSize( c:char; width:int32; fill:char );
 

This routine outputs a character to the standard output device that is justified within the specified field width. This routine prints a minimum of width characters. If the width parameter is positive, the character is printed right justified in the print field. If the width value is negative, the character is printed left justified in the print field. If width is greater than one, then the fill character is printed in the other print positions.

stdout.puts( s:string );
 

This routine prints the specified string to the standard output device. Keep in mind that HLA strings are pointer objects. Therefore the parameter is a pointer to an HLA string. See the section on the HLA string library for more details.

stdout.putsSize( s:string; width:int32; fill:char );
 

This routine outputs a string to the standard output device using the specified minimum field width and fill character.

26.4 Hexadecimal Output

stdout.putb( b:byte );

stdout.putbSize( b:byte; size:dword; fill:char)
 

This procedure writes the value of b to the standard output device using exactly two hexadecimal digits (including a leading zero if necessary). The stdout.putbSize function lets you specify a minimum field width and a fill character. The stdout.putb routine uses a minimum size of two and a fill character of '0'.

stdout.putw( w:word );

stdout.putwSize( w:word; size:dword; fill:char)
 

This procedure writes the value of w to the standard output device using exactly four hexadecimal digits (including leading zeros if necessary). The stdout.putwSize function lets you specify a minimum field width and a fill character. The stdout.putw routine uses a minimum size of two and a fill character of '0'.

stdout.putd( dw:dword );

stdout.putdSize( d:dword; size:dword; fill:char)
 

This procedure writes the value of d to the standard output device using exactly eight hexadecimal digits (including leading zeros if necessary and an intervening underscore if underscore output is enabled). The stdout.putdSize function lets you specify a minimum field width and a fill character. The stdout.putd routine uses a minimum size of two and a fill character of '0'.

stdout.putq( qw:qword );

stdout.putqSize( q:qword; size:dword; fill:char)
 

This procedure writes the value of q to the standard output device using exactly sixteen hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The stdout.putqSize function lets you specify a minimum field width and a fill character. The stdout.putqroutine uses a minimum size of two and a fill character of '0'.

stdout.puttb( tb:tbyte );
 

This procedure writes the value of tb to the standard output device using exactly 20 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

stdout.putl( l:lword );

stdout.putlSize( l:lword; size:dword; fill:char)
 

This procedure writes the value of l to the standard output device using exactly 32 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled, in which case there will be 39 output characters). The stdout.putlSize function lets you specify a minimum field width and a fill character. The stdout.putl routine uses a minimum size of two and a fill character of '0'.

26.5 Signed Integer Output

These routines convert signed integer values to string format and write that string to the standard output device. The stdout.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

If the absolute value of width is greater than the number of print positions the value requires, then these functions output width characters to the output file. If width is non-negative, then these functions right-justify the value in the output field; if value is negative, then these functions left-justify the value in the output field.

These functions print the fill character as the padding value for the extra print positions.

Note that unlike floating point values, these functions do not print a space in front of the value if it is non-negative.



Figure 17 stdout.ixxSize Output Format

stdout.puti8size ( b:byte;  width:int32; fill:char );
 

This function writes the eight-bit signed integer value you pass to the standard output device using the width and fill values as specified above.

stdout.puti16Size( w:word;  width:int32; fill:char );
 

This function writes the 16-bit signed integer value you pass to the standard output device using the width and fill values as specified above.

stdout.puti32Size( d:dword; width:int32; fill:char );
 

This function writes the 32-bit value you pass as a signed integer to the standard output device using the width and fill values as specified above.

stdout.puti64Size( q:qword; width:int32; fill:char );
 

This function writes the 64-bit value you pass as a signed integer to the standard output device using the width and fill values as specified above.

stdout.puti128Size( l:lword; width:int32; fill:char );
 

This function writes the 128-bit value you pass as a signed integer to the standard output device using the width and fill values as specified above.

stdout.puti8 ( b:byte  );
 

This function converts the eight-bit signed integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.puti16( w:word  );
 

This function converts the 16-bit signed integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.puti32( d:dword );
 

This function converts the 32-bit signed integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.puti64( q:qword );
 

This function converts the 64-bit signed integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.puti128( l:lword );
 

This function converts the 128-bit signed integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

26.6 Unsigned Integer Output

These routines convert unsigned integer values to string format and write that string to the standard output device. The stdout.putuxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

If the absolute value of width is greater than the number of print positions the value requires, then these functions output width characters to the output file. If width is non-negative, then these functions right-justify the value in the output field; if value is negative, then these functions left-justify the value in the output field.

These functions print the fill character as the padding value for the extra print positions.



Figure 18 stdout.uxxxSize Output Format

stdout.putu8Size ( b:byte;  width:int32; fill:char );
 

This function writes the unsigned eight-bit value you pass to the standard output device using the width and fill values as specified above.

stdout.putu16Size( w:word;  width:int32; fill:char );
 

This function writes the unsigned 16-bit value you pass to the standard output device using the width and fill values as specified above.

stdout.putu32Size( d:dword; width:int32; fill:char );
 

This function writes the unsigned 32-bit value you pass to the standard output device using the width and fill values as specified above.

stdout.putu64Size( q:qword; width:int32; fill:char );
 

This function writes the unsigned 64-bit value you pass to the standard output device using the width and fill values as specified above.

stdout.putu128Size( l:lword; width:int32; fill:char );
 

This function writes the unsigned 128-bit value you pass to the standard output device using the width and fill values as specified above.

stdout.putu8 ( b:byte  );
 

This function converts theeight-bit unsigned integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.putu16( w:word  );
 

This function converts the 16-bit unsigned integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.putu32( d:dword );
 

This function converts the 32-bit unsigned integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.putu64( d:dword );
 

This function converts the 64-bit unsigned integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

stdout.putu128( d:dword );
 

This function converts the 128-bit unsigned integer you pass as a parameter to a string and writes this string to the standard output device using the minimum number of print positions the number requires.

26.7 Floating Point Output

The HLA standard output module provides several procedures you can use to write floating point values to athe standard output. The following subsections describe these routines.

26.7.0.1 Real Output Using Scientific Notation

The floating point numeric output routines translate the three different binary floating point formats to their string representation and then write this string to the standard output device. There are two generic classes of these routines: those that convert their values to exponential/scientific notation and those that convert their string to a decimal form.

The stdout.pute80, stdout.pute64, and stdout.pute32 routines convert their values to a string using scientific notation. These three routines each have two parameters: the value to output and the field width of the result. These routines produce a string with the following format:



Figure 19 stdout.putexx Output Using Scientific Notation

stdout.pute80( r:real80; width:uns32 );
 

This function writes the 80-bit extended precision floating point value passed in r to the standard output device using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 80-bit extended precision floating point values support about 18 significant digits. So a width value that yeilds more than 18 mantissa digits will produce garbage output in the low order digits of the number.

stdout.pute64( r:real64; width:uns32 );
 

This function writes the 64-bit double precision floating point value passed in r to the standard output device using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 64-bit double precision floating point values support about 15 significant digits. So a width value that yeilds more than 15 mantissa digits will produce garbage output in the low order digits of the number.

stdout.pute32( r:real32; width:uns32 );
 

This function writes the 32-bit single precision floating point value passed in r to the standard output device using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 32-bit extended precision floating point values support about 6-7 significant digits. So a width value that yeilds more than seven mantissa digits will produce garbage output in the low order digits of the number.

Note: all HLA floating point library routines assume the presence of an FPU. They do not save the state of the FPU.

26.7.1 Real Output Using Decimal Notation

Although scientific (exponential) notation is the most general display format for real numbers, real numbers you display in this format are very difficult to read. Therefore, the HLA standard output module also provides a set of functions that output real values using the decimal representation. Although you cannot (practically) use these decimal output routines for all real values, they are applicable to a wide variety of common numbers you will use in your programs.

These functions come in two varieties. The first variety requires four parameters: the real value to convert, the width of the converted value, the number of digit positions to the right of the decimal point, and a padding character. The second variety only requires the first three parameters and assumes the padding character is a space. These functions write their values using the following string format:



Figure 20 stdout.putrxx Conversion Format

stdout.putr80pad(  r:real80; width:uns32; decpts:uns32; pad:char );
 

This procedure writes an 80-bit extended precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

stdout.putr64pad(  r:real64; width:uns32; decpts:uns32; pad:char );
 

This procedure writes a 64-bit double precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

stdout.putr32pad( r:real32; width:uns32; decpts:uns32; pad:char );
 

This procedure writes a 32-bit single precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

stdout.putr80( r:real80; width:uns32; decpts:uns32 );
 

This procedure writes an 80-bit extended precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

stdout.putr64( r:real64; width:uns32; decpts:uns32 );
 

This procedure writes a 64-bit double precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

stdout.putr32( r:real32; width:uns32; decpts:uns32 );
 

This procedure writes a 32-bit single precision floating point value to the standard output device as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

Note: all HLA floating point library routines assume the presence of an FPU. They do not save the state of the FPU.

26.8 The stdout.put Macro

stdout.put( output_list );
 

stdout.put is a macro that provides a flexible syntax for outputting data to the standard output device. This macro allows a variable number of parameters. For each parameter present in the list, stdout.put will call the appropriate routine to emit that data, according to the type of the parameter. Parameters may be constants, registers, or memory locations.

Here is an example of a typical invocation of stdout.put:


 
stdout.put( "I=", i, " j=", j, nl );
 

 

The above is roughly equivalent to


 
puts( "I=" );
 
puti32( i );
 
puts( " j=" );
 
puti32( j );
 
newln();
 

 

This assumes, of course, that "i" and "j" are int32 variables.

The stdout.put macro also lets you specify the minimum field width for each parameter you specify. To print a value using a minimum field width, follow the object you wish to print with a colon and the value of the minimum field width. The previous example, using field widths, could look like the following:


 
stdout.put( "I=", i:2, " j=", j:5, nl );
 

 

Although this example used the literal decimal constants two and five for the field widths, keep in mind that register values and memory value (integers, anyway) are prefectly legal here.

For floating point numbers you wish to display in decimal form, you can specify both the minimum field width and the number of digits to print to the right of the decimal point by using the following syntax:


 
stdout.put( "Real value is ", f:10:3, nl );
 

 

The stdout.put macro can handle all the basic primitive types, including boolean, unsigned (8, 16, 32, 64, 128), signed (8, 16, 32, 64, 128), character, character set, real (32, 64, 80), string, and hexadecimal (byte, word, dword, qword, lword).

If you specify a class variable (object) and that class defines a "toString" method, the stdout.put macro will call the associated toString method and print that string. Note that the toString method must dynamically allocate storage for the string by calling stralloc. This is because stdout.put will call strfree on the string once it prints the string.

There is a known "design flaw" in the stdout.put macro. You cannot use it to print HLA intermediate variables (i.e., non-local VAR objects). The problem is that HLA's syntax for non-local accesses takes the form "reg32:varname" and stdout.put cannot determine if you want to print reg32 using varname print positions versus simply printing the non-local varname object. If you want to display non-local variables you must copy the non-local object into a register, a static variable, or a local variable prior to using stdout.put to print it. Of course, there is no problem using the other stdout.putXXXX functions to display non-local VAR objects, so you can use those as well.



TOC PREV NEXT INDEX