ex13_1.in

ART OF Assembly Language Programming, 很不错

		      characters (HTOA/HTOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (HTOA2 only).

Flags affected:      Carry set denotes memory allocation error (HTOAM only)


Description:    The HTOAx routines convert an 8-bit value in AL to the two-
		character hexadecimal representation of that byte.  Other
		that that, they behave just like ITOAx/UTOAx.  Note that
		the resulting buffer must have at least three bytes for
		HTOA/HTOA2.


Include:        stdlib.a or conv.a


Routine:  WTOA (2,M)
--------------------

Category:             Conversion Routine

Registers on Entry:   AX- 16-bit value to convert to a string
		      ES:DI- Pointer to buffer to hold result (WTOA/WTOA2
			     only).

Registers on Return:  ES:DI- Pointer to string containing converted
		      characters (WTOA/WTOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (WTOA2 only).

Flags Affected:       Carry set denotes memory allocation error (WTOAM only)

Example of Usage:
		      Like WTOA above


Description:  WTOAx converts the 16-bit value in AX to a string of four
	      hexadecimal digits. It behaves exactly like HTOAx except
	      it outputs four characters (and requires a five byte buffer).


Include:        stdlib.a or conv.a



Routine:  LTOA (2,M)
--------------------

Category:             Conversion Routine

Registers on entry:   DX:AX (contains a signed 32 bit integer)
		      ES:DI- Pointer to buffer to hold result (LTOA/LTOA2
			     only).

Registers on Return:  ES:DI- Pointer to string containing converted
		      characters (LTOA/LTOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (LTOA2 only).

Flags affected:       Carry set if memory allocation error (LTOAM only)


Example of Usage: 
			mov	di, seg buffer	;Get address of storage
			mov	es, di		; buffer.
			lea	di, buffer
			mov	ax, word ptr value
			mov	dx, word ptr value+2
			ltoa

Description:    LtoA converts the 32-bit signed integer in DX:AX to a string
		of characters.  LTOA stores the string at the address specified
		in ES:DI (there must be at least twelve bytes available at
		this address) and returns with ES:DI pointing at this buffer.
		LTOA2 works the same way, except it returns with ES:DI
		pointing at the zero terminating byte.  LTOAM allocates
		storage for the string on the heap and returns a pointer
		to the string in ES:DI.

Include:        stdlib.a or conv.a



Routine:  ULTOA (2,M)
---------------------

Category:             Conversion Routine

Registers on Entry:   DX:AX- Unsigned 32-bit value to convert to a string
		      ES:DI- Pointer to buffer to hold result (LTOA/LTOA2
			     only).
Registers on Return:  ES:DI- Pointer to string containing converted
		      characters (LTOA/LTOAM only).
		      ES:DI- Pointer to zero-terminating byte of converted
			     string (LTOA2 only).

Flags Affected:       Carry is set if malloc error (ULTOAM only)

Example of Usage:  
                      Like LTOA


Description:  Like LTOA except this routine handles unsigned integer values.

Include:	stdlib.a or conv.a



Routine:  SPrintf (2,M)
-----------------------

Category:            Conversion Routine
		     In-Memory Formatting Routine

Registers on entry:  CS:RET - Pointer to format string and operands of the
			      sprintf routine
		     ES:DI-   Address of buffer to hold output string
			      (sprintf/sprintf2 only)

Register on return:  ES:DI register - pointer to a string containing
				      output data (sprintf/sprintfm only).
				      Pointer to zero-terminating byte at the
				      end of the converted string (sprintf2
				      only).

Flags affected:      Carry is set if memory allocation error (sprintfm only).

Example of Usage:
		     sprintfm
		     db      "I=%i, U=%u, S=%s",13,10,0
		     db      i,u,s
		     puts
		     free


Description:   SPrintf is an in-memory formatting routine. It is similar to
	       C's sprintf routine.

	       The programmer selects the maximum length of the output string.
	       SPrintf works in a manner quite similar to printf, except sprintf
	       writes its output to a string variable rather than to the stdlib
	       standard output.

	       SPrintfm, by default, allocates 2048 characters for the string
	       and then deallocates any unnecessary storage.  An external
	       variable, sp_MaxBuf, holds the number of bytes to allocate upon
	       entry into sprintfm.  If you wish to allocate more or less than
	       2048 bytes when calling sprintf, simply change the value of this
	       public variable (type is word).  Sprintfm calls malloc to
	       allocate the storage dynamically.  You should call free to
	       return this buffer to the heap when you are through with it.

	       Sprintf and Sprintf2 expect you to pass the address of a buffer
	       to them.  You are responsible for supplying a sufficiently
	       sized buffer to hold the result.

Include:             stdlib.a or conv.a



Routine:  SScanf
----------------

Category:              Conversion Routine
		       Formatted In-Memory Conversion Routine

Registers on Entry:    ES:DI - points at string containing values to convert

Registers on return:   None

Flags affected:	       None

Example of Usage:

	      ; this code reads the values for i, j, and s from the characters
	      ; starting at memory location Buffer.

		       les   di, Buffer
		       SScanf
		       db    "%i %i %s",0
		       dd     i, j, s


Description:  SScanf provides formatted input in a fashion analogous to scanf.
              The difference is that scanf reads in a line of text from the
              stdlib standard input whereas you pass the address of a sequence
              of characters to SScanf in es:di.


Include:                stdlib.a or conv.a




Routine:  ToLower
-----------------

Category:            Conversion Routine

Register on entry:   AL- Character to (possibly) convert
				to lower case.

Register on return:  AL- Converted character.

Flags affected:      None

Example of usage:
		     mov     al, char
		     ToLower


Description:  ToLower checks the character in the AL register, if it is upper
	      case it converts it to lower case.  If it is anything else,
	      ToLower leaves the value in AL unchanged.  For high performance
	      this routine is implemented as a macro rather than as a
	      procedure call.  This routine is so short you would spend more
	      time actually calling the routine than executing the code inside.
	      However, the code is definitely longer than a (far) procedure
	      call, so if space is critical and you're invoking this code
	      several times, you may want to convert it to a procedure call to
	      save a little space.


Include:             stdlib.a or conv.a



Routine:   ToUpper
------------------

Category:             Conversion Routine

Registers on Entry:   AL- Character to (possibly) convert to upper case

Registers on Return:  AL- Converted character

Flags Affected:       None

Example of Usage:
		      mov  al, char
		      ToUpper


Description:  ToUpper checks the character in the AL register, if it is lower
	      case it converts it to upper case.  If it is anything else,
	      ToUpper leaves the value in AL unchanged.  For high performance
	      this routine is implemented as a macro rather than as a
	      procedure call (see ToLower, above).


Include:              stdlib.a or conv.a


=====================
Date & Time  Routines
=====================

These routines convert DOS system times and dates to/from ASCII strings.
They appear in this section rather than conversions because we eventually
intend to add date and time arithmetic to the package.

Note the time to string conversion routines do not output the hundredths of
a second.  Most applications do not need (or want) this.  If you want
hundredths of a second you can easily write a routine (using this code) or
modify the existing code to suit your purposes.




Routine:  DTOA (2,m)
--------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			CX-	Current year (in the range 1980-2099)
			DL-	Current day
			DH-	Current month
			ES:DI-	Points at buffer with room for at least
				nine bytes (DTOA/DTOA2 only).


Registers on Return: 	ES:DI-	DTOA sticks a string of the form MM/DD/YY
				into a buffer allocated on the heap (DTOAM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (DTOA2 only).

Flags Affected:       carry-	Set if memory allocation error (DTOAM only).


Example of Usage:

			mov	ah, 2ah		;Call DOS to get the system
			int	21h		; time (also see xDTOA)
			lesi	TodaysDate	;Buffer to store string.
			DTOA			;Convert date to string.

			mov	ah, 2ah
			int	21h
			lesi	TodaysDate2
			DTOA2

			mov	ah, 2ah
			int	21h
			DTOAM			;ES:DI is allocated on heap.

Description:

DTOA converts a DOS system date (in CX/DX) to an ASCII string and deposits
the characters into a buffer specified by ES:DI on input.  ES:DI must be at
least nine bytes long (eight bytes for mm/dd/yy plus the zero terminating
byte).

DTOA2 converts a DOS system date to an ASCII string just like DTOA above.
The only difference is that it does not preserve DI.  It leaves DI pointing
at the zero terminating byte at the end of the string.  This routine is use-
ful for building up long strings with a date somewhere in the middle.

DTOAM works like DTOA except you do not pass the pointer to a buffer in ES:DI.
Instead, DTOAM allocates nine bytes for the string on the heap.  It returns
a pointer to this new string in ES:DI.

Include:              stdlib.a or date.a

Routine:  xDTOA (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			ES:DI-	Points at buffer with room for at least
				nine bytes (xDTOA/xDTOA2 only).


Registers on Return: 	ES:DI-	DTOA sticks a string of the form MM/DD/YY
				into a buffer allocated on the heap (xDTOAM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (xDTOA2 only).

Flags Affected:       carry-	Set if memory allocation error (xDTOAM only).


Example of Usage:

			lesi	TodaysDate	;Buffer to store string.
			xDTOA			;Convert date to string.

			lesi	TodaysDate2
			xDTOA2

			mov	ah, 2ah
			int	21h
			xDTOAM			;ES:DI is allocated on heap.

Description:

These routines work just like DTOA, DTOA2, and DTOAM except you do not pass
in the date to them, they call DOS to read the current system date and
convert that to a string.

Include:              stdlib.a or date.a


Routine:  LDTOA (2,m)
---------------------

Category:       Date/Time Routines

Author:		Randall Hyde

Registers on Entry:
			CX-	Current year (in the range 1980-2099)
			DL-	Current day
			DH-	Current month
			ES:DI-	Points at buffer with room for at least
				nine bytes (DTOA/DTOA2 only).


Registers on Return: 	ES:DI-	DTOA sticks a string of the form "mmm dd, yyyy"
				into a buffer allocated on the heap (LDTOAM
				only).

			ES:DI-	Points at the zero terminating byte at the
				end of the string (LDTOA2 only).