TOC PREV NEXT INDEX

Put your logo here!


25 Standard Input Routines (stdin.hhf)


The HLA Standard I/O unit provides a set of buffer input routines that read data from the Windows/Linux Standard Input Device.

Whenever you request input, by calling one of the following input routines, the Standard Library routines first check to see if there is any data available in an internal buffer. If so, the routines read the data from the buffer; if not, the routines fill the buffer by reading a line of text from the Windows/Linux Standard Input Device. Once a line is read, the routine will read its data from the newly acquired buffer. Additional calls to the standard input routines continue to read their data from this same buffer until the input line is exhausted, at which point the library routines will read more data from the Windows/Linux Standard Input Device.

The internal data buffer has sufficient storage for 1,024 characters1. This is generally sufficient for interactive input. If you feel you need more, feel free to go in an modify the source code to the library.

25.1 General Input Functions

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

This routine returns the handle of the Linux/Windows Standard Input Device in the EAX register.

stdin.flushInput;
 

This routine flushes the internal buffer. The next call to a Standard Library input routine will force the system to read a new line of text from the user. All current data in the internal input buffer is lost.

Please note that this routine does not immediately force the input of a new line of text from the user unless the internal buffer is already empty. If the internal buffer is empty and you call this routine, it will read a new line of text from the user and then flush this text from the internal buffer.

stdin.read( Handle:dword; var buffer:byte; count:uns32 )
 

This routine reads a sequence of count bytes from the standard input, storing the bytes into memory at the address specified by buffer.

stdin.readLn;
 

This routine flushes the current input buffer and immediately read a new line of text from the user.

stdin.eoln; @returns( "al" );
 
stdin.eoln2; @returns( "al" );
 

These functions return true if the input buffer is at the end of the current line. The stdin.eoln2 function will first remove any delimiter characters from the input buffer before testing for the end of the current line. These functions return true (1) or false (0) in the AL/EAX register.

These functions do not force a new line of input on the next stdin.getXX operation. I.e., if you read a string after stdin.eoln returns true, you will get the empty string as the result. Call stdin.readln to force the input of a new line.

25.2 Character and String Input Functions

stdin.peekc; @returns( "al" );
 

This routine returns the character character from the standard input device without actually "reading" that character. That is, after a call to stdin.peekc, the next call to stdin.getc will return the same character as the one stdin.peekc returns. A call to stdin.peekc does not force the input of a new line of text. If the current input buffer is empty, calls to stdin.peekc return zero in the AL register. This routine returns the character in the AL register and it returns zeros in the upper three bytes of EAX.

stdin.getc; @returns( "al" );
 

This routine reads a single character from the standard input and returns this character in the AL register. (Note that this routine also zeros out the H.O. three bytes of EAX.)

stdin.gets( s:string );
 

This routine reads a string from the standard input device and store the string into the string variable passed as the parameter. The string read consists of all characters remaining in the buffer to the end of the line, but the string will not contain the end of line sequence. If all characters have been read from the buffer then this call returns the empty string. If some routine removes the new line sequence from the end of the buffer, then calling this routine will force the input of a new line of text.

If the string is not large enough to hold the characters read from the input buffer, these routines will raise an exception.

When the standard input device is the Windows console device, the stdin.gets function allows you to use the standard Windows console editing functions. For example, pressing the ESC key erasing the current input line. You can use the arrow keys and the insert/delete keys to perform intraline editing on the input line. Ditto for Linux, though the console editing keys are more limited.

stdin.a_gets; @returns( "eax" );
 

This routine is very similar to stdin.gets. However, it allocates storage for its input string rather than store the string into some specified location. This routine returns a pointer to the newly allocated string in the EAX register. You should call strfree to free the storage associated with this string when you are done with it. Internally, HLA limits the input line to 1,024 characters. Note, however, that the Windows console device generallly limits input to fewer than this number of characters (typically 128) so you may not be able to read a full 1,024 characters into the string. Note, however, that this Windows Console input buffer limitation does not apply if you're redirected the input from a file to the standard input device.

25.3 Hexadecimal Input Functions

stdin.getb; @returns( "al" );
 

This function reads an eight-bit hexadecimal integer in the range 0..$FF from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getb function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FF. This function returns the binary form of the value in the AL register.

stdin.getw; @returns( "ax" );
 

This function reads a 16-bit hexadecimal integer in the range 0..$FFFF from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getw function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF. This function returns the binary form of the value in the AX register.

stdin.getd ; @returns( "eax" );
 

This function reads a 32-bit hexadecimal integer in the range 0..$FFFF_FFFF from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getd function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF. This function returns the binary form of the value in the EAX register.

stdin.getq; @returns( "edx:eax" ); 
 
This function reads a 64-bit hexadecimal integer in the range 0..$FFFF_FFFF_FFFF_FFFF from the file.  The 
number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter 
functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits.  Note 
that the value may not have a leading "$" unless you add this character to the delimiter character set.  The number 
must end with a valid delimiter character or the end of the file.  This function allows underscores in the interior of 
the number.  The stdin.getq function raises an appropriate exception if the input violates any of these rules or the 
value is outside the range 0..$FFFF_FFFF_FFFF_FFFF.  This function returns the 64-bit result in EDX:EAX. 
 
stdin.getl(  l:lword ) ; 
 

This function reads a 128-bit hexadecimal integer in the range zero through $FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getl function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF. This function stores the 128-bit result into the variable you pass as a reference parameter.

25.4 Signed Integer Input Functions

stdin.geti8; @returns( "al" );
 

This function reads a signed eight-bit decimal integer in the range -128..+127 from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.geti8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -128..+127. This function returns the binary form of the integer in the AL register.

stdin.geti16; @returns( "ax" );
 

This function reads a signed 16-bit decimal integer in the range -32768..+32767 from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.geti16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -32768..+32767. This function returns the binary form of the integer in the AX register.

stdin.geti32; @returns( "eax" );
 

This function reads a signed 32-bit decimal integer in the (approximate) range ±2 Billion from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.geti32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range plus or minus two billion. This function returns the binary form of the integer in the EAX register.

stdin.geti64; @returns( "edx:eax" );
 

This function reads a signed 64-bit decimal integer from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.geti64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 64-bit signed integer. This function returns the 64-bit result in EDX:EAX.

stdin.geti128( var l: lword ); 
 

This function reads a signed 128-bit decimal integer from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.geti128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 128-bit signed integer. This function stores the 128-bit result in the lword you pass as a reference parameter.

25.5 Unsigned Integer Input Routines

stdin.getu8; @returns( "al" );
 

This function reads an unsigned eight-bit decimal integer in the range 0..+255 from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getu8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..255. This function returns the binary form of the integer in the AL register.

stdin.getu16; @returns( "ax" );
 

This function reads an unsigned 16-bit decimal integer in the range 0..+65535 from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getu16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..65535. This function returns the binary form of the integer in the AX register.

stdin.getu32; @returns( "eax" );
 

This function reads an unsigned 32-bit decimal integer in the range 0..+4,294,967,295 from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getu32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..4,294,967,295. This function returns the binary form of the integer in the EAX register.

stdin.getu64; @returns( "edx:eax" );
 

This function reads an unsigned 64-bit decimal integer from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getu64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..264-1. This function returns the binary form of the integer in the qword parameter you pass by reference.

stdin.getu128( var q:qword );
 

This function reads an unsigned 128-bit decimal integer from the standard input device. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The stdin.getu128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..2128-1. This function returns the binary form of the integer in the lword parameter you pass by reference.

25.6 Floating Point Input

stdin.getf; @returns( "st0" );
 

This function reads an 80-bit floating point value in either decimal or scientific from from the standard input device and leaves the result sitting on the FPU stack (i.e., in ST0). The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a sequence of characters that represent a floating point value. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. This function raises an appropriate exception if an error occurs.

1Windows has its own internal limitations and may not support input of 1,024 characters.



TOC PREV NEXT INDEX