strings.txt

来自「汇编编程艺术」· 文本 代码 · 共 923 行 · 第 1/2 页

String Handling Routines
------------------------

Manipulating text is a major part of many computer applications. Typically,
strings are inputed and interpreted. This interpretation may involve some
chores such as extracting certain part of the text, copying it, or comparing
with other strings.

The string manipulation routines in C provides various functions. Therefore,
the stdlib has some C-like string handling functions (e.g. strcpy, strcmp).
In C a string is an array of characters; similarly, the string are terminated
by a "0" as a null character. In general, the input strings of these routines
are pointed by ES:DI. In some routines, the carry flag will be set to indicate
an error.

The following string routines take as many as four different forms: strxxx,
strxxxl, strxxxm, and strxxxlm.  These routines differ in how they store
the destination string into memory and where they obtain their source strings.

Routines of the form strxxx generally expect a single source string address
in ES:DI or a source and destination string in ES:DI & DX:SI.  If these
routines produce a string, they generally store the result into the buffer
pointed at by ES:DI upon entry.  They return with ES:DI pointing at the
first character of the destination string.

Routines of the form strxxxl have a "literal source string".  A literal
source string follows the call to the routine in the code stream.  E.g.,

			strcatl
			db	"Add this string to ES:DI",0

Routines of the form strxxxm automatically allocate storage for a source
string on the heap and return a pointer to this string in ES:DI.

Routines of the form strxxxlm have a literal source string in the code
stream and allocate storage for the destination string on the heap.



Routine:  Strcpy (l)
--------------------

Category:             String Handling Routine

Registers on Entry:   ES:DI - pointer to source string (Strcpy only)
		      CS:RET - pointer to  source  string (Strcpy1 only)
		      DX:SI - pointer to destination string


Registers on return:  ES:DI - points at the destination string


Flags affected:	      None


Example of Usage:
		      mov     dx, seg Dest
		      mov     si, offset Dest
		      mov     di, seg Source
		      mov     es, di
		      mov     si, offset Source
		      Strcpy

		      mov     dx, seg Dest
		      mov     si, offset Dest
		      Strcpyl
		      db      "String to copy",0


Description:  Strcpy is used to copy a zero-terminated string from one
	      location to another.  ES:DI points at the source string,
	      DX:SI points at the destination address.  Strcpy copies all
	      bytes, up to and including the zero byte, from the source
	      address to the destination address.  The target buffer must
	      be large enough to hold the string.  Strcpy performs no error
	      checking on the size of the destination buffer.

	      Strcpyl copies the  zero-terminated string immediately following
	      the call instruction to the destination address specified by
	      DX:SI.  Again, this routine expects you to ensure that the
	      taraget buffer is large enough to hold the result.

	      Note: There are no "Strcpym" or "Strcpylm" routines.  The
	      reason is simple: "StrDup" and "StrDupl" provide these functions
	      using names which are familiar to MSC and Borland C users.

Include:              stdlib.a or strings.a


Routine:  StrDup (l)
--------------------

Category:            String Handling Routine

Register on entry:   ES:dI - pointer to source string (StrDup
		     only).  CS:RET - Pointer to source string
		     (StrDupl only).

Register on return:  ES:DI - Points at the destination string
		     allocated on heap.  Carry=0 if operation
		     successful.  Carry=0 if insufficient
		     memory for new string.

Flags affected:      Carry flag

Example of usage:
		     StrDupl
		     db "String for StrDupl",0
		     jc  MallocError
		     mov word ptr Dest1, di
		     mov word ptr Dest1+2, es  ;create another
					       ;copy of this
					       ;string. Note
					       ;that es:di points
					       ;at Dest1 upon
					       ;entry to StrDup,
					       ;but it points at
					       ;the new string on
					       ;exit
		     StrDup
		     jc MallocError
		     mov word ptr Dest2, di
		     mov word ptr Dest2+2, es


Description:  StrDup and StrDupl duplicate strings.  You pass them
	      a pointer to the string (in es:di for strdup, via
	      the return address for strdupl) and they allocate
	      sufficient storage on the heap for a copy of this
	      string.  Then these two routines copy their source
	      strings to the newly allocated storage and return
	      a pointer to the new string in ES:DI.


Include:             stdlib.a or strings.a


Routine:  Strlen
----------------

Category:            String Handling Routine

Registers on entry:  ES:DI - pointer to source string.

Register on return:  CX - length of specified string.

Flags Affected:      None

Examples of Usage:
		     les   di, String
		     strlen
		     mov   sl, cx
		     printf
		     db   "Length of '%s' is %d\n",0
		     dd   String, sl


Description:  Strlen computes the length of the string whose address
	      appears in ES:DI.  It returns the number of characters
	      up to, but not including, the zero terminating byte.

Include:             stdlib.a or strings.a


Routine:  Strcat (m,l,ml)
-------------------------

Category:             String Handling Routine

Registers on Entry:   ES:DI- Pointer to first string
		      DX:SI- Pointer to second string (Strcat and Strcatm only)


Registers on Return:  ES:DI- Pointer to new string (Strcatm and Strcatml only)

Flags Affected:       Carry = 0 if no error
		      Carry = 1 if insufficient memory (Strcatm and Strcatml
							only)


Example of Usage:     les  DI, String1
		      mov  DX, seg String2
		      lea  SI, String2
		      Strcat                   ; String1 <- String1 + String2

		      les  DI, String1
		      Strcatl                  ; String1 <- String1 +
		      db  "Appended String",0  ;            "Appended String",0


		      les  DI, String1
		      mov  DX, seg String2
		      lea  SI, String2
		      Strcatm                  ; NewString <- String1 + String2
		      puts
		      free

		      les  DI, String1
		      Strcatml                 ; NewString <- String1 +
		      db  "Appended String",0  ;         "Appended String",0
		      puts
		      free


Description:  These routines concatenate two strings together.  They differ
	      mainly in the location of their source and destination operands.

	      Strcat concatenates the string pointed at by DX:SI to the end of
	      the string pointed at by ES:DI in memory.  Both strings must be
	      zero-terminated.  The buffer pointed at by ES:DI must be large
	      enough to hold the resulting string.  Strcat does NOT perform
	      bounds checking on the data.

	      ( continued on next page )







Routine:  Strcat (m,l,ml)   ( continued )
-----------------------------------------


	      Strcatm computes the length of the two strings pointed at by ES:DI
	      and DX:SI and attempts to allocate this much storage on the heap.
	      If it is not successful, Strcatm returns with the Carry flag set,
	      otherwise it copies the string pointed at by ES:DI to the heap,
	      concatenates the string DX:SI points at to the end of this string
	      on the heap, and returns with the Carry flag clear and ES:DI
	      pointing at the new (concatenated) string on the heap.

	      Strcatl and Strcatml work just like Strcat and Strcatm except you
	      supply the second string as a literal constant immediately AFTER
	      the call rather than pointing DX:SI at it (see examples above).


Include:             stdlib.a or strings.a


Routine:  Strchr
----------------

Category:            String Handling Routine

Register on entry:   ES:DI- Pointer to string.
			AL- Character to search for.

Register on return:  CX- Position (starting at zero)
			 where Strchr found the character.

Flags affected:      Carry=0 if Strchr found the character.
		     Carry=1 if the character was not present
			     in the string.

Example of usage:
		     les di, String
		     mov al, Char2Find
		     Strchr
		     jc  NotPresent
		     mov CharPosn, cx


Description:  Strchr locates the first occurrence of a character within a
	      string.  It searches through the zero-terminated string pointed
	      at by es:di for the character passed in AL. If it locates the
	      character, it returns the position of that character to the CX
	      register.  The first character in the string corresponds to the
	      location zero.  If the character is not in the string, Strchr
	      returns the carry flag set.  CX's value is undefined in that
	      case.  If Strchr locates the character in the string, it
	      returns with the carry clear.


Include:             stdlib.a or strings.a


Routine:  Strstr (l)
--------------------

Category:            String Handling Routine

Register on entry:   ES:DI - Pointer to string.
		     DX:SI - Pointer to substring(strstr).
		     CS:RET - Pointer to substring (strstrl).

Register on return:  CX - Position (starting at zero)
		     where Strstr/Strstrl found the
		     character.  Carry=0 if Strstr/
		     Strstrl found the character.
		     Carry=1 if the character was not
		     present in the string.

Flags affected:      Carry flag

Example of usage :
		     les di, MainString
		     lea si, Substring
		     mov dx, seg Substring
		     Strstr
		     jc NoMatch
		     mov i, cx
		     printf
		     db "Found the substring '%s' at location %i\n",0
		     dd Substring, i


Description:  Strstr searches for the position of a substring
	      within another string.  ES:DI points at the
	      string to search through, DX:SI points at the
	      substring.  Strstr returns the index into ES:DI's
	      string where DX:SI's string is found.  If the
	      string is found, Strstr returns with the carry
	      flag clear and CX contains the (zero based) index
	      into the string.  If Strstr cannot locate the
	      substring within the string ES:DI points at, it
	      returns the carry flag set.  Strstrl works just
	      like Strstr except it excepts the substring to
	      search for immediately after the call instruction
	      (rather than passing this address in DX:SI).


Include:              stdlib.a or strings.a


Routine:  Strcmp (l)
--------------------

Category:            String Handling Routine

Registers on entry:  ES:DI contains the address of the first string
		     DX:SI contains the address of the second string (strcmp)
		     CS:RET (contains the address of the substring (strcmpl)

Register on return:  CX (contains the position where the two strings differ)

Flags affected:      Carry flag and zero flag (string1 > string2 if C + Z = 0)
					 (string1 < string2 if C = 1)

Example of Usage:
		     les 	di, String1
		     mov 	dx, seg String2
		     lea 	si, String2
		     strcmp
		     ja		OverThere

		     les 	di, String1
		     strcmpl
		     db 	"Hello",0
		     jbe 	elsewhere



Description:  Strcmp compares the first strings pointed by ES:DI with
	      the second string pointed by DX:SI. The carry and zero flag
	      will contain the corresponding result. So unsigned branch
	      instructions such as JA or JB is recommended. If string1
	      equals string2, strcmp will return with CX containing the
	      offset of the zero byte in the two strings.

	      Strcmpl compares the first string pointed by ES:DI with
	      the substring pointed by CS:RET. The carry and zero flag
	      will contain the corresponding result. So unsigned branch
	      instructions such as JA or JB are recommended. If string1
	      equals to the substring, strcmp will return with CX
	      containing the offset of the zero byte in the two strings.

Include:             stdlib.a or strings.a


Routine:  Stricmp (l)
---------------------

Category:            String Handling Routine

Registers on entry:  ES:DI contains the address of the first string
		     DX:SI contains the address of the second string (stricmp)
		     CS:RET (contains the address of the substring (stricmpl)

Register on return:  CX (contains the position where the two strings differ)

Flags affected:      Carry flag and zero flag (string1 > string2 if C + Z = 0)
					 (string1 < string2 if C = 1)

Example of Usage:
		     les 	di, String1
		     mov 	dx, seg String2
		     lea 	si, String2
		     stricmp
		     ja		OverThere

		     les 	di, String1
		     stricmpl
		     db 	"Hello",0
		     jbe 	elsewhere



Description:	This routine is virtually identical to strcmp (l) except it
		ignores case when comparing the strings.

Include:             stdlib.a or strings.a


Routine:  Strupr (m)
--------------------

Category:            String Handling Routine
		     Conversion Routine

Register on entry:   ES:DI (contains the pointer to input string)

Register on return:  ES:DI (contains the pointer to input string
			   with characters converted to upper case)
			   Note: struprm allocates storage for a new
			   string on the heap and returns the pointer
			   to this routine in ES:DI.

Flags affected:      Carry = 1 if memory allocation error (Struprm only).

Example of Usage:
		     les 	di, lwrstr1
		     strupr
		     puts

		     mov        di, seg StrWLwr
		     mov	es, di
		     lea	di, StrWLwr
		     struprm
		     puts
		     free


Description:  Strupr converts the input string pointed by ES:DI to
	      upper case.  It will actually modify the string you pass
	      to it.

	      Struprm first makes a copy of the string on the heap and
	      then converts the characters in this new string to upper
	      case.  It returns a pointer to the new string in ES:DI.

Include:             stdlib.a or strings.a


Routine:  Strlwr (m)
--------------------

Category:            String Handling Routine
		     Conversion Routine

Register on entry:   ES:DI (contains the pointer to input string)

Register on return:  ES:DI (contains the pointer to input string
			   with characters converted to lower case).

Flags affected:      Carry = 1 if memory allocation error (strlwrm only)


Example of Usage:
		     les di, uprstr1
		     strlwr