Standard Library -- Conversions

UCR StdLib v2.0: Conversion Routines
6.1 - Interface
6.2 - Generic Interface
6.3 - Atof, AtofCS, Atofx, AtofStk
6.3.1 - Calling Conventions and Assertions
6.3.2 - Atof Addressing Modes
6.3.3 - Syntax & Examples
6.4 - Atoh, AtohCS, Atohx, AtohStk, AtohTOS
6.4.1 - Calling Conventions and Assertions
6.4.2 - Atoh Addressing Modes
6.4.3 - Syntax & Examples
6.5 - Atoi, AtoiCS, AtoiStk, AtoiTOS, AtoiX
6.5.1 - Calling Conventions and Assertions
6.5.2 - Atoi Addressing Modes
6.5.3 - Syntax & Examples
6.6 - AtoL, AtoLCS, AtoLx, AtoLStk, AtoLTOS
6.6.1 - Calling Conventions and Assertions
6.6.2 - AtoL Addressing Modes
6.6.3 - Syntax & Examples
6.7 - Atolh, Atolhx, AtolhStk, AtolhTOS
6.7.1 - Calling Conventions and Assertions
6.7.2 - Atolh Addressing Modes
6.7.3 - Syntax & Examples
6.8 - Atou, AtouCS, AtouTOS, AtouStk, Atoux
6.8.1 - Calling Conventions and Assertions
6.8.2 - Atou Addressing Modes
6.8.3 - Syntax & Examples
6.9 - Atoul, AtoulCS, Atoulx, AtoulStk, AtoulTOS
6.9.1 - Calling Conventions and Assertions
6.9.2 - Atoul Addressing Modes
6.9.3 - Syntax & Examples
6.10 - etoa, etoax, etoam
6.10.1 - Calling Conventions and Assertions
6.10.2 - Etoa Addressing Modes
6.10.3 - Syntax & Examples
6.11 - ftoa, ftoax, ftoam
6.11.1 - Calling Conventions and Assertions
6.11.2 - Ftoa Addressing Modes
6.11.3 - Syntax & Examples
6.12 - Htoa, HtoaCS, HtoaStk, HtoaTOS, Htoax, Htoam
6.12.1 - Calling Conventions and Assertions
6.12.2 - Htoa Addressing Modes
6.12.3 - Syntax & Examples
6.13 - ISize, ISizeCS, ISizeStk, ISizeTOS
6.13.1 - Calling Conventions and Assertions
6.13.2 - ISize Addressing Modes
6.13.3 - Syntax & Examples
6.14 - Itoa, ItoaCS, ItoaStk, ItoaTOS, Itoax, Itoam
6.14.1 - Calling Conventions and Assertions
6.14.2 - Itoa Addressing Modes
6.14.3 - Syntax & Examples
6.15 - LSize, LSizeCS, LSizeStk, LSizeTOS
6.15.1 - Calling Conventions and Assertions
6.15.2 - LSize Addressing Modes
6.15.3 - Syntax & Examples
6.16 - Ltoa, LtoaCS, LtoaStk, LtoaTOS, Ltoax, Ltoam
6.16.1 - Calling Conventions and Assertions
6.16.2 - Ltoa Addressing Modes
6.16.3 - Syntax & Examples
6.17 - toFlt, toFltStk,toFltCS
6.17.1 - Calling Conventions and Assertions
6.17.2 - ToFlt Addressing Modes
6.17.3 - Syntax & Examples
6.18 - toHex, toHexStk, toHexTOS, toHexCS
6.18.1 - Calling Conventions and Assertions
6.18.2 - ToHex Addressing Modes
6.18.3 - Syntax & Examples
6.19 - toInt, toIntStk, toIntCS, toIntTOS
6.19.1 - Calling Conventions and Assertions
6.19.2 - ToInt Addressing Modes
6.19.3 - Syntax & Examples
6.20 - toLHex, toLHexStk, toLHexTOS, toLHexCS
6.20.1 - Calling Conventions and Assertions
6.20.2 - ToLHex Addressing Modes
6.20.3 - Syntax & Examples
6.21 - toLong, toLongStk, toLongTOS, toLongCS
6.21.1 - Calling Conventions and Assertions
6.21.2 - ToLong Addressing Modes
6.21.3 - Syntax & Examples
6.22 - toULong, toULongStk
6.22.1 - Calling Conventions and Assertions
6.22.2 - ToULong Addressing Modes
6.22.3 - Syntax & Examples
6.23 - toUns, toUnsStk, toUnsTOS, toUnsCS
6.23.1 - Calling Conventions and Assertions
6.23.2 - ToUns Addressing Modes
6.23.3 - Syntax & Examples
6.24 - UlSize, UlSizeCS, UlSizeStk, UlSizeTOS
6.24.1 - Calling Conventions and Assertions
6.24.2 - UlSize Addressing Modes
6.24.3 - Syntax & Examples
6.25 - Ultoa, UltoaCS, UltoaStk, UltoaTOS, Ultoax, Ultoam
6.25.1 - Calling Conventions and Assertions
6.25.2 - Ultoa Addressing Modes
6.25.3 - Syntax & Examples
6.26 - USize, USizeCS, USizeStk, USizeTOS
6.26.1 - Calling Conventions and Assertions
6.26.2 - USize Addressing Modes
6.26.3 - Syntax & Examples
6.27 - Utoa, UtoaCS, UtoaStk, UtoaTOS, Utoax, Utoam
6.27.1 - Calling Conventions and Assertions
6.27.2 - Utoa Addressing Modes
6.27.3 - Syntax & Examples
6.28 - Wtoa, WtoaCS, WtoaStk, WtoaTOS, Wtoax, Wtoam
6.28.1 - Calling Conventions and Assertions
6.28.2 - Wtoa Addressing Modes
6.28.3 - Syntax & Examples

UCR StdLib v2.0: Conversion Routines

The UCR Standard Library (stdlib) contains a large number of routines that convert data from one format to another. These routines typically convert between some binary format and ASCII. For example, the ATOI routine converts an ASCII string to an integer. Conversely, the Utoa routine converts an integer value to an ASCII string. There are other conversions as well. For example, the TOUPPER routine converts lower case characters to upper case.

6.1 Interface

To access the routines in the conversions package, your assembly language module must include the file "conv.a" during assembly. You can accomplish this with either of the following include statements in your assembly code: 




	include	conv.a
or
	include	ucrlib.a
Note that the "ucrlib.a" include file automatically includes all include files associated with the UCR Standard Library.

The conv.a include file exports several symbols. The UCR Standard Library prefaces all "private" names with a dollar sign ("$"). You should not call any routine in this package that begins with this symbol. To avoid name conflicts, you should not define any symbols in your programs that begin with a dollar sign ("$"). Note that future versions of the stdlib (that remain compatible with this release) may change "private" names. To remain compatible with future releases, you must not refer to these "private" names within your programs.

Source code appearing in this chapter is current as of Version Two, Release 40. There may be minor changes between this source code and the current release.

6.2 Generic Interface

Many of the standard library routines use a common generic programmer's interface. Such routines let you pass parameters to them in several different locations. Common examples include in the registers, by value in the code stream (CSi), by reference in the code stream (CS), by value on the top of stack (TOS), and by reference on the top of stack (Stk). Typically, there are separate invocation macros defined for each of these variants, e.g., 





        IsAlNum                 ;Passed in AL register.

        IsAlNumCS
        dword   chrPtr          ;Passed by reference in code stream.

        push    'a'             ;Passed by value on the stack.
        IsAlNumTOS

        push    seg chrVar      ;Passed by reference on the stack.
        push    offset chrVar
        IsAlNumStk
Note that you will rarely find actual routines that pass their parameters by value in the code stream using the "CSi" suffix. The reason this is so is because most such routines use different, more descriptive names. For example, "PutsCSi" goes by the name "Print".

In addition to the above forms there are two other suffixes generally applied to stdlib routine names: "m" and "x". The "m" suffix stands for "malloc". Routines with the "m" suffix typically generate a string result and malloc storage for the string on the heap, returning a pointer to this string in the ES:DI register pair. The routines with an "x" suffix also process strings. Most stdlib routines preserve the value of the ES:DI registers when processing strings; typically, they leave the ES:DI register pair pointing at the start of the string. The routines with an "x" suffix do not preserve ES:DI, they generally leave ES:DI pointing at the zero byte of the string they processed or generated.

To make it easier to use all these different variants, the standard library typically defines a macro for each routine that lets you specify various operands using stdlib "addressing modes." The allowable addressing modes vary by routines, but they typically take one of the following forms: 





        name            ;If operand field is blank, use "plain" version.
        name    var     ;Generally passes address of var in code stream.
        name    const   ;Pushes const onto TOS and uses nameTOS routine.
        name    [wvar]  ;Pushes DS followed by value of wVar variable
                        ; (assumed to be a word) and calls nameSTK
        name    [dVar]  ;Pushes dword value of dVar and calls nameStk.
Since not all of these "addressing modes" are applicable to all instructions, and some instructions allow different sets of operands (including multiple operands), there are lots of special cases. Such cases are noted after the explaination for each particular routine.

6.3 Atof, AtofCS, Atofx, AtofStk

These routines convert a string of ASCII characters to an 80-bit floating point value. On entry to Atof and Atofx, the ES:DI register pair contains the address of the string to convert; on entry to AtofStk, the far address of the string appears on the stack; for AtofCS, the address follows the call in the code stream. On return from these routines, the ST(0) register (top of FPU stack) contains the real value assuming there was no conversion error. If a conversion error occurs, these routines return the carry flag set. If no such error occurs, these routines return the carry flag clear.

These routines flag an error under under the following conditions:

The string (after removing leading spaces) doesn't begin with one of the following, where "d " represents a single decimal digit: 




-d     -.d     +d     +.d     d     .d

An error will also occur if there are two (or more) decimal points in a floating point number or if the exponent (if present) doesn't contain at least one decimal digit after the "E", "e", or exponent sign character. Finally, ATOF also returns an error condition if the exponent is outside the rang e -4930..+4930.

A typical floating point value takes the form sign digits . digits E sign digits. The sign can be a plus or minus sign. Digits represents a string of zero or more digits. A syntactically correct floating point value has a sequence of one or more digits either before or after the decimal point. All other fields are optional. Note that Atof will properly convert a simple string of digits (i.e., integer representation) to a floating point value. No exponent or decimal point is required. The following regular expression describes legal input to Atof: 





[+ | -]?  ["0".."9"]+   [ "."  ["0".."9"]*]?  [ ["E" | "e"] [+|-]? ["0".."9"]+]?
Unlike integer strings, Atof does not allow underscores in floating point numbers.

If you need to verify that the conversion did not end on an illegal symbol, you should use the Atofx routine. This routine leaves ES:DI pointing at the first character it was not able to convert (assuming Atofx returns with the carry flag clear). You can compare the character ES:DI points at against a set of legal characters that you want to allow as number termination characters.

6.3.1 Calling Conventions and Assertions




Atof:
Inputs:	ES:DI points at the string to convert.
Outputs:	ST(0) contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some real number.
Note:	Atof will skip leading spaces in the string before the conversion begins.

Atofx:
Inputs:	ES:DI points at the string to convert.
Outputs:	ST(0) contains the real result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the character it could not convert.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some real number.
Note:	Atofx will skip leading spaces in the string before the conversion begins.





AtofCS:
Inputs:	A far pointer to the string to convert follows the call in the code stream.
Outputs:	ST(0) contains the real result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some real number.
Note:	AtofStk will skip leading spaces in the string before the conversion begins.





AtofStk:
Inputs:	A far pointer to the string to convert appears on the top of stack.
Outputs:	ST(0) contains the real result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Pops pointer to string off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some real number.
Note:	AtofStk will skip leading spaces in the string before the conversion begins.

6.3.2 Atof Addressing Modes

Atof Addressing Modes
Name Plain CS TOS Stk X CSi
Atof X X   X X -

6.3.3 Syntax & Examples




String2Convert  byte    "  -12345.67  89.1e-10",0
Value           real8   ?
Value2          real8   ?
                 
                lesi    String2Convert
                atof
                fst     Value          ;Value = -12345.67
                 
                atofCS
                dword   String2Convert
                fst     Value          ;Value = -12345.67

                push    seg String2Convert
                push    offset String2Convert
                atofStk
                fst     Value           ;Value = -12345.67
                
                lesi    String2Convert
                atofx
                fst     Value           ;Value = -12345.67
                atofx
                fst     Value2          ;Value2 = 89.1e-10

6.4 Atoh, AtohCS, Atohx, AtohStk, AtohTOS

These routines convert a string of ASCII characters that represent a hexadecimal value to a 16-bit value in the range 0..FFFF. The regular expression for legal values is 




["0".."9" | "A".."f" | "a".."f"] 
	[["0".."9" | "a".."f" | "a".."f" | "_"]* 
		["0".."9" | "a".."f" | "a".."f"]]*
In English, this regular expression requires at least one hexadecimal digit followed by zero or more hexadecimal digits. It also allows underscore characters between hex digits (though not at the beginning or end of the value).

Other than the fact that these routines work with hexadecimal values, you use them in the same manner that you would use the ATOI* routines.

6.4.1 Calling Conventions and Assertions




Atoh:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	Atoh will skip leading spaces in the string before the conversion begins.

Atohx:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-hex digit (and non-underscore) character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	Atohx will skip leading spaces in the string before the conversion begins.





AtohCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	AX contains the result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtohCS will skip leading spaces in the string before the conversion begins.





AtohStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtohStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	AtohStk will skip leading spaces in the string before the conversion begins.





AtohTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtohTOS leaves the converted result on the top of the stack.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtohTOS will skip leading spaces in the string before the conversion begins.

6.4.2 Atoh Addressing Modes

Atoh Addressing Modes
Name Plain CS TOS Stk X CSi
Atoh X X X X X -

The Atoh macro allows the following operands:

Atoh Extended Syntax (Single/No Operands)
Name Plain byteVar Num const [word Var] [dword Var] String Const
Atoh X X - X X -

Atoh Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoh X - X X -

Atoh Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoh X - X X -

6.4.3 Syntax & Examples




String2Convert  byte    "  ABCD  678a",0
Value           word    ?
Value2          word    ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                Atoh
                mov     Value, ax       ;Value = 0abcdh

                AtohCS
                dword   String2Convert
                mov     Value, ax       ;Value = 0abcdh

                pshadrs String2Convert
                AtohTOS
                pop     Value           ;Value = 0abcdh

                pshadrs String2Convert
                pshadrs Value
                AtohStk                 ;Value = 0abcdh

                lesi    String2Convert
                Atohx
                mov     Value, ax       ;Value = 0abcdh
                Atohx
                mov     Value2, ax      ;Value2 = 678ah
The Atoh routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atoh calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atoh routine; it expects a pointer to the string in ES:DI and returns the converted result in AX: 




                Atoh   ;Generates a call to the stdlib $Atoh routine.
The second version of the extended syntax Atoh call lets you specify a single parameter. If this is the name of a byte variable, Atoh assumes this is the name of a string variable that contains the value to convert. It calls AtohCS to do the conversion and returns the value in AX: 




                Atoh    String2Convert

; Equivalent to:

                AtohCS
                dword   String2Convert
If this is a [wvar] or [dwvar] operand (word pointer or double word pointer), then atoh assumes the pointer contains the address of the string to convert. Atoh will return the converted value in AX.

The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atoh will put the result. This particular form calls the AtohStk routine: 




                Atoh    byteVar, wordVar
                Atoh    byteVar, [wordVar]
                Atoh    byteVar, [dwordVar]

                Atoh    [wordVar], wordVar
                Atoh    [wordVar], [wordVar]
                Atoh    [wordVar], [dwordVar]

                Atoh    [dwordVar], wordVar
                Atoh    [dwordVar], [wordVar]
                Atoh    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atoh assumes that it's the name of a string variable. It converts that string to a binary value. If the first parameter is of the form "[wordVar]" then Atoh assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to a binary value. If the first parameter is "[dwordVar]" then Atoh assumes this is a dword variable containing a far pointer to the string, it converts that string to a binary value.

The second parameter must be a word variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atoh stores the converted value in the word specified by this second parameter.

Note that Atoh converts all the calls above to AtohStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtohStk to do the work.

6.5 Atoi, AtoiCS, AtoiStk, AtoiTOS, AtoiX

These routines convert a string of ASCII characters to a 16-bit signed integer value. On entry to Atoi and Atoix, the ES:DI register pair contains the address of the string to convert; on entry to AtoiStk, the far address of the string appears on the stack. AtoiCS expects a pointer to a string in the code stream immediately following the call. AtoiStk expects two pointers on the stack, a pointer to the string to convert and a pointer to the integer where it should store the result. AtoiTOS expects a pointer to a string on the top of stack, it leaves the integer result on the stack.

On return from the Atoi, AtoiX, and AtoiCS routines, the AX register contains the signed integer value assuming there was no conversion error. AtoiStk and AtoiTOS leave their results in the aforementioned locations. If a conversion error occurs, these routines return the carry flag set. If no such error occurs, these routines return the carry flag clear.

These routines are rather lax in their conversion. Specifically, they allow leading spaces and will terminate conversion on the first non-digit symbol. Assuming there was at least one decimal digit in the string, they will not return an error.

These routines flag an error under under two conditions: an arithmetic overflow occurs during conversion or if the first non-blank character is not a digit or a minus sign followed by a digit. Arithmetic overflow occurs if the value is outside the range -32768..+32767. A valid number takes the form described by the following regular expression: 




	["-" | ] ["0".."9"] [["0".."9" | "_"]* ["0".."9"]]*
In English, this regular expression means that a 16-bit signed value may have an optional minus sign followed by at least one digit. It may optionally have more than one decimal digit. If the number contains two or more digits, there may be underscore characters between the digits (that is, the digit string cannot begin or end with the underscore). The conversion algorithm ignores any underscores appearing in the string. They are intended to serve as thousands separators in lieu of commas in long numbers. There is no requirement that they occur within an integer nor any requirement that they separate exactly three digits. The following "integers" all represent the same value: 




	-1000	-1_000	-1_0_0_0		-1_____000
If you need to verify that the conversion did not end on an illegal symbol, you should use the Atoix routine. This routine leaves ES:DI pointing at the first character it was not able to convert (assuming Atoix returns with the carry flag clear). You can compare the character ES:DI points at against a set of legal characters that you want to allow as number termination characters.

6.5.1 Calling Conventions and Assertions




Atoi:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atoi will skip leading spaces in the string before the conversion begins.

Atoix:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-digit character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atoix will skip leading spaces in the string before the conversion begins.





AtoiCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	AX contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtoiCS will skip leading spaces in the string before the conversion begins.





AtoiStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtoiStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoiStk will skip leading spaces in the string before the conversion begins.





AtoiTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtoiTOS leaves the converted result on the top of the stack.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoiTOS will skip leading spaces in the string before the conversion begins.

6.5.2 Atoi Addressing Modes

Atoi Addressing Modes
Name Plain CS TOS Stk X CSi
Atoi X X X X X -

The Atoi macro allows the following operands:

Atoi Extended Syntax (Single/No Operands)
Name byteVar Num const [word Var] [dword Var] String Const
Atoi X - X X -

Atoi Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoi X - X X -

Atoi Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoi X - X X -

6.5.3 Syntax & Examples




String2Convert  byte    "  -12345  6789",0
Value           word    ?
Value2          word    ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                atoi
                mov     Value, ax       ;Value = -12345

                atoiCS
                dword   String2Convert
                mov     Value, ax       ;Value = -12345

                pshadrs String2Convert
                atoiTOS
                pop     Value           ;Value = -12345

                pshadrs String2Convert
                pshadrs Value
                atoiStk                 ;Value = -12345

                lesi    String2Convert
                atoix
                mov     Value, ax       ;Value = -12345
                atoix
                mov     Value2, ax      ;Value2 = 6789
The Atoi routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atoi calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atoi routine; it expects a pointer to the string in ES:DI and returns the converted result in AX: 




                atoi      ;Generates a call to the stdlib $atoi routine.
The second version of the extended syntax Atoi call lets you specify a single parameter. This must be the name of a byte variable. Atoi assumes this is the name of a string variable that contains the value to convert. It calls AtoiCS to do the conversion and returns the value in AX: 




                atoi    String2Convert

; Equivalent to:

                atoiCS
                dword   String2Convert
Another possibility is to specify (surrounded by square brackets) the name of a word or dword pointer variable that contains the near or far address (respectively) of the string to convert. 





		atoi	[wptr]
		atoi	[dptr]
The first example above assumes that wptr contains a near pointer to a character string found in the current data segment. The second example uses a far pointer to the string.

The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atoi will put the result. This particular form calls the AtoiStk routine: 




                atoi    byteVar, wordVar
                atoi    byteVar, [wordVar]
                atoi    byteVar, [dwordVar]

                atoi    [wordVar], wordVar
                atoi    [wordVar], [wordVar]
                atoi    [wordVar], [dwordVar]

                atoi    [dwordVar], wordVar
                atoi    [dwordVar], [wordVar]
                atoi    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atoi assumes that it's the name of a string variable. It converts that string to an integer. If the first parameter is of the form "[wordVar]" then Atoi assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to an integer. If the first parameter is "[dwordVar]" then Atoi assumes this is a dword variable containing a far pointer to the string, it converts that string to an integer.

The second parameter must be a word variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atoi stores the converted integer in the word specified by this second parameter.

Note that Atoi converts all the calls above to AtoiStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtoiStk to do the work.

6.6 AtoL, AtoLCS, AtoLx, AtoLStk, AtoLTOS

These routines convert a string of ASCII characters to a 32-bit signed integer value in the range -2147483648..+2147483647. Other than the range involved, this routine is identical to the Atoix routines. Please see their descriptions for more details.

6.6.1 Calling Conventions and Assertions




AtoL:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atol will skip leading spaces in the string before the conversion begins.

AtoLx:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the signed result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-digit character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atolx will skip leading spaces in the string before the conversion begins.

AtoLCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtoLCS will skip leading spaces in the string before the conversion begins.





AtoLStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtoLStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoLStk will skip leading spaces in the string before the conversion begins.





AtoLTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtoLTOS replaces the pointer on TOS with the converted result.
Errors:	None.
Side Effects:	None.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoLTOS will skip leading spaces in the string before the conversion begins.

6.6.2 AtoL Addressing Modes

AtoL Addressing Modes
Name Plain CS TOS Stk X CSi
AtoL X X X X X -

The Atol macro allows the following operands:

Atol Extended Syntax (Single/No Operands)
Name Plain byteVar Num const [word Var] [dword Var] String Const
Atol X X - - - -

Atol Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atol X - X X -

Atol Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atol X - X X -

6.6.3 Syntax & Examples




String2Convert  byte    "  12345  6789",0
Value           sdword    ?
Value2          sdword    ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                atol
                mov     Value, eax       ;Value = 12345

                atolCS
                dword   String2Convert
                mov     Value, eax       ;Value = 12345

                pshadrs String2Convert
                atolTOS
                popd    Value           ;Value = 12345

                pshadrs String2Convert
                pshadrs Value
                atolStk                 ;Value = 12345

                lesi    String2Convert
                atolx
                mov     Value, eax      ;Value = 12345
                atolx
                mov     Value2, eax     ;Value2 = 6789
The Atol routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atol calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atol routine; it expects a pointer to the string in ES:DI and returns the converted result in EAX: 




                atol       ;Generates a call to the stdlib $atol routine.
The second version of the extended syntax Atol call lets you specify a single parameter. This must be the name of a byte variable. Atol assumes this is the name of a string variable that contains the value to convert. It calls AtolCS to do the conversion and returns the value in EAX: 




                atol    String2Convert

; Equivalent to:

                atolCS
                dword   String2Convert
The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atol will put the result. This particular form calls the AtolStk routine: 




                atol    byteVar, dwordVar
                atol    byteVar, [wordVar]
                atol    byteVar, [dwordVar]

                atol    [wordVar], dwordVar
                atol    [wordVar], [wordVar]
                atol    [wordVar], [dwordVar]

                atol    [dwordVar], dwordVar
                atol    [dwordVar], [wordVar]
                atol    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atol assumes that it's the name of a string variable. It converts that string to an integer. If the first parameter is of the form "[wordVar]" then Atol assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to an integer. If the first parameter is "[dwordVar]" then Atol assumes this is a dword variable containing a far pointer to the string, it converts that string to an integer.

The second parameter must be a dword variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atol stores the converted integer in the dword specified by this second parameter.

Note that Atol converts all the calls above to AtolStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtolStk to do the work.

6.7 Atolh, Atolhx, AtolhStk, AtolhTOS

These routines convert a string of ASCII characters that represent a hexadecimal value to a 32-bit value in the range 0..FFFFFFFF. The regular expression for legal values is 




["0".."9" | "A".."f" | "a".."f"] 
	[["0".."9" | "a".."f" | "a".."f" | "_"]* 
		["0".."9" | "a".."f" | "a".."f"]]*
In English, this regular expression requires at least one hexadecimal digit followed by zero or more hexadecimal digits. It also allows underscore characters between hex digits (though not at the beginning or end of the value).

These routines are essentially the same as the Atoh* routines except they return a 32-bit value in EAX rather than a 16-bit value in AX.

6.7.1 Calling Conventions and Assertions




Atolh:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	Atolh will skip leading spaces in the string before the conversion begins.

Atolhx:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-hex digit (and non-underscore) character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	Atolhx will skip leading spaces in the string before the conversion begins.





AtolhCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	EAX contains the result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtolhCS will skip leading spaces in the string before the conversion begins.





AtolhStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtolhStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some hexadecimal number.
Note:	AtolhStk will skip leading spaces in the string before the conversion begins.





AtolhTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtolhTOS leaves the converted result on the top of the stack.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtolhTOS will skip leading spaces in the string before the conversion begins.

6.7.2 Atolh Addressing Modes

Atolh Addressing Modes
Name Plain CS TOS Stk X CSi
Atolh X X X X X -

The Atolh macro allows the following operands:

Atolh Extended Syntax (Single/No Operands)
Name No Operand byteVar Num const [word Var] [dword Var] String Const
Atolh X X - X X -

Atolh Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atolh X - X X -

Atolh Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atolh X - X X -

6.7.3 Syntax & Examples




String2Convert  byte    "  1a2b  6789",0
Value           dword   ?
Value2          dword   ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                Atolh
                mov     Value, eax      ;Value = 1a2b

                AtolhCS
                dword   String2Convert
                mov     Value, eax      ;Value = 1a2b

                pshadrs String2Convert
                AtolhTOS
                popd     Value          ;Value = 1a2b

                pshadrs String2Convert
                pshadrs Value
                AtolhStk                ;Value = 1a2b

                lesi    String2Convert
                Atolhx
                mov     Value, eax      ;Value = 1a2b
                Atolhx
                mov     Value2, eax     ;Value2 = 6789
The Atolh routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atolh calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atolh routine; it expects a pointer to the string in ES:DI and returns the converted result in EAX: 




                Atolh                   ;Generates a call to the stdlib $Atolh routine.
The second version of the extended syntax Atolh call lets you specify a single parameter. This must be the name of a byte variable. Atolh assumes this is the name of a string variable that contains the value to convert. It calls AtolhCS to do the conversion and returns the value in EAX: 




                Atolh    String2Convert

; Equivalent to:

                AtolhCS
                dword   String2Convert
The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atolh will put the result. This particular form calls the AtolhStk routine: 




                Atolh    byteVar, dwordVar
                Atolh    byteVar, [wordVar]
                Atolh    byteVar, [dwordVar]

                Atolh    [wordVar], dwordVar
                Atolh    [wordVar], [wordVar]
                Atolh    [wordVar], [dwordVar]

                Atolh    [dwordVar], dwordVar
                Atolh    [dwordVar], [wordVar]
                Atolh    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atolh assumes that it's the name of a string variable. It converts that string to an integer. If the first parameter is of the form "[wordVar]" then Atolh assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to an integer. If the first parameter is "[dwordVar]" then Atolh assumes this is a dword variable containing a far pointer to the string, it converts that string to an integer.

The second parameter must be a dword variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atolh stores the converted integer in the dword specified by this second parameter.

Note that Atolh converts all the calls above to AtolhStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtolhStk to do the work.

6.8 Atou, AtouCS, AtouTOS, AtouStk, Atoux

These routines convert a string of ASCII characters to a 16-bit unsigned integer value in the range 0..65535. You use these routines in a manner identical to the Atoix routines except that these routines do not allow a leading minus sign in front of the number and they allow positive values in the range 32768..65535. The regular expression for legal values is 




	["0".."9"] [["0".."9" | "_"]* ["0".."9"]]*

6.8.1 Calling Conventions and Assertions




Atou:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atou will skip leading spaces in the string before the conversion begins.

Atoux:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-digit (and non-underscore) character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atoux will skip leading spaces in the string before the conversion begins.





AtouCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	AX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtouCS will skip leading spaces in the string before the conversion begins.





AtouStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtouStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtouStk will skip leading spaces in the string before the conversion begins.





AtouTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtouTOS leaves the converted result on the top of the stack.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtouTOS will skip leading spaces in the string before the conversion begins.

6.8.2 Atou Addressing Modes

Atou Addressing Modes
Name Plain CS TOS Stk X CSi
Atou X X X X X -

The Atou macro allows the following operands:

Atou Extended Syntax (Single/No Operands)
Name No Operand byteVar Num const [word Var] [dword Var] String Const
Atou X X - X X -

Atou Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atou X - X X -

Atou Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atou X - X X -

6.8.3 Syntax & Examples




String2Convert  byte    "  12345  6789",0
Value           word    ?
Value2          word    ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                atou
                mov     Value, ax       ;Value = 12345

                atouCS
                dword   String2Convert
                mov     Value, ax       ;Value = 12345

                pshadrs String2Convert
                atouTOS
                pop     Value           ;Value = 12345

                pshadrs String2Convert
                pshadrs Value
                atouStk                 ;Value = 12345

                lesi    String2Convert
                atoux
                mov     Value, ax       ;Value = 12345
                atoux
                mov     Value2, ax      ;Value2 = 6789
The Atou routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atou calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atou routine; it expects a pointer to the string in ES:DI and returns the converted result in AX: 




                atou     ;Generates a call to the stdlib $atou routine.
The second version of the extended syntax Atou call lets you specify a single parameter. This must be the name of a byte variable, a [word] pointer, or a [dword] pointer. For byte variables, it calls AtouCS to do the conversion and returns the value in AX: 




                atou    String2Convert

; Equivalent to:

                atouCS
                dword   String2Convert
The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atou will put the result. This particular form calls the AtouStk routine: 




                atou    byteVar, wordVar
                atou    byteVar, [wordVar]
                atou    byteVar, [dwordVar]

                atou    [wordVar], wordVar
                atou    [wordVar], [wordVar]
                atou    [wordVar], [dwordVar]

                atou    [dwordVar], wordVar
                atou    [dwordVar], [wordVar]
                atou    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atou assumes that it's the name of a string variable. It converts that string to an integer. If the first parameter is of the form "[wordVar]" then Atou assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to an integer. If the first parameter is "[dwordVar]" then Atou assumes this is a dword variable containing a far pointer to the string, it converts that string to an integer.

The second parameter must be a word variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atou stores the converted integer in the word specified by this second parameter.

Note that Atou converts all the calls above to AtouStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtouStk to do the work.

6.9 Atoul, AtoulCS, Atoulx, AtoulStk, AtoulTOS

These routines convert a string of ASCII characters to a 32-bit unsigned integer value in the range 0..4294967295. You use these routines in a manner identical to the Atoux routines except they input 32-bit integers rather than 16-bit integers. See Atoux for more details.

6.9.1 Calling Conventions and Assertions




Atoul:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atoul will skip leading spaces in the string before the conversion begins.

Atoulx:
Inputs:	ES:DI points at the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	Does not preserve DI.  Assuming C=0 upon return, DI will point at the first non-digit (and non-underscore) character in the string.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.
Note:	Atoulx will skip leading spaces in the string before the conversion begins.





AtoulCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	EAX contains the unsigned result.  C=1 if there was a conversion error.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.
Note:	AtoulCS will skip leading spaces in the string before the conversion begins.





AtoulStk:
Inputs:	A far pointer to the string to convert (pushed first) and a far pointer to the word that will hold the result (pushed second) appear on the top of stack.
Outputs:	AtoulStk stores the converted result at the specified address.
Errors:	None.
Side Effects:	Pops the two pointers off the stack.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoulStk will skip leading spaces in the string before the conversion begins.





AtoulTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	AtoulTOS leaves the converted result on the top of the stack.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.
Note:	AtoulTOS will skip leading spaces in the string before the conversion begins.

6.9.2 Atoul Addressing Modes

Atoul Addressing Modes
Name Plain CS TOS Stk X CSi
Atoul X X X X X -

The Atoul macro allows the following operands:

Atoul Extended Syntax (Single/No Operands)
Name Plain byteVar Num const [word Var] [dword Var] String Const
Atoul X X - X X -

Atoul Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoul X - X X -

Atoul Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Atoul X - X X -

6.9.3 Syntax & Examples




String2Convert  byte    "  12345  6789",0
Value           dword   ?
Value2          dword   ?
wPtr            word    String2Convert
dPtr            dword   String2Convert

                lesi    String2Convert
                atoul
                mov     Value, eax      ;Value = 12345

                atoulCS
                dword   String2Convert
                mov     Value, eax      ;Value = 12345

                pshadrs String2Convert
                atoulTOS
                popd     Value          ;Value = 12345

                pshadrs String2Convert
                pshadrs Value
                atoulStk                ;Value = 12345

                lesi    String2Convert
                atoulx
                mov     Value, eax      ;Value = 12345
                atoulx
                mov     Value2, eax     ;Value2 = 6789
The Atoul routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Atoul calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Atoul routine; it expects a pointer to the string in ES:DI and returns the converted result in EAX: 




                atoul                   ;Generates a call to the stdlib $atoul routine.
The second version of the extended syntax Atoul call lets you specify a single parameter. This must be the name of a byte variable. Atoul assumes this is the name of a string variable that contains the value to convert. It calls AtoulCS to do the conversion and returns the value in EAX: 




                atoul    String2Convert

; Equivalent to:

                atoulCS
                dword   String2Convert
The third extended syntax form allows two parameters. The first specifies the address of the string to convert, the second specifies the address where Atoul will put the result. This particular form calls the AtoulStk routine: 




                atoul    byteVar, dwordVar
                atoul    byteVar, [wordVar]
                atoul    byteVar, [dwordVar]

                atoul    [wordVar], dwordVar
                atoul    [wordVar], [wordVar]
                atoul    [wordVar], [dwordVar]

                atoul    [dwordVar], dwordVar
                atoul    [dwordVar], [wordVar]
                atoul    [dwordVar], [dwordVar]
If the first parameter is a byte variable, Atoul assumes that it's the name of a string variable. It converts that string to an integer. If the first parameter is of the form "[wordVar]" then Atoul assumes that the word variable is a near pointer to a string. It converts the string pointed at by DS:[wordVar] to an integer. If the first parameter is "[dwordVar]" then Atoul assumes this is a dword variable containing a far pointer to the string, it converts that string to an integer.

The second parameter must be a dword variable, a near pointer ("[wordVar]"), or a far pointer ("[dwordVar]"). Atoul stores the converted integer in the dword specified by this second parameter.

Note that Atoul converts all the calls above to AtoulStk. It pushes a 32-bit address of the string onto the stack followed by the 32-bit address of the second operand. It then calls AtoulStk to do the work.

6.10 etoa, etoax, etoam

These routines convert a floating point number to the ASCII representation of that value in scientific notation.

6.10.1 Calling Conventions and Assertions




Etoa:
Inputs:	ST(0) contains the floating point value to convert. AL contians the number of print positions. ES:DI points at the buffer where Etoa will store its result.
Outputs:	The specified buffer holds a zero terminated string containing the result.
Errors:	If the number does not fit in the output buffer (i.e., if AL contains less than eight), then this functions writes pound signs ("#") to the buffer.
Side Effects:	None.
Assertions:	ES:DI points at a buffer with at least AL+1 available bytes.

Etoam:
Inputs:	ST(0) contains the floating point value to convert. AL contians the number of print positions
Outputs:	Etoam allocates storage for the resulting string on the heap  and returns a pointer to this converted string in ES:DI.
Errors:	If the number does not fit in the output buffer (i.e., if AL contains less than eight), then this functions writes pound signs ("#") to the buffer.  If insufficient memory is available on the heap, this function will raise an exception (assuming exceptions are enabled).
Side Effects:	None.
Assertions:	Sufficient memory exists on the heap.

Etoax:
Inputs:	ST(0) contains the floating point value to convert. AL contians the number of print positions. ES:DI points at the buffer where Etoa will store its result.
Outputs:	The specified buffer holds a zero terminated string containing the result.
Errors:	If the number does not fit in the output buffer (i.e., if AL contains less than eight), then this functions writes pound signs ("#") to the buffer.
Side Effects:	Etoax does not preserve the ES:DI register.  It leaves DI pointing at the zero byte immediately after the converted string.
Assertions:	ES:DI points at a buffer with at least AL+1 available bytes.

6.10.2 Etoa Addressing Modes

Etoa Addressing Modes
Name Plain CS TOS Stk X CSi m
Etoa X - - - X - X

Etoa does not provide an extended syntax.

6.10.3 Syntax & Examples




fVar            real8   3.14159
eVar            real8   2.71

fMsg            byte    "PI and E = "
fStr            byte    32 dup (?)
                 .
                 .
                 .
                fld     fVar
                lesi    fStr
                mov     al, 12
                etoa
                printf  "fStr = %s\n", fStr
                 .
                 .
                 .
                fld     fVar
                mov     al, 12
                etoam
                print   "Value = "
                puts
                putcr
                 .
                 .
                 .
                fld     fVar
                lesi    fStr
                mov     al, 12
                etoax
                mov     byte ptr es:[di],','
                inc     di
                fld     eVar
                mov     al, 12
                etoa

6.11 ftoa, ftoax, ftoam

These routines convert a floating point number to the ASCII representation of that value in decimal notation.

6.11.1 Calling Conventions and Assertions




Ftoa:
Inputs:	ST(0) contains the floating point value to convert. AL contians the number of print positions. AH contains the number of print positions to the right of the decimal point. ES:DI points at the buffer where ftoa will store its result.
Outputs:	The specified buffer holds a zero terminated string containing the result.
Errors:	If the number does not fit in the output buffer, then this functions writes pound signs ("#") to the buffer.
Side Effects:	None.
Assertions:	ES:DI points at a buffer with at least AL+1 available bytes.

Ftoam:
Inputs:	ST(0) contains the floating point value to convert. AL contains the number of print positions.  AH contains the number of positions after the decimal point.
Outputs:	Ftoam allocates storage for the resulting string on the heap  and returns a pointer to this converted string in ES:DI.
Errors:	If the number does not fit in the output buffer, then this functions writes pound signs ("#") to the buffer.  If insufficient memory is available on the heap, this function will raise an exception (assuming exceptions are enabled).
Side Effects:	None.
Assertions:	There is a value on the floating point stack.

Ftoax:
Inputs:	ST(0) contains the floating point value to convert. AL contians the number of print positions. AH contains the number of print positions to the right of the decimal point.  ES:DI points at the buffer where Ftoa will store its result.
Outputs:	The specified buffer holds a zero terminated string containing the result.
Errors:	If the number does not fit in the output buffer (i.e., if AL contains less than eight), then this functions writes pound signs ("#") to the buffer.
Side Effects:	Ftoax does not preserve the ES:DI register.  It leaves DI pointing at the zero byte immediately after the converted string.
Assertions:	ES:DI points at a buffer with at least AL+1 available bytes.  The floating point stack must contain a value.

6.11.2 Ftoa Addressing Modes

Ftoa Addressing Modes
Name Plain CS TOS Stk X CSi m
Ftoa X - - - X - X

Ftoa does not provide an extended syntax.

6.11.3 Syntax & Examples




fVar            real8   3.14159
eVar            real8   2.71

fMsg            byte    "PI and E = "
fStr            byte    32 dup (?)
                 .
                 .
                 .
                fld     fVar
                lesi    fStr
                mov     al, 8
                mov     ah, 5
                ftoa
                printf  "fStr = %s\n", fStr
                 .
                 .
                 .
                fld     fVar
                mov     al, 8
                mov     ah, 5
                ftoam
                print   "Value = "
                puts
                putcr
                 .
                 .
                 .
                fld     fVar
                lesi    fStr
                mov     al, 8
                mov     ah, 5
                etoax
                mov     byte ptr es:[di],','
                inc     di
                fld     eVar
                mov     al, 9
                mov     ah, 5
                ftoa

6.12 Htoa, HtoaCS, HtoaStk, HtoaTOS, Htoax, Htoam

These routines convert an 8-bit integer value to a string containing exactly two characters (plus a zero terminating byte). The string is the hexadecimal representation of the unsigned integer value. These routines print any necessary leading zeros; the string is always exactly two characters long.

6.12.1 Calling Conventions and Assertions




Htoa:
Inputs:	AL contains the integer value to convert. ES:DI points at a string that can hold at least three bytes (two digits plus a zero terminating character).
Outputs:	Htoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at an array that can hold at least three bytes.

Htoam:
Inputs:	AL contains the integer value to convert.
Outputs:	Htoa stores the converted string onto the heap.  It returns a pointer to the string in the ES:DI register pair.
Errors:	The malloc routine raises an exception if there is insufficient room on the heap..
Side Effects:	None.
Assertions:	Sufficient memory is available on the heap.

Htoax:
Inputs:	AL contains the integer value to convert. ES:DI points at a string that can hold at least three bytes (two digits plus a zero terminating character).
Outputs:	Htoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	Does not preserve DI.  This routine leaves DI pointing at the zero byte at the end of the converted string.
Assertions:	ES:DI points at an array that can hold at least three bytes.

HtoaCS:
Inputs:	AL contains the eight-bit integer value to convert. A far pointer to a string buffer that will hold the result immediate follows the call in the code stream.
Outputs:	HtoaCS stores the converted string at the location pointed by the far pointer in the code stream.
Errors:	None.
Side Effects:	On return, HtoaCS modifies the return address so that the return operation skips over the far pointer following the call in the code stream.
Assertions:	The far pointer in the code stream points at an array that can hold at least three bytes.

HtoaTOS:
Inputs:	The TOS contains a 16-bit value.  HtoaTOS converts the L.O. byte of this 16-bit value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  HtoaTOS stores the converted string at this address.
Outputs:	HtoaTOS stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the value and far pointer off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least three bytes.

HtoaSTK:
Inputs:	The TOS contains a 32-bit far pointer that points at an eight-bit value in memory.  HtoaStk converts this value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  HtoaStk stores the converted string at this address.
Outputs:	HtoaStk stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the two far pointers off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least three bytes.

6.12.2 Htoa Addressing Modes

Htoa Addressing Modes
Name Plain CS TOS Stk X CSi m
Htoa X X X X X - X

The Htoa macro allows the following operands:

Htoa Extended Syntax (Single/No Operands)
Name Plain byteVar Num const [word Var] [dword Var] String Const
Htoa X X - X X -

Htoa Two-Operand Syntax (First Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Htoa X - X X -

Htoa Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Htoa X - X X -

6.12.3 Syntax & Examples




String2Convert  byte    32 dup (0)
Value           byte    0ABh
Value2          byte    67h
wPtr            word    Value
dPtr            dword   Value2

                mov     al, Value
                lesi    String2Convert
                htoax
                mov     byte ptr es:[di], ' '
                mov     al, Value2
                htoa
                printf  "Str2Cnvrt=%s\n", String2Convert
                 .
                 .
                 .
                mov     al, Value
                htoaCS
                dword   String2Convert
                printf  "Str2Cnvrt=%s\n", String2Convert
                 .
                 .
                 .
                pshadrs String2Convert
                push    word ptr Value2
                htoaStk
                printf  "String2Convert=%s\n", String2Convert
                 .
                 .
                 .
                pshadrs String2Convert
                push    word ptr Value          ;Ignores H.O. byte
                htoaTOS
                printf  "String2Convert=%s\n", String2Convert
The Htoa routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Htoa calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard htoa routine; it expects a pointer to the string in ES:DI and the value to convert in AL: 




                htoa   ;Generates a call to the stdlib $htoa routine.
The second version of the extended syntax htoa call lets you specify a single string parameter (the value to convert is assumed to be in the AL register). If this is the name of a byte variable, htoa assumes this is the name of a string variable where it stores the converted string.. It calls htoaCS to do the conversion: 




                htoa    String2Convert

; Equivalent to:

                htoaCS
                dword   String2Convert
If this is a [wvar] or [dwvar] operand (word pointer or double word pointer), then htoa assumes the specified variable is a pointer to the array that will hold the string. In either case ([wordvar] or [dwordvar]) the macro pushes the far address onto the stack along with the value to convert and calls the htoaTOS routine to do the conversion.

The third extended syntax form allows two parameters. The first specifies the value to convert, the second specifies the address where htot will store the converted string. This particular form calls the htoaStk routine: 




;                       Value     string
;                       -------- ------------
                htoa    byteVar, byteVar
                htoa    byteVar, [wordVar]
                htoa    byteVar, [dwordVar]

                htoa    [wordVar], wordVar
                htoa    [wordVar], [wordVar]
                htoa    [wordVar], [dwordVar]

                htoa    [dwordVar], wordVar
                htoa    [dwordVar], [wordVar]
                htoa    [dwordVar], [dwordVar]
The first parameter must be a byte variable or a pointer to a byte variable. The second parameter must be a pointer to an array that has enough storage to hold three characters (two digits and a zero terminating byte).

6.13 ISize, ISizeCS, ISizeStk, ISizeTOS

These routines determine the number of print positions a 16-bit integer will require on output. The value these functions return include a print position for a minus sign if the number is negative.

6.13.1 Calling Conventions and Assertions




ISize:
Inputs:	AX contains the integer value test.
Outputs:	ISize returns the number of print positions in EAX (1-5).
Errors:	None.
Side Effects:	None.

ISizeCS:
Inputs:	A far pointer to a 16-bit signed integer value immediately follows the call in the code stream.
Outputs:	ISizeCS returns the size of the integer in EAX.
Errors:	None.
Side Effects:	On return, ISizeCS modifies the return address so that the return operation skips over the far pointer following the call in the code stream.

ISizeTOS:
Inputs:	The TOS contains the signed 16-bit value to test.
Outputs:	ISizeTOS returns the size of the integer in EAX.
Errors:	None.
Side Effects:	Pops the far pointer off the stack upon return.

ISizeSTK:
Inputs:	The TOS contains a 32-bit far pointer that points at a 16-bit value in memory to test.
Outputs:	ISizeStk returns the size of the integer in the EAX register.
Errors:	None.
Side Effects:	Pops the far pointer off the stack upon return.

6.13.2 ISize Addressing Modes

ISize Addressing Modes
Name Plain CS TOS Stk X CSi m
ISize X X X X - - -

The ISize macro allows the following operands:

ISize Extended Syntax (Single/No Operands)
Name Plain word Var Num const [word Var] [dword Var] String Const
ISize X X - X X -

6.13.3 Syntax & Examples

The following example demonstrates how to create left and right justified versions of an integer value for possible output: 




Value           word    123
ValPtr1         word    Value
ValPtr2         dword   Value
                 .
                 .
                 .

; Output an integer right justified in a field of 12 print positions
; (This is, essentially, how PutISize works).

                mov     ax, Value
                ISize
                add     ax, -12         ;Compute ISize(value) - 12.
                neg     ax              ;Compute 12-ISize(value).
                call    PrtSpcs
                puti    Value
                 .
                 .
                 .

; Output an integer left justified in a field of 12 print positions.

                mov     ax, Value
                puti
                ISize
                add     ax, -12         ;Compute ISize(value) - 12.
                neg     ax              ;Compute 12-ISize(value).
                call    PrtSpcs
The ISize macro also supports an extended syntax. Without any parameters, ISize simply calls the StdLib $ISize procedure. With a word parameter, ISize calls the StdLib $ISizeCS procedure. With a word pointer or dword pointer argument, ISize calls the StdLib $ISizeStk routine. 




                ISize                   ;Calls $ISize
                
;The following are equivalent:

                ISize   Value
                
                ISizeCS
                dword   Value
                
;The following are equivalent:

                ISize   [ValPtr1]
                
                push    ds
                push    ValPtr1
                ISizeStk
                
;The following are equivalent:

                ISize   [ValPtr2]
                
                pushd   ValPtr2
                ISizeStk
                  .
                  .
                  .
prtspcs         proc    near
                push    eax
                mov     cx, ax
                mov     al, ' '
                jcxz    psDone
PrtLp:          putc
                loop    PrtLp
psDone:         pop     eax
                ret
prtspcs         endp

6.14 Itoa, ItoaCS, ItoaStk, ItoaTOS, Itoax, Itoam

These routines convert a 16-bit integer value to a string of decimal characters (plus a zero terminating byte). These routines supress any leading zeros unless, of course, the integer value is zero. If the integer value is negative, these routines emit a leading minus sign.

6.14.1 Calling Conventions and Assertions




Itoa:
Inputs:	AX contains the integer value to convert. ES:DI points at a string that can hold at least seven bytes (a possible minus sign, up to five digits, and a zero terminating character).
Outputs:	Itoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at an array that can hold at least seven bytes.

Itoam:
Inputs:	AX contains the integer value to convert.
Outputs:	Itoa stores the converted string onto the heap.  It returns a pointer to the string in the ES:DI register pair.
Errors:	The malloc routine raises an exception if there is insufficient room on the heap.
Side Effects:	None.
Assertions:	Sufficient memory is available on the heap.

Itoax:
Inputs:	AX contains the integer value to convert. ES:DI points at a string that can hold at least seven bytes (a minus sign, five digits, and a zero terminating byte).
Outputs:	Itoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	Does not preserve DI.  This routine leaves DI pointing at the zero byte at the end of the converted string.
Assertions:	ES:DI points at an array that can hold at least seven bytes.

ItoaCS:
Inputs:	AX contains the 16-bit integer value to convert. A far pointer to a string buffer that will hold the result immediately follows the call in the code stream.
Outputs:	ItoaCS stores the converted string at the location pointed by the far pointer in the code stream.
Errors:	None.
Side Effects:	On return, ItoaCS modifies the return address so that the return operation skips over the far pointer following the call in the code stream.
Assertions:	The far pointer in the code stream points at an array that can hold at least seven bytes.

ItoaTOS:
Inputs:	The TOS contains a 16-bit value.  ItoaTOS converts this 16-bit value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  ItoaTOS stores the converted string at this address.
Outputs:	ItoaTOS stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the value and far pointer off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least seven bytes.

ItoaSTK:
Inputs:	The TOS contains a 32-bit far pointer that points at a 16-bit value in memory.  ItoaStk converts this value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  ItoaStk stores the converted string at this address.
Outputs:	ItoaStk stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the two far pointers off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least seven bytes.

6.14.2 Itoa Addressing Modes

Itoa Addressing Modes
Name Plain CS TOS Stk X CSi m
Itoa X X X X X - X

The Itoa macro allows the following operands:

Itoa Extended Syntax (Single/No Operands)
Name Plain word Var Num const [word Var] [dword Var] String Const
Itoa X X - X X -

Itoa Two-Operand Syntax (First Operand)
Name word var Num const [word Var] [dword Var] String Const
Itoa X - X X -

Itoa Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Itoa X - X X -

6.14.3 Syntax & Examples




ConvertedStr    byte    32 dup (0)
Value           word    -12345
Value2          word    4321
wPtr            word    Value
dPtr            dword   Value2
sptr            dword   ConvertedStr
                 .
                 .
                 .
                mov     ax, Value
                lesi    ConvertedStr
                itoa
                printf  "ConvertedStr=%s\n", ConvertedStr
                 .
                 .
                 .
                mov     ax, Value2
                itoam
                print   "ConvertedStr="
                puts
                free
                putcr
                 .
                 .
                 .
                mov     ax, Value
                lesi    ConvertedStr
                itoax
                mov     byte ptr es:[di], ' '
                mov     ax, Value2
                itoax
                printf  "Value & value2 = %s\n", ConvertedStr
                 .
                 .
                 .
                mov     ax, Value
                itoaCS
                dword   ConvertedStr
                printf  "ConvertedStr=%s\n", ConvertedStr
                 .
                 .
                 .
                pshadrs ConvertedStr
                push    Value
                itoaTOS
                printf  "Value=%s\n", ConvertedStr
                 .
                 .
                 .
                pshadrs ConvertedStr
                pshadrs Value2
                itoaStk
                printf  "Value2=%s\n", ConvertedStr
The Itoa routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Itoa calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard itoa routine; it expects a pointer to the string in ES:DI and the value to convert in AX: 




                itoa   ;Generates a call to the stdlib $itoa routine.
The second version of the extended syntax itoa call lets you specify a single string parameter (the value to convert is assumed to be in the AX register). If this is the name of a byte variable, itoa assumes this is the name of a string variable where it stores the converted string.. It calls itoaCS to do the conversion: 




                itoa    ConvertedStr

; Equivalent to:

                itoaCS
                dword   ConvertedStr
If this is a [wvar] or [dwvar] operand (word pointer or double word pointer), then itoa assumes the specified variable is a pointer to the array that will hold the string. In either case ([wordvar] or [dwordvar]) the macro pushes the far address onto the stack along with the value to convert and calls the itoaTOS routine to do the conversion.

The third extended syntax form allows two parameters. The first specifies the value to convert, the second specifies the address where itoa will store the converted string. This particular form calls the itoaStk routine: 




;                       Value     string
;                       -------- ------------
                itoa    byteVar, byteVar
                itoa    byteVar, [wordVar]
                itoa    byteVar, [dwordVar]

                itoa    [wordVar], wordVar
                itoa    [wordVar], [wordVar]
                itoa    [wordVar], [dwordVar]

                itoa    [dwordVar], wordVar
                itoa    [dwordVar], [wordVar]
                itoa    [dwordVar], [dwordVar]
The first parameter must be a word variable or a pointer to a word variable. The second parameter must be a pointer to an array that has enough storage to hold seven characters (a leading minus sign, five digits, and a zero terminating byte).

6.15 LSize, LSizeCS, LSizeStk, LSizeTOS

These routines determine the number of print positions a 32-bit signed integer will require on output. The value these functions return include a print position for a minus sign if the number is negative.

6.15.1 Calling Conventions and Assertions




LSize:
Inputs:	EAX contains the integer value test.
Outputs:	LSize returns the number of print positions in EAX (1-5).
Errors:	None.
Side Effects:	None.

LSizeCS:
Inputs:	A far pointer to a 32-bit signed integer value immediately follows the call in the code stream.
Outputs:	LSizeCS returns the size of the integer in EAX.
Errors:	None.
Side Effects:	On return, LSizeCS modifies the return address so that the return operation skips over the far pointer following the call in the code stream.

LSizeTOS:
Inputs:	The TOS contains the signed 32-bit value to test.
Outputs:	LSizeTOS returns the size of the integer in EAX.
Errors:	None.
Side Effects:	Pops the far pointer off the stack upon return.

LSizeSTK:
Inputs:	The TOS contains a 32-bit far pointer that points at a 32-bit value in memory to test.
Outputs:	LSizeStk returns the size of the integer in the EAX register.
Errors:	None.
Side Effects:	Pops the far pointer off the stack upon return.

6.15.2 LSize Addressing Modes

LSize Addressing Modes
Name Plain CS TOS Stk X CSi m
LSize X X X X - - -

The LSize macro allows the following operands:

LSize Extended Syntax (Single/No Operands)
Name Plain word Var Num const [word Var] [dword Var] String Const
LSize X X - X X -

6.15.3 Syntax & Examples

The following example demonstrates how to create left and right justified versions of an integer value for possible output: 




Value           sdword  123
ValPtr1         word    Value
ValPtr2         dword   Value
                 .
                 .
                 .

; Output an integer right justified in a field of 12 print positions
; (This is, essentially, how PutLSize works).

                mov     eax, Value
                LSize
                add     ax, -12         ;Compute LSize(value) - 12.
                neg     ax              ;Compute 12-LSize(value).
                call    PrtSpcs
                putl    Value
                 .
                 .
                 .

; Output an integer left justified in a field of 12 print positions.

                mov     eax, Value
                putl
                LSize
                add     ax, -12         ;Compute LSize(value) - 12.
                neg     ax              ;Compute 12-LSize(value).
                call    PrtSpcs
The LSize macro also supports an extended syntax. Without any parameters, LSize simply calls the StdLib $LSize procedure. With a word parameter, LSize calls the StdLib $LSizeCS procedure. With a word pointer or dword pointer argument, LSize calls the StdLib $LSizeStk routine. 




                LSize                   ;Calls $LSize
                
;The following are equivalent:

                LSize   Value
                
                LSizeCS
                dword   Value
                
;The following are equivalent:

                LSize   [ValPtr1]
                
                push    ds
                push    ValPtr1
                LSizeStk
                
;The following are equivalent:

                LSize   [ValPtr2]
                
                pushd   ValPtr2
                LSizeStk
                  .
                  .
                  .
prtspcs         proc    near
                push    eax
                mov     cx, ax
                mov     al, ' '
                jcxz    psDone
PrtLp:          putc
                loop    PrtLp
psDone:         pop     eax
                ret
prtspcs         endp

6.16 Ltoa, LtoaCS, LtoaStk, LtoaTOS, Ltoax, Ltoam

These routines convert a 32-bit signed integer value to a string of decimal characters (plus a zero terminating byte). These routines supress any leading zeros unless, of course, the integer value is zero. If the integer value is negative, these routines emit a leading minus sign.

6.16.1 Calling Conventions and Assertions




Ltoa:
Inputs:	EAX contains the integer value to convert. ES:DI points at a string that can hold at least 12 bytes (a possible minus sign, up to ten digits, and a zero terminating character).
Outputs:	Ltoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	None.
Assertions:	ES:DI points at an array that can hold at least 12 bytes.

Ltoam:
Inputs:	EAX contains the integer value to convert.
Outputs:	Ltoa stores the converted string onto the heap.  It returns a pointer to the string in the ES:DI register pair.
Errors:	The malloc routine raises an exception if there is insufficient room on the heap.
Side Effects:	None.
Assertions:	Sufficient memory is available on the heap.

Ltoax:
Inputs:	EAX contains the integer value to convert. ES:DI points at a string that can hold at least 12 bytes (a minus sign, ten digits, and a zero terminating byte).
Outputs:	Ltoa stores the converted string at the location pointed by ES:DI.
Errors:	None.
Side Effects:	Does not preserve DI.  This routine leaves DI pointing at the zero byte at the end of the converted string.
Assertions:	ES:DI points at an array that can hold at least 12 bytes.

LtoaCS:
Inputs:	EAX contains the 32-bit integer value to convert. A far pointer to a string buffer that will hold the result immediately follows the call in the code stream.
Outputs:	LtoaCS stores the converted string at the location pointed by the far pointer in the code stream.
Errors:	None.
Side Effects:	On return, LtoaCS modifies the return address so that the return operation skips over the far pointer following the call in the code stream.
Assertions:	The far pointer in the code stream points at an array that can hold at least 12 bytes.

LtoaTOS:
Inputs:	The TOS contains a 32-bit signed integer.  LtoaTOS converts this 32-bit value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  LtoaTOS stores the converted string at this address.
Outputs:	LtoaTOS stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the value and far pointer off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least 12 bytes.

LtoaSTK:
Inputs:	The TOS contains a 32-bit far pointer that points at a 32-bit signed integer value in memory. LtoaStk converts this value to a string.  NOS (next on stack, just above the TOS value) is a 32-bit far pointer.  LtoaStk stores the converted string at this address.
Outputs:	LtoaStk stores the converted string at the location pointed by the far pointer on NOS.
Errors:	None.
Side Effects:	Pops the two far pointers off the stack upon return.
Assertions:	The far pointer on NOS points at an array that can hold at least 12 bytes.

6.16.2 Ltoa Addressing Modes

Ltoa Addressing Modes
Name Plain CS TOS Stk X CSi m
Ltoa X X X X X - X

The Ltoa macro allows the following operands:

Ltoa Extended Syntax (Single/No Operands)
Name Plain word Var Num const [word Var] [dword Var] String Const
Ltoa X X - X X -

Ltoa Two-Operand Syntax (First Operand)
Name word var Num const [word Var] [dword Var] String Const
Ltoa X - X X -

Ltoa Two-Operand Syntax (Second Operand)
Name byteVar Num const [word Var] [dword Var] String Const
Ltoa X - X X -

6.16.3 Syntax & Examples




ConvertedStr    byte    32 dup (0)
Value           sdword  -123456789
Value2          sdword  987654321
wPtr            word    Value
dPtr            dword   Value2
sptr            dword   ConvertedStr
                 .
                 .
                 .
                mov     eax, Value
                lesi    ConvertedStr
                ltoa
                printf  "ConvertedStr=%s\n", ConvertedStr
                 .
                 .
                 .
                mov     eax, Value2
                ltoam
                print   "ConvertedStr="
                puts
                free
                putcr
                 .
                 .
                 .
                mov     eax, Value
                lesi    ConvertedStr
                ltoax
                mov     byte ptr es:[di], ' '
                mov     eax, Value2
                ltoax
                printf  "Value & value2 = %s\n", ConvertedStr
                 .
                 .
                 .
                mov     eax, Value
                ltoaCS
                dword   ConvertedStr
                printf  "ConvertedStr=%s\n", ConvertedStr
                 .
                 .
                 .
                pshadrs ConvertedStr
                push    Value
                ltoaTOS
                printf  "Value=%s\n", ConvertedStr
                 .
                 .
                 .
                pshadrs ConvertedStr
                pshadrs Value2
                ltoaStk
                printf  "Value2=%s\n", ConvertedStr
The Ltoa routines also allow the extended syntax using the stdlib "addressing modes." There are three basic forms for these Ltoa calls: "plain" without any parameters, a single parameter version, and several two-parameter versions.

The plain version (without any parameters) simply calls the standard Ltoa routine; it expects a pointer to the string in ES:DI and the value to convert in EAX: 




                ltoa   ;Generates a call to the stdlib $ltoa routine.
The second version of the extended syntax Ltoa call lets you specify a single string parameter (the value to convert is assumed to be in the EAX register). If this is the name of a byte variable, ltoa assumes this is the name of a string variable where it stores the converted string.. It calls LtoaCS to do the conversion: 




                ltoa    ConvertedStr

; Equivalent to:

                ltoaCS
                dword   ConvertedStr
If this is a [wvar] or [dwvar] operand (word pointer or double word pointer), then ltoa assumes the specified variable is a pointer to the array that will hold the string. In either case ([wordvar] or [dwordvar]) the macro pushes the far address onto the stack along with the value to convert and calls the ltoaTOS routine to do the conversion.

The third extended syntax form allows two parameters. The first specifies the value to convert, the second specifies the address where ltoa will store the converted string. This particular form calls the ltoaStk routine: 




;                       Value     string
;                       -------- ------------
                ltoa    byteVar, byteVar
                ltoa    byteVar, [wordVar]
                ltoa    byteVar, [dwordVar]

                ltoa    [wordVar], wordVar
                ltoa    [wordVar], [wordVar]
                ltoa    [wordVar], [dwordVar]

                ltoa    [dwordVar], wordVar
                ltoa    [dwordVar], [wordVar]
                ltoa    [dwordVar], [dwordVar]
The first parameter must be a word variable or a pointer to a word variable. The second parameter must be a pointer to an array that has enough storage to hold 12 characters (a leading minus sign, ten digits, and a zero terminating byte).

6.17 toFlt, toFltStk,toFltCS

These routines are very similar to Atof, Atofx, and AtofStk. There are three primary differences between the toFlt* and the Atof* routines: 




(1)	The Atof* routines are sloppy.  They allow leading spaces and allow the number to end with any arbitrary non-digit character.  The toFlt* routines are more rigorous in their checking.  In particular, the characters that appear in the string must be part of the number.  The conversion must end on a zero terminating byte, not an arbitrary character.

(2)	If exceptions are initialized and enabled, these routines generate a conversion exception when an error occurs.

(3)	There is no need for a toFltx routine because of point (1) above.  Leaving the ES:DI register pair pointing at the zero terminating byte would be of little use.

6.17.1 Calling Conventions and Assertions




toFlt:
Inputs:	ES:DI points at the string to convert.
Outputs:	ST(0)  contains the real result.  C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	Raises a $Conversion exception if there is a conversion error and exceptions are active.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some real number.

toFltStk:
Inputs:	A far pointer to the string to convert appears on the top of stack.
Outputs:	ST(0)  contains the real result.  C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	Pops pointer to string off the stack. Raises a $Conversion exception if there is a conversion error and exceptions are active.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some real number.

ToFltCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	ST(0) contains the floating point result. C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the address of an ASCII representation of some number.

6.17.2 ToFlt Addressing Modes

ToFlt Addressing Modes
Name Plain CS TOS Stk X CSi
ToFlt X X - X - -

The ToFlt macro does not provide any extended syntax:

6.17.3 Syntax & Examples




String2Convert  byte    "-12345.6789",0
BadString       byte    "ABCD",0
                 .
                 .
                 .
                InitExcept
                 .
                 .
                 .
                lesi    String2Convert
                toFlt
                mov     ax, 40Bh
                putf                    ;Prints -12345.6789
                putcr
                 .
                 .
                 .
                try
                 .
                 .
                 .
                lesi    BadString
                toFlt                   ;Raises an exception,
                putf                    ; does not print
                putcr                   ; anything here.
                 .
                 .
                 .
                exception $Conversion
                print   "Conversion error occured",nl
                 .
                 .
                 .
                endtry
                 .
                 .
                 .
                CleanUpEx

6.18 toHex, toHexStk, toHexTOS, toHexCS

These routines are very similar to Atoh and AtohStk. There are three primary differences between the toHex* and the Atoh* routines: 




(1)	The Atoh* routines are sloppy.  They allow leading spaces and allow the number to end with any arbitrary non-digit character.  The toHex* routines are more rigorous in their checking.  In particular, the characters that appear in the string must be part of the number.  The conversion must end on a zero terminating byte, not an arbitrary character.

(2)	If exceptions are initialized and enabled, these routines generate a conversion exception when an error occurs.

(3)	There is no need for a toHexx routine because of point (1) above.  Leaving the ES:DI register pair pointing at the zero terminating byte would be of little use.

6.18.1 Calling Conventions and Assertions




toHex:
Inputs:	ES:DI points at the string to convert.
Outputs:	AX contains the hexadecimal result.  C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	Raises a $Conversion exception if there is a conversion error and exceptions are active.
Assertions:	ES:DI points at a reasonable location containing the ASCII representation of some number.

toHexStk:
Inputs:	A far pointer to the string to convert appears on the top of stack.
Outputs:	AX contains the hexadecimal result.  C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	Pops pointer to string off the stack. Raises a $Conversion exception if there is a conversion error and exceptions are active.
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.

ToHexTOS:
Inputs:	A far pointer to the string to convert (pushed first)  appears on the top of stack.
Outputs:	ToHexTOS leaves the converted result on the top of the stack. C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	Removes two bytes from the stack (result is two bytes, it replaces a four-byte pointer).
Assertions:	Far pointer points at a reasonable location containing the ASCII representation of some number.

ToHexCS:
Inputs:	A dword pointer immediately following the call in the code stream contains a pointer to the string to convert.
Outputs:	AX contains the signed result. C=1 if there was a conversion error and exceptions are not active.
Errors:	None.
Side Effects:	None.
Assertions:	The return address points at a reasonable location containing the ASCII representation of some number.

6.18.2 ToHex Addressing Modes

ToHex Addressing Modes
Name Plain CS TOS Stk X CSi
ToHex X