String Manipulation

Reference Section

_fstr_cat
_fstr_cate
_fstr_center
_fstr_chr
_fstr_chri
_fstr_chrn
_fstr_chrni
_fstr_cmp
_fstr_cmpi
_fstr_cpy
_fstr_cpye
_fstr_cspn
_fstr_drive
_fstr_drvpath
_fstr_end
_fstr_ext
_fstr_fname
_fstr_fnamext
_fstr_left
_fstr_len
_fstr_lwr
_fstr_ncat
_fstr_ncate
_fstr_ncmp
_fstr_ncmpi
_fstr_ncpy
_fstr_nset
_fstr_path
_fstr_pbrk
_fstr_pbrkn
_fstr_rchr
_fstr_rchri
_fstr_rchrn
_fstr_rchrni
_fstr_rev
_fstr_right
_fstr_set
_fstr_skips
_fstr_skipw
_fstr_spn
_fstr_str
_fstr_stri
_fstr_tok
_fstr_toks
_fstr_trims
_fstr_trimw
_fstr_upr
_str_cat
_str_cate
_str_center
_str_chr
_str_chri
_str_chrn
_str_chrni
_str_cmp
_str_cmpi
_str_cpy
_str_cpye
_str_cspn
_str_drive
_str_drvpath
_str_end
_str_ext
_str_fname
_str_fnamext
_str_left
_str_len
_str_lwr
_str_ncat
_str_ncate
_str_ncmp
_str_ncmpi
_str_ncpy
_str_nset
_str_path
_str_pbrk
_str_pbrkn
_str_rchr
_str_rchri
_str_rchrn
_str_rchrni
_str_rev
_str_right
_str_set
_str_skips
_str_skipw
_str_spn
_str_str
_str_stri
_str_tok
_str_toks
_str_trims
_str_trimw
_str_upr

_fstr_cat


Descrip
Appends one string to the end of another.

Syntax
#include <sastring.h>
char far *_fstr_cat(char far *deststr, const char far *srcstr);

Notes
See _str_cat.

Source file _STFCAT.ASM ASM equiv STR_CAT

_fstr_cate


Descrip
Appends one string to the end of another, returning a pointer to the end of the modified string.

Syntax
#include <sastring.h>
char far *_fstr_cate(char far *deststr, const char far *srcstr);

Notes
See _str_cate.

Source file _STFCATE.ASM ASM equiv STR_CATE

_fstr_center


Descrip
Centers a string within a buffer.

Syntax
#include <sastring.h>
char far *_fstr_center(char chr, unsigned char width, char far *string);

Notes
See _str_center.

Source file _STFCNTR.ASM ASM equiv STR_CENTER

_fstr_chr


Descrip
Searches a string for the first occurrence of a character.

Syntax
#include <sastring.h>
char far *_fstr_chr(const char far *string, int chr);

Notes
See _str_chr.
Source file _STFCHR.ASM ASM equiv STR_CHR

_fstr_chri


Descrip
Searches a string for the first occurrence of a character, ignoring case.

Syntax
#include <sastring.h>
char far *_fstr_chri(const char far *string, int chr);

Notes
See _str_chri.

Source file _STFCHRI.ASM ASM equiv STR_CHRI

_fstr_chrn


Descrip
Searches a string for the first occurrence of a character which is NOT the given character.

Syntax
#include <sastring.h>
char far *_fstr_chrn(const char far *string, int chr);

Notes
See _str_chrn.

Source file _STFCHRN.ASM ASM equiv STR_CHRN

_fstr_chrni


Descrip
Searches a string for the first occurrence of a character which is NOT the given character, ignoring case.

Syntax
#include <sastring.h>
char far *_fstr_chrni(const char far *string, int chr);

Notes
See _str_chrni.

Source file _STFCHNI.ASM ASM equiv STR_CHRNI

_fstr_cmp


Descrip
Compares one string with another.

Syntax
#include <sastring.h>
int _fstr_cmp(const char far *string1, const char far *string2);

Notes
See _str_cmp.

Source file _STFCMP.ASM ASM equiv STR_CMP

_fstr_cmpi


Descrip
Compares one string with another, ignoring case.

Syntax
#include <sastring.h>
int _fstr_cmpi(const char far *string1, const char far *string2);

Notes
See _str_cmpi.

Source file _STFCMPI.ASM ASM equiv STR_CMPI

_fstr_cpy


Descrip
Copies a string to another location.

Syntax
#include <sastring.h>
char far *_fstr_cpy(char far *deststr, const char far *srcstr);

Notes
See _str_cpy.

Source file _STFCPY.ASM ASM equiv STR_CPY

_fstr_cpye


Descrip
Copies a string to another location and returns a pointer to the end of the copy.

Syntax
#include <sastring.h>
char far *_fstr_cpye(char far *deststr, const char far *srcstr);

Notes
See _str_cpye.

Source file _STFCPYE.ASM ASM equiv STR_CPYE

_fstr_cspn


Descrip
Determines the number of characters at the beginning of a string which do not match any character in a given character set.

Syntax
#include <sastring.h>
int _fstr_cspn(const char far *string, const char far *charset);

Notes
See _str_cspn.

Source file _STFCSPN.ASM ASM equiv STR_CSPN

_fstr_drive


Descrip
Locates a drive specifier substring in a pathname string.

Syntax
#include <sastring.h>
char far *_fstr_drive(const char far *pathname, int *drivelen);

Notes
See _str_drive.

Source file STFDRIV.ASM ASM equiv STR_DRIVE

_fstr_drvpath


Descrip
Locates a drive specifier and path substring in a pathname string.

Syntax
#include <sastring.h>
char far *_fstr_drvpath(const char far *pathname, int *pathlen);

Notes
See _str_drvpath.

Source file _STFDPTH.ASM ASM equiv STR_DRVPATH

_fstr_end


Descrip
Returns a pointer to the end of a string.

Syntax
#include <sastring.h>
char far *_fstr_end (const char far *string);

Notes
See _str_end.

Source file _STFEND.ASM ASM equiv STR_ENDDI

_fstr_ext


Descrip
Locates a filename extension substring in a string.

Syntax
#include <sastring.h>
char far *_fstr_ext(const char far *string, int *extlen);

Notes
See _str_ext.

Source file _STFEXT.ASM ASM equiv STR_EXT

_fstr_fname


Descrip
Locates a filename substring in a string.

Syntax
#include <sastring.h>
char far *_fstr_fname(const char far *pathname, int *fnamelen);

Notes
See _str_name.

Source file _STFFNAM.ASM ASM equiv STR_FNAME

_fstr_fnamext


Descrip
Locates a filename/extension substring in a string.

Syntax
#include <sastring.h>
char far *_fstr_fnamext(const char far *pathname, int *extlen);

Notes
See _str_namext.

Source file _STFFNEX.ASM ASM equiv STR_FNAMEXT

_fstr_left


Descrip
Left justifies a string within a buffer.

Syntax
#include <sastring.h>
char far *_fstr_left(char chr, unsigned char width, char far *string);

Notes
See _str_left.

Source file _STFLEFT.ASM ASM equiv STR_LEFT

_fstr_len


Descrip
Returns the length of a string.

Syntax
#include <sastring.h>
int _fstr_len (const char far *string);

Notes
See _str_len.

Source file _STFLEN.ASM ASM equiv STR_LENDI

_fstr_lwr


Descrip
Converts uppercase characters in a string to lowercase.

Syntax
#include <sastring.h>
char far *_fstr_lwr(char far *string);

Notes
See _str_lwr.

Source file _STFLWR.ASM ASM equiv STR_LWR

_fstr_ncat


Descrip
Appends a portion of one string to the end of another.

Syntax
#include <sastring.h>
char far *_fstr_ncat(char far *deststr, const char far *srcstr, unsigned int maxnum);

Notes
See _str_ncat.

Source file _STRNCAT.ASM ASM equiv STR_NCAT

_fstr_ncate


Descrip
Appends a portion of one string to the end of another, returning a pointer to the end of the modified string.

Syntax
#include <sastring.h>
char far *_fstr_ncate(char far *deststr, const char far *srcstr, unsigned int maxnum);

Notes
See _str_ncate.

Source file _STFNCTE.ASM ASM equiv STR_NCATE

_fstr_ncmp


Descrip
Compares a portion of one string to a portion of another.

Syntax
#include <sastring.h>
int _fstr_ncmp(const char far *string1, const char far *string2, unsigned int num);

Notes
See _str_ncmp.

Source file _STFNCMP.ASM ASM equiv STR_NCMP

_fstr_ncmpi


Descrip
Compares a portion of one string with a portion of another, ignoring case.

Syntax
#include <sastring.h>
int _fstr_ncmpi(const char far *string1, const char far *string2, unsigned int num);

Notes
See _str_ncmpi.

Source file _STFNCPI.ASM ASM equiv STR_NCMPI

_fstr_ncpy


Descrip
Copies a portion of a string to another location.

Syntax
#include <sastring.h>
char far *_fstr_ncpy(char far *deststr, const char far *srcstr, unsigned int num);

Notes
See _str_ncpy.

Source file _STFNCPY.ASM ASM equiv STR_NCPY

_fstr_nset


Descrip
Sets the first n characters of a string to a specified character.

Syntax
#include <sastring.h>
char far *_fstr_nset(char far *string, int chr, unsigned int *num);

Notes
See _str_nset.

Source file _STFNSET.ASM ASM equiv STR_NSET

_fstr_path


Descrip
Locates a path substring in a string.

Syntax
#include <sastring.h>
char far *_fstr_path(const char far *string, int *pathlen);

Notes
See _str_path.

Source file _STFPATH.ASM ASM equiv STR_PATH

_fstr_pbrk


Descrip
Searches a string for the first occurrence of any character which is in a set of characters.

Syntax
#include <sastring.h>
char far *_fstr_pbrk(const char far *string, const char *charset);

Notes
See _str_pbrk.

Source file _STFPBRK.ASM ASM equiv STR_PBRK

_fstr_pbrkn


Descrip
Searches a string for the first occurrence of any character which is not in a set of characters.

Syntax
#include <sastring.h>
char far *_fstr_pbrkn(const char far *string, const char far *charset);

Notes
See _str_pbrkn.

Source file _STFPBKN.ASM ASM equiv STR_PBRKN

_fstr_rchr


Descrip
Searches a string for the last occurrence of a character.

Syntax
#include <sastring.h>
char far *_fstr_rchr(const char far *string, int chr);

Notes
See _str_rchr.

Source file _STFRCH.ASM ASM equiv STR_RCHR

_fstr_rchri


Descrip
Searches a string for the last occurrence of a character, ignoring case.

Syntax
#include <sastring.h>
char far *_fstr_rchri(const char far *string, int chr);

Notes
See _str_rchri.

Source file _STFRCHI.ASM ASM equiv STR_RCHRI

_fstr_rchrn


Descrip
Searches a string for the last occurrence of a character which is not the given character.

Syntax
#include <sastring.h>
char far *_fstr_rchrn(const char far *string, int chr);

Notes
See _str_rchrn.

Source file _STFRCHN.ASM ASM equiv STR_RCHRN

_fstr_rchrni


Descrip
Searches a string for the last occurrence of a character which is not the given character, ignoring case.

Syntax
#include <sastring.h>
char far *_fstr_rchrni(const char far *string, int chr);

Notes
See _str_rchrni.

Source file _STFRCNI.ASM ASM equiv STR_RCHRNI

_fstr_rev


Descrip
Reverses the order of the characters in a string.

Syntax
#include <sastring.h>
char far *_fstr_rev(char far *string);

Notes
See _str_rev.

Source file _STFREV.ASM ASM equiv STR_REV

_fstr_right


Descrip
Right justifies a string within a buffer.

Syntax
#include <sastring.h>
char far *_fstr_right(char chr, unsigned char width, char far *string);

Notes
See _str_right.

Source file _STFRGHT.ASM ASM equiv STR_RIGHT

_fstr_set


Descrip
Sets all characters in a string to a specified character.

Syntax
#include <sastring.h>
char far *_fstr_set(char far *string, int chr);

Notes
See _str_set.

Source file _STFSET.ASM ASM equiv STR_SET

_fstr_skips


Descrip
Skips past space characters in a string.

Syntax
#include <sastring.h>
char far *_fstr_skips(const char far *string);

Notes
See _str_skips.

Source file _STFSKPS.ASM ASM equiv STR_SKIPS

_fstr_skipw


Descrip
Skips past whitespace characters in a string.

Syntax
#include <sastring.h>
char far *_fstr_skipw(const char far *string);

Notes
See _str_skipw.

Source file _STFSKPW.ASM ASM equiv STR_SKIPW

_fstr_spn


Descrip
Determines the number of characters at the beginning of a string which match any character in a given character set.

Syntax
#include <sastring.h>
int _fstr_spn(const char far *string, const char far *charset);

Notes
See _str_spn.

Source file _STFSPN.ASM ASM equiv STR_SPN

_fstr_str


Descrip
Searches a string for the first occurrence of a substring.

Syntax
#include <sastring.h>
char far *_fstr_str(const char far *string, const char far *substr);

Notes
See _str_str.

Source file _STFSTR.ASM ASM equiv STR_STR

_fstr_stri


Descrip
Searches a string for the first occurrence of a substring, ignoring case.

Syntax
#include <sastring.h>
char far *_fstr_stri(const char far *string, const char far *substr);

Notes
See _str_stri.

Source file _STFSTRI.ASM ASM equiv STR_STRI

_fstr_tok


Descrip
Initializes a string for subsequent tokenization by _str_tok.

Syntax
#include <sastring.h>
char far *_fstr_tok(const char far *charset);

Notes
See _str_tok.

Source file _STFTOK.ASM ASM equiv STR_TOK

_fstr_toks


Descrip
Initializes a string for subsequent tokenization by _str_tok.

Syntax
#include <sastring.h>
void _fstr_toks(const char far *string);

Notes
See _str_toks.

Source file _STFTOK.ASM ASM equiv STR_TOKS

_fstr_trims


Descrip
Removes space characters from the end of a string.

Syntax
#include <sastring.h>
char far *_fstr_trims(char far *string);

Notes
See _str_trims.

Source file _STFTRMS.ASM ASM equiv STR_TRIMS

_fstr_trimw


Descrip
Removes whitespace characters from the end of a string.

Syntax
#include <sastring.h>
char far *_fstr_trimw(char far *string);

Notes
See _str_trimw.

Source file _STFTRMW.ASM ASM equiv STR_TRIMW

_fstr_upr


Descrip
Converts lowercase letters in a string to uppercase.

Syntax
#include <sastring.h>
char far *_fstr_upr(char far *string);

Notes
See _str_upr.

Source file _STFUPR.ASM ASM equiv STR_UPR

_str_cat


Descrip
Appends one string to the end of another.

Syntax
#include <sastring.h>
char *_str_cat(char far *deststr, const char *srcstr);

Returns
A pointer to deststr.
deststr copy of deststr with srcstr appended to the end

Notes
This function copies srcstr to the end of deststr. The modified deststr is NULL terminated. The original NULL of deststr is overwritten with the first character of srcstr. The space allocated for deststr must be sufficient to hold the modified deststr, or data following deststr will be overwritten.

srcstr and deststr may be the same string.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   _str_cat (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea di,string1
	   lea si,string2
	   str_cat ();
	   ...
	}

Source file _STRCAT.ASM ASM equiv STR_CAT
See also
_fstr_cat, _str_cat, _str_ncat

_str_cate


Descrip
Appends one string to the end of another, returning the address of the end of the modified string.

Syntax
#include <sastring.h>
char *_str_cate(char far *deststr, const char *srcstr);

Returns
A pointer to the end of deststr.
deststr copy of deststr with srcstr appended to the end
Notes
This function copies srcstr to the end of deststr. The modified deststr is NULL terminated. A pointer is returned to the terminating NULL of deststr. The original NULL of deststr is overwritten with the first character of srcstr. The space allocated for deststr must be sufficient to hold the modified deststr or data following deststr will be overwritten. A subsequent call to _str_cpy or _str_cpye will append data to the result more rapidly than is possible with _str_cat.

srcstr and deststr may be the same string.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   _str_cate (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string1
	   lea si,string2
	   str_cate ();/* DI -> end of string1 */
	   ...
	}

Source file _STRCATE.ASM ASM equiv STR_CATE
See also
_fstr_cat, _str_cat, _str_ncat

_str_center


Descrip
Centers a string within a buffer.

Syntax
#include <sastring.h>
char *_str_center(char *string, char pad, unsigned char width);

Returns
A pointer to string.
string a center-aligned copy of string

Notes
This function pads string on the left and right with an equal number of pad characters. Characters are padded only until the total number of characters equals width. If an odd number of pad characters is required, the additional character is padded on the right. The resulting string is NULL terminated.

C/C++ Example
	#include <sastring.h>
	{
	   char string[11];
	   ...
	   _put_str(_str_center("Hello!", ' ', 10)); /* "  Hello!  "*/
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[11] = "hello!";
	...
	lea si,string/* SI = offset of string */
	mov cl,10	 /* CL = width */
	mov al," "	 /* AL = pad character */
	str_center();	 /* center align string */
	put_str();	 /* "  Hello!  " */
	...
	}

Source file _STRCNTR.ASM ASM equiv STR_CENTER
See also
cput_strci, _fstr_center, _sput_script, _str_left, _str_right

_str_chr


Descrip
Searches a string for the first occurrence of a character.

Syntax
#include <sastring.h>
char *_str_chr(const char *string, int chr);

Returns
A pointer to the first occurrence of chr in string.

NULL if string contains no occurrences of chr.

Notes
This function scans string in the forward direction, searching for chr. The search stops at the first occurrence of chr or at the terminating NULL, whichever comes first. A pointer to the first occurrence of chr in string is returned. NULL is returned if string contains no occurrences of chr.

This function may be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_chr (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	str_chr ();	 /* SI = offset of first 
		   	    occurrence of look */
	 jncstr_chr_010/* if look was found */
	...    	 /* if look wasn't found */
	jmp short str_chr_020

	str_chr_010:
	...    	 /* if look was found */
	str_chr_020:
	...
	}

Source file _STRCHR.ASM ASM equiv STR_CHR
See also
_fstr_chr, _mem_chr, _str_chr, _str_chr, _str_chr, _str_rchr

_str_chri


Descrip
Searches a string for the first occurrence of a character, ignoring case.

Syntax
#include <sastring.h>
char *_str_chri(const char *string, int chr);

Returns
A pointer to the first occurrence of chr in string.

NULL if string contains no occurrences of chr.

Notes
This function scans string in the forward direction, searching for chr. The search stops at the first occurrence of chr or at the terminating NULL, whichever comes first. The case of ASCII characters is ignored. A pointer to the first occurrence of chr in string is returned. NULL is returned if string contains no occurrences of chr.

This function may be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_chri (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_chri ();/* DS:SI -> 1st occurrence of look */
	    jncstr_chri_010    /* if look was found */
	   ... 	 	    /* if look wasn't found */
	   jmp short str_chri_020

	str_chri_010:
	...    	 /* if look was found */
	str_chri_020:
	...
	}

Source file _STRCHRI.ASM ASM equiv STR_CHRI
See also
_fstr_chr, _str_chr, _str_rchr

_str_chrn


Descrip
Searches a string for the first occurrence of a character which is NOT the given character.

Syntax
#include <sastring.h>
char *_str_chrn(const char *string, int chr);

Returns
A pointer to the first character in string not matching chr.

NULL if all characters in string match chr.

Notes
This function scans string for the first occurrence of a character which is different from chr. A pointer to that character is returned. NULL is returned if all characters in string match the specified character.

A NULL string always results in a NULL return, even if chr is not NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_chrn (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_chrn ();	/* SI = offset of first 
	   	  	 	   non-occurrence of look */
	    jncstr_chrn_010/* if no chars matched look */
	   ... 	 	/* if all chars matched look */
	   jmp short str_chrn_020

	str_chrn_010:
	   ... 	 	/* if no chars matched look */
	str_chrn_020:
	   ...
	}

Source file _STRCHRN.ASM ASM equiv STR_CHRN
See also
_fstr_chr, _str_chr, _str_chr, _str_chr, _str_rchr

_str_chrni


Descrip
Searches a string for the first occurrence of a character which is NOT the given character, ignoring case.

Syntax
#include <sastring.h>
char *_str_chrni(const char *string, int chr);

Returns
A pointer to the first character in string not matching chr.

NULL if string contains only occurrences of chr.

Notes
This function returns a pointer to the first occurrence of a character which is different from chr, ignoring the case of ASCII characters. A pointer to that character is returned. NULL is returned if every character in string matches the specified character (ignoring case).

A NULL string always results in a NULL return, even if chr is not NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_chrni (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_chrni ();	/* SI = offset of first 
	   	  	 	   non-occurrence of look */
	    jncstr_chrni_010/* if no chars matched look */
	   ... 	 	/* if all chars matched look */
	   jmp short str_chrni_020

	str_chrni_010: 
	   ... 	 	/* no matching chars found */
	str_chrni_020:
	   ...
	}

Source file _STRCHNI.ASM ASM equiv STR_CHRNI
See also
_fstr_chr, _str_chr, _str_rchr

_str_cmp


Descrip
Compares two strings.

Syntax
#include <sastring.h>
int _str_cmp(const char *string1, const char far *string2);

Returns
1 if string1 is greater than string2.

0 if string1 is equal to string2.

-1 if string1 is less than string2.

Notes
This function compares each character of string1 to the corresponding character of string2. The comparison starts with the first character of each string and continues until corresponding characters differ or until the end of one of the strings is encountered. The return values (1, 0 ,-1) indicate whether string1 is greater than, equal to, or less than string2. If one string is longer than the other, but the strings are otherwise identical, the longer string is considered to be greater than the shorter string.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   switch (_str_cmp (string1, string2))
	   {
	      case 1:	 	/* string1 > string2 */
	         break;
	      case 0:	 	/* string1 = string2 */
	         break;
	      case -1:	 	/* string1 < string2 */
	         break;
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	<char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,string1
	   lea di,string2
	   str_cmp ();
	    je str_cmp_010/* if string1 = string2 */
	    jb str_cmp_020/* if string1 < string2 */
	   ... 	 	/* if string1 > string2 */
	   jmp short str_cmp_030

	str_cmp_010:
	   ... 	 	/* string1 = string2 */
	   jmp short str_cmp_030
	str_cmp_020:
	   ... 	 	/* string1 < string2 */
	str_cmp_030:
	   ...
	}

Source file _STRCMP.ASM ASM equiv STR_CMP
See also
_buf_cmp, _fstr_cmp, _mem_cmp, _str_cmp, _str_ncmp

_str_cmpi


Descrip
Compares two strings, ignoring case.

Syntax
#include <sastring.h>
int _str_cmpi(const char *string1, const char far *string2);

Returns
1 if string1 is greater than string2.

0 if string1 is equal to string2.

-1 if string1 is less than string2.

Notes
This function compares each character of string1 to the corresponding character of string2, ignoring the case of ASCII characters. The comparison starts with the first character of each string and continues until corresponding characters differ or until the end of one of the strings is encountered. The return value (1, 0, or -1) indicates whether string1 is greater than, equal to, or less than string2. If one string is longer than the other, but the strings are otherwise identical, the longer string is considered to be greater than the shorter string.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   switch (_str_cmpi (string1, string2))
	   {
	      case 1:/* string1 > string2, case insensitive */
	         break;
	      case 0:/* string1 = string2, case insensitive */
	         break;
	      case -1:/* string1 < string2, case insensitive */
	         break;
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	lea si,string1
	lea di,string2
	str_cmpi ();
	 je str_cmpi_010/* if string1 = string2 */
	 jb str_cmpi_020/* if string1 < string2 */
	...    	 /* if string1 > string2 */
	jmp short str_cmpi_030

	str_cmpi_010:
	...    	 /* string1 = string2 */
	jmp short str_cmpi_030

	str_cmpi_020:
	...    	 /* string1 < string2 */
	str_cmpi_030:
	...
	}

Source file _STRCMPI.ASM ASM equiv STR_CMPI
See also
_buf_cmp, _fstr_cmp, _mem_cmp, _str_cmp, _str_ncmp

_str_cpy


Descrip
Copies a string to another location.

Syntax
#include <sastring.h>
char *_str_cpy(char far *deststr, const char *srcstr);

Returns
A pointer to deststr.
deststr copy of srcstr

Notes
This function copies srcstr into deststr. The copy is NULL terminated.

srcstr and deststr must not overlap if deststr is higher in memory than srcstr.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   _str_cpy (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea di,string1/* ES:DI -> string1 */
	   lea si,string2/* DS:SI -> string2 */
	   str_cpy ();	/* copy string2 into string1 */
	   ...
	}

Source file _STRCPY.ASM ASM equiv STR_CPY
See also
_buf_cpy, _fstr_cpy, _mem_cmp, _mem_mov, _str_cpy, _str_ncpy

_str_cpye


Descrip
Copies a string to another location and returns the address of the end of the copy.

Syntax
#include <sastring.h>
char *_str_cpye(char far *deststr, const char *srcstr);

Returns
A pointer to the end of deststr.
deststr a copy of srcstr

Notes
This function copies srcstr into deststr and returns a pointer to the terminating NULL of deststr. A subsequent call to _str_cpy or _str_cpye will append data to the result more rapidly than would be possible if _str_cpy were used instead of this function.

srcstr and deststr must not overlap if deststr is higher in memory than srcstr.

C/C++ Example
	{
	   char string1[10], string2[10], *pointer;
	   ...
	   pointer = _str_cpye (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string1
	   lea si,string2
	   str_cpye ();/* ES:DI -> end of string1 */
	   ...
	}

Source file _STRCPYE.ASM ASM equiv STR_CPYE
See also
_fstr_cpy, _mem_cpy, _str_cpy

_str_cspn


Descrip
Determines the number of characters at the beginning of a string which do not match any character in a given character set.

Syntax
#include <sastring.h>
int _str_cspn(const char *string, const char far *charset);

Returns
The number of consecutive characters at the beginning of string that are not in charset.

Notes
This function compares each character in string to all of the characters in charset. The comparison starts with the first character of string and continues until one of the characters in string matches one of the characters in charset.The number of consecutive unmatched characters at the beginning of string is returned.

charset must be a NULL-terminated string containing all characters in the character set.

The terminating NULL of string is never included in the count; therefore, a NULL string results in a count of zero.

C/C++ Example
	{
	   char string1[10], string2[10];
	   int num;
	   ...
	   num = _str_cspn (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea di,string2
	   lea si,string1
	   str_cspn ();	/* CX=number of matching chars */
	   ...
	}

Source file _STRCSPN.ASM ASM equiv STR_CSPN
See also
_fstr_cspn, _mem_cspn, _str_spn

_str_drive


Descrip
Locates a drive specifier substring in a pathname string.

Syntax
#include <sastring.h>
char *_str_drive(const char *pathname, int *drivelen);

Returns
A pointer to the drive substring in pathname.
drivelen the length of the drive substring

Notes
This function returns a pointer to the start of the drive specifier substring in pathname. drivelen indicates the length of the substring. If there is no drive specifier substring, the returned pointer indicates where the substring would be if it were present and drivelen is set to 0.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_drive (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	...
	lea si,string
	str_drive ();/* DS:SI -> drive specifier,
		      CX=length */
	...
	}

Source file _STRDRIV.ASM ASM equiv STR_DRIVE
See also
_fstr_drive, _str_drvpath, _str_ext, _str_fname, _str_path

_str_drvpath


Descrip
Locates a drive specifier and path substring in a pathname string.

Syntax
#include <sastring.h>
char *_str_drvpath(const char *pathname, int *pathlen);

Returns
A pointer to the drive/path substring.
pathlen the length of the drive/path substring

Notes
This function returns a pointer to the substring consisting of the drive specifier and path in pathname. pathlen indicates the length of the substring. If there is no drive specifier and/or path substring, the returned pointer indicates where the substring would be if it were present and pathlen is set to 0.

This function requires that the path portion of pathname be terminated with a backslash character ("\"). This makes it possible to differentiate between path-only and path-filename strings. The _term_path function is provided to force path-only strings to conform to this internal Spontaneous Assembly format. _fix_path is provided to convert strings from this format into DOS-compatible format.

See the technical notes for more information about internal and DOS path string formats.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_drvpath (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_drvpath ();/* DS:SI -> drive/path specifier,
	   	  	   CX=length */
	   ...
	}

Source file _STRDPTH.ASM ASM equiv STR_DRVPATH
See also
_fstr_drvpath, _str_drive, _str_ext, _str_fname, _str_path

_str_end


Descrip
Returns a pointer to the end of a string.

Syntax
#include <sastring.h>
char *_str_end(const char *string);

Returns
A pointer to the end of string.

Notes
This function returns a pointer to the terminating NULL in string.

C/C++ Example
	{
	   char string[10], *pointer;
	   ...
	   pointer = _str_end (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string
	   str_enddi ();/* ES:DI -> end of string */
	   ...
	}

Source file _STREND.ASM ASM equiv STR_ENDDI
See also
_fstr_end

_str_ext


Descrip
Locates a file name extension substring in a string.

Syntax
#include <sastring.h>
char *_str_ext(const char *string, int *extlen);

Returns
A pointer to the extension substring.
extlen the length of the extension substring

Notes
This function returns a pointer to the start of the file extension substring in string. extlen indicates the length of the substring. The first extension character is always ".". If there is no file extension substring, the returned pointer indicates where the substring would be if it were present and extlen is set to 0.

This function requires that the path portion of string be terminated with a backslash character ("\"). This makes it possible to differentiate between path-only and path-filename strings. The _term_path function is provided to force path-only strings to conform to this internal format. _fix_path is provided to convert strings from this format into DOS-compatible format.

See the technical notes for more information about internal and DOS path string formats.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_ext (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_ext ();/* SI = offset of extension in string,
	   	  	    CX=length */
	   ...
	}

Source file _STREXT.ASM ASM equiv STR_EXT
See also
_fstr_ext, _str_drive, _str_fname, _str_fname, _str_path

_str_fname


Descrip
Locates a filename substring in a string.

Syntax
#include <sastring.h>
char *_str_fname(const char *pathname, int *fnamelen);

Returns
A pointer to the filename substring.
fnamelen the length of the filename substring

Notes
This function returns a pointer to the start of the filename substring in pathname. fnamelen indicates the length of the substring. The filename extension is NOT included in the substring. If there is no filename substring, the returned pointer indicates where the substring would be if it were present and fnamelen is set to 0.

This function requires that the path portion of pathname be terminated with a backslash character ("\"). This makes it possible to differentiate between path-only and path-filename strings. The _term_path function is provided to force path-only strings to conform to this internal format. _fix_path is provided to convert strings from this format into DOS-compatible format.

See the technical notes for more information about internal and DOS path string formats.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_fname (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	      ...
	lea si,string
	str_fname ();/* SI = offset of filename portion of
		      string, CX=length */
	...
	}

Source file _STRFNAM.ASM ASM equiv STR_FNAME
See also
_fstr_fname, _str_drive, _str_ext, _str_fname, _str_path

_str_fnamext


Descrip
Locates a filename/extension substring in a string.

Syntax
#include <sastring.h>
char *_str_fnamext(const char *pathname, int *extlen);

Returns
A pointer to the file extension substring.
extlen the length of the filename/extension substring

Notes
This function returns a pointer to the start of the file extension substring in pathname. extlen indicates the length of the substring. If there is no file extension substring, the returned pointer indicates where the substring would be if it were present and extlen is set to 0.

This function requires that the path portion of pathname be terminated with a backslash character ("\"). This makes it possible to differentiate between path-only and path-filename strings. The _term_path function is provided to force path-only strings to conform to this internal format. _fix_path is provided to convert strings from this format into DOS-compatible format.

See the technical notes for more information about internal and DOS path string formats.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_fnamext (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_fnamext ();/* SI = offset of filename.ext portion 
	   	  	    of string, CX=length */
	   ...
	}

Source file _STRFNEX.ASM ASM equiv STR_FNAMEXT
See also
_fstr_fname, _str_drive, _str_ext, _str_fname, _str_path

_str_left


Descrip
Left justifies a string within a buffer.

Syntax
#include <sastring.h>
char *_str_left(char *string, char pad, unsigned char width);

Returns
A pointer to string.
string a left-aligned copy of string

Notes
The function pads string on the right with the specified pad character until string is left justified within width. Characters are padded only until the total number of characters equals width. The resulting string is NULL terminated.

C/C++ Example
	#include <sastring.h>
	{
	   char string[11];
	   ...
	   _put_str(_str_left("Hello!", ' ', 10)); /* "Hello!    " */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[11] = "hello!";
	   ...
	   lea si,string/* SI = offset of string */
	   mov cl,10	/* CL = width */
	   mov al," "	/* AL = pad character */
	   str_left();	/* left align string */
	   put_str();	/* "Hello!    " */
	   ...
	}

Source file _STRLEFT.ASM ASM equiv STR_LEFT
See also
_fstr_left, _sput_script, _str_center, _str_right

_str_len


Descrip
Returns the length of a string.

Syntax
#include <sastring.h>
int _str_len(const char *string);

Returns
The length of string.

Notes
This function returns the number of characters in string (not including the terminating NULL character).

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   length = _str_len (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[] = "Length of this string";
	...
	pushss
	pop es /* ES = SS */
	lea di,string
	str_lendi ();/* CX=string length */
	...
	}

Source file _STRLEN.ASM ASM equiv STR_LENDI
See also
_fstr_len

_str_lwr


Descrip
Converts uppercase characters in a string to lowercase.

Syntax
#include <sastring.h>
char *_str_lwr(char *string);

Returns
A pointer to string.
string copy of string with ASCII characters converted to lowercase

Notes
This function converts all ASCII uppercase letters (A-Z) in string to lowercase letters (a-z). No other characters are modified. A pointer to string is returned.

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_lwr (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_lwr ();
	   ...
	}

Source file _STRLWR.ASM ASM equiv STR_LWR
See also
_fstr_lwr, _mem_lwr, _str_upr

_str_ncat


Descrip
Appends a portion of one string to the end of another.

Syntax
#include <sastring.h>
char *_str_ncat(char far *deststr, const char *srcstr, unsigned int maxnum);
Returns
A pointer to deststr.
deststr a copy of deststr with up to maxnum characters from srcstr appended

Notes
This function copies up to maxnum characters from srcstr to the end of deststr. The modified deststr is NULL terminated. A pointer to deststr is returned.

The original NULL at the end of deststr is overwritten with the first character of srcstr. The space allocated for deststr must be sufficient to hold the modified deststr or data following deststr will be overwritten.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   _str_ncat (string1, string2, 5);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string1
	   lea si,string2
	   mov cx,5
	   str_ncat ();/* CX=number of characters copied */
	   ...
	}

Source file _STRNCAT.ASM ASM equiv STR_NCAT
See also
_fstr_ncat, _str_cat, _str_ncat

_str_ncate


Descrip
Appends a portion of one string to the end of another, returning a pointer to the end of the modified string.

Syntax
#include <sastring.h>
char *_str_ncate(char far *deststr, const char *srcstr, unsigned int maxnum);

Returns
A pointer to the end of deststr.
deststr a copy of deststr with up to maxnum characters from srcstr appended

Notes
This function copies up to maxnum characters from srcstr to the end of deststr. The modified deststr is NULL terminated. A pointer to this NULL character is returned. A subsequent call to _str_cpy or _str_cpye will append data to the result more rapidly than would have been possible if _str_ncat had been called instead of this function.

The original NULL at the end of deststr is overwritten with the first character of srcstr. The space allocated for deststr must be sufficient to hold the modified deststr, or data following deststr will be overwritten.

C/C++ Example
	{
	   char string1[10], string2[10], *pointer;
	   ...
	   pointer = _str_ncate (string1, string2, 5);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string1
	   lea si,string2
	   mov cx,5
	   str_ncate ();/* CX=# of chars copied, 
	   	  	    DI -> end of string1 */
	   	  ...
	}

Source file _STRNCTE.ASM ASM equiv STR_NCATE
See also
_fstr_cat, _str_cat, _str_ncat

_str_ncmp


Descrip
Compares a portion of one string to a portion of another.

Syntax
#include <sastring.h>
int _str_ncmp(const char *string1, const char far *string2, unsigned int num);

Returns
1 if string1 is greater than string2.

0 if string1 is equal to string2.

-1 if string1 is less than string2.

Notes
This function compares each character of string1 to the corresponding character of string2. The comparison starts with the first character of each string and continues until corresponding characters differ, until the end of one of the strings is encountered, or until num characters have been compared, whichever comes first. The return value (1, 0, or -1) indicates whether string1 is greater than, equal to, or less than string2.

WARNING! If num is zero, the return condition is undefined.

C/C++ Example
	{
	   char string1[10], string2[10];
	   int num;
	   ...
	   switch (_str_ncmp (string1, string2, num))
	   {
	      case 1:/* first num chars of string1 > string2 */
	         break;
	      case 0:/* first num chars of string1 = string2 */
	         break;
	      case -1:/* first num chars of string1 < string2 */
	         break;
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	...
	pushss
	pop es 	 /* ES = SS */
	lea si,string1
	lea di,string2
	mov cx,5
	str_ncmp ();
	 je str_ncmp_010/* if first num chars of 
		   	    string1 = string2 */
	 jb str_ncmp_020/* if first num chars of 
		   	    string1 < string2 */
	...    	 /* if first num chars of 
		   	    string1 > string2 */
	jmp short str_ncmp_030

	str_ncmp_010:

	jmp short str_ncmp_030
	str_ncmp_020:
	...    	 /* first num chars of 
		   	    string1 < string2 */
	str_ncmp_030:
	...
	}

Source file _STRNCMP.ASM ASM equiv STR_NCMP
See also
_fstr_ncmp, _str_cmp, _str_ncmp

_str_ncmpi


Descrip
Compares a portion of one string to a portion of another, ignoring case.

Syntax
#include <sastring.h>
int _str_ncmpi(const char *string1, const char far *string2, unsigned int num);
Returns
1 if string1 is greater than string2.

0 if string1 is equal to string2.

-1 if string1 is less than string2.

Notes
This function compares each character of string1 to the corresponding character of string2, ignoring the case of ASCII characters. The comparison starts with the first character of each string and continues until corresponding characters differ, until the end of one of the strings is encountered, or until num characters have been compared, whichever comes first. The return value (1, 0, or -1) indicates whether string1 is greater than, equal to, or less than string2.

WARNING! If num is zero, the return condition is undefined.

C/C++ Example
	{
	   char string1[10], string2[10];
	   int num;
	   ...
	   switch (_str_ncmpi (string1, string2, num))
	   {
	      case 1:/* first num chars of string1 > string2 */
	         break;
	      case 0:/* first num chars of string1 = string2 */
	         break;
	      case -1:/* first num chars of string1 < string2 */
	         break;
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   int num;
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,string1
	   lea di,string2
	   str_ncmpi ();
	    je str_ncmpi_010/* string1 = string2 */
	    jb str_ncmpi_020/* string1 < string2 */
	   ... 	 	/* string1 > string2 */
	   jmp short str_ncmpi_030

	str_ncmpi_010:
	   ... /* string1 = string2, case insensitive */
	   jmp short str_ncmpi_030

	str_ncmpi_020: 
	   ... /* string1 = string2, case insensitive */
	str_ncmpi_030:
	   ...
	}

Source file _STRNCPI.ASM ASM equiv STR_NCMPI
See also
_fstr_ncmp, _str_cmp, _str_ncmp

_str_ncpy


Descrip
Copies a portion of a string to another location.

Syntax
#include <sastring.h>
char *_str_ncpy(char far *deststr, const char *srcstr, unsigned int num);

Returns
A pointer to deststr.
deststr contains up to num characters copied from srcstr

Notes
This function copies characters from srcstr into deststr. Copying starts with the first character of srcstr and continues until all characters in srcstr have been copied or until num characters have been copied, whichever comes first. The copy is always NULL terminated. A pointer to deststr is returned.

srcstr and deststr must not overlap. If num is zero, a NULL string is copied into deststr.

C/C++ Example
	{
	   char string1[10], string2[10];
	   ...
	   _str_ncpy (string1, string2, 5);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea di,string1
	   lea si,string2
	   mov cx,5
	   str_ncpy ();/* CX=number of characters copied */
	   ...
	}

Source file _STRNCPY.ASM ASM equiv STR_NCPY
See also
_fstr_ncpy, _str_cpy, _str_cpy

_str_nset


Descrip
Sets the first n characters of a string to a specified character.

Syntax
#include <sastring.h>
char *_str_nset(char *string, int chr, unsigned int num);
Returns
A pointer to string.
string a copy of string with up to num characters replaced with chr

Notes
This function replaces consecutive characters in string with chr. The function starts with the first character of string and continues until the terminating NULL is encountered or until num characters have been replaced, whichever comes first. The terminating NULL is never replaced.

If num is zero, no change is made to string.

C/C++ Example
	{
	   char string1[10];
	   ...
	   _str_nset (string1, ' ', 9);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], init;
	   ...
	   lea si,string1
	   mov al,' '
	   mov cx,5
	   str_nset ();/* CX=number of characters set to AL */
	   ...
	}

Source file _STRNSET.ASM ASM equiv STR_NSET
See also
_fstr_nset, _str_set

_str_path


Descrip
Locates the path substring in a string.

Syntax
#include <sastring.h>
char *_str_path(const char *string, int *pathlen);

Returns
A pointer to the path substring in string.
pathlen the length of the path substring

Notes
This function returns a pointer to the start of the path substring in string. pathlen contains the length of the substring. If there is no path substring, the returned pointer indicates where the substring would be if it were present and pathlen is set to 0.

This function requires that the path portion of string be terminated with a backslash character ("\"). This makes it possible to differentiate between path-only and path-filename strings. The _term_path function is provided to force path-only strings to conform to this internal format. _fix_path is provided to convert strings from this format into DOS-compatible format.

See the technical notes for more information about internal and DOS path string formats.

C/C++ Example
	{
	   char string[10];
	   int length;
	   ...
	   _str_path (string, &length);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	...
	lea si,string
	str_path ();/* SI = offset of path specifier 
		      in string, CX=length */
	...
	}

Source file _STRPATH.ASM ASM equiv STR_PATH
See also
_fstr_path, _str_drive, _str_drvpath, _str_ext, _str_fname

_str_pbrk


Descrip
Searches a string for the first occurrence of any character which is in a set of characters.

Syntax
#include <sastring.h>
char *_str_pbrk(const char *string, const char far *charset);

Returns
A pointer to the first character in string that is also in charset.

NULL if string does not contain a character from charset.

Notes
This function searches a string for the first occurrence of any character from charset. The search begins with the first character of string and continues until there is a match, or until the terminating NULL of string is encountered. A pointer is returned to the first character in string that matches one of the characters in charset. NULL is returned if no matching character is found.

charset must be a NULL-terminated string containing all characters in the character set.

C/C++ Example
	{
	   char string1[10], string2[10], *pointer;
	   ...
	   pointer = _str_pbrk (string1, string2);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	...
	pushss
	pop es 	 /* ES = SS */
	lea si,string1
	lea di,string2
	str_pbrk ();	 /* SI = offset of first char in 
		   	    string1 that matches a char 
		   	    from string2 */
	 jc str_pbrk_010/* if no match found */
	...
	str_pbrk_010:
	...
	}

Source file _STRPBRK.ASM ASM equiv STR_PBRK
See also
_fstr_pbrk, _mem_pbrk, _str_pbrk

_str_pbrkn


Descrip
Searches a string for the first occurrence of any character which is not in a set of characters.

Syntax
#include <sastring.h>
char *_str_pbrkn(const char *string, const char far *charset);

Returns
A pointer to the first occurrence of a character in string that does not exist in charset.

NULL if string only contains characters from charset.

Notes
This function searches string for the first occurrence of any character which is not in charset. The search starts with the first character in string and continues until a character is found in string which is not found in charset, or until the terminating NULL of string is encountered. A pointer is returned to the first character in string that is not found in charset. NULL is returned if all characters in string exist in charset.

charset must be a NULL-terminated string containing all characters in the character set.

C/C++ Example
	{
	   char string1[10], string2[10], *pointer;
	   ...
	   pointer = _str_pbrkn (string1, string2);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	...
	pushss
	pop es 	 /* ES = SS */
	lea si,string1
	lea di,string2
	str_pbrkn ();	 /* SI = offset of first char in
		   	    string1 that doesn't matches
		   	    a char from string2 */
	 jc str_pbrkn_010/* string1 == string2 */
	...
	str_pbrkn_010:
	...
	}

Source file _STRPBKN.ASM ASM equiv STR_PBRKN
See also
_fstr_pbrk, _mem_pbrk, _str_pbrk

_str_rchr


Descrip
Searches a string for the last occurrence of a character.

Syntax
#include <sastring.h>
char *_str_rchr(const char *string, int chr);

Returns
A pointer to the last occurrence of chr in string.

NULL if there are no occurrences of chr in string.

Notes
This function searches string for the last occurrence of chr. The search starts with the last character in string. The search stops when chr is found or when all characters of string have been checked, whichever comes first. A pointer to the last occurrence of chr is returned. NULL is returned if no matching characters are found.

This function cannot be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_rchr (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_rchr ();	/* SI = offset of last occurrence
		   	    of look */
	 jc str_rchr_010/* if no match found */
	...
	str_rchr_010:
	...
	}

Source file _STRRCH.ASM ASM equiv STR_RCHR
See also
_fstr_rchr, _str_chr, _str_rchr, _str_rchr

_str_rchri


Descrip
Searches a string for the last occurrence of a character, ignoring case.

Syntax
#include <sastring.h>
char *_str_rchri(const char *string, int chr);

Returns
A pointer to the last character in string which matches chr (ignoring case).

NULL if no matches were found.

Notes
This function searches string for the last occurrence of chr. The case of ASCII characters is ignored. The search starts with the last character in string and continues until a match is found or until all characters in string have been checked, whichever comes first. A pointer to the last occurrence of chr (ignoring case) is returned. NULL is returned if no matches are found.

This function cannot be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_rchri(string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_rchri();	/* SI = offset of last occurrence
	   	  	 	   of look */
	    jc str_rchr_010/* if no match found */
	   ...
	str_rchr_010:
	   ...
	}

Source file _STRRCHI.ASM ASM equiv STR_RCHRI
See also
_fstr_rchr, _str_chr, _str_rchr

_str_rchrn


Descrip
Searches a string for the last occurrence of a character which is not the given character.

Syntax
#include <sastring.h>
char *_str_rchrn(const char *string, int chr);

Returns
A pointer to the last non-occurrence of chr in string.

NULL if all characters in string match chr.

Notes
This function searches string for the last occurrence of a character which does not match chr. The search starts with the last character and continues until a character is found in string which does not match chr or until all characters of string have been checked, whichever comes first. A pointer to the last non-
matching character is returned. NULL is returned if all characters in string match the given character.

NULL is returned if string is a NULL string. This function cannot be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_rchrn (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_rchrn ();	/* SI = offset of last 
	   	  	 	   non-occurrence of look */
	    jc str_rchrn_010/* all chars match look */
	   ...
	str_rchrn_010:
	   ...
	}

Source file _STRRCHN.ASM ASM equiv STR_RCHRN
See also
_fstr_rchr, _str_chr, _str_rchr, _str_rchr

_str_rchrni


Descrip
Searches a string for the last occurrence of a character which is not the given character, ignoring case.

Syntax
#include <sastring.h>
char *_str_rchrni(const char *string, int chr);

Returns
A pointer to the last character in string which does not match chr, ignoring case.

NULL if all characters in string match chr, ignoring case.

Notes
This function searches string for the last occurrence of a character which is not chr. The case of ASCII characters is ignored. The search starts with the last character in string and continues until a character is found which does not match chr or until all characters in string have been checked, whichever comes first. A pointer to the last non-occurrence of chr (ignoring case) is returned. NULL is returned if every character in string matches the given character.

NULL is returned if string is a NULL string. This function cannot be used to search for the terminating NULL.

C/C++ Example
	{
	   char string[10], look;
	   char *pointer;
	   ...
	   pointer = _str_rchrni (string, look);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10], look;
	   ...
	   lea si,string
	   mov al,look
	   str_rchrni ();	/* SI = offset of last 
	   	  	 	   non-occurrence of look */
	    jc str_rchrni_010/* all chars match look */
	   ...
	str_rchrni_010:
	   ...
	}

Source file _STRRCNI.ASM ASM equiv STR_RCHRNI
See also
_fstr_rchr, _str_chr, _str_rchr

_str_rev


Descrip
Reverses the order of the characters in a string.

Syntax
#include <sastring.h>
char *_str_rev(char *string);

Returns
A pointer to string.
string a copy of string with characters in reverse order

Notes
This function reverses the order of all characters in string. The terminating NULL is left at the end of the string. A pointer to string is returned.

For example, this function would change "hello world",0 to "dlrow olleh",0.

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_rev (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_rev ();
	   ...
	}

Source file _STRREV.ASM ASM equiv STR_REV
See also
_fstr_rev, _mem_rev

_str_right


Descrip
Right justifies a string within a buffer.

Syntax
#include <sastring.h>
char *_str_right(char *string, char pad, unsigned char width);

Returns
A pointer to string.
string a right-aligned copy of string

Notes
This function pads string on the left with the specified pad character until string is right justified within width. Characters are padded only until the total number of characters equals width. The resulting string is NULL terminated.

C/C++ Example
	#include <sastring.h>
	{
	   char string[11];
	   ...
	   _put_str(_str_right("Hello!", ' ', 10)); /* "    Hello!" */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[11] = "hello!";
	...
	lea si,string/* SI = offset of string */
	mov cl,10	 /* CL = width */
	mov al," "	 /* AL = pad character */
	str_right();	 /* right align string */
	put_str();	 /* "    Hello!" */
	...
	}

Source file _STRRGHT.ASM ASM equiv STR_RIGHT
See also
_cput_str, _fstr_right, _sput_script, _str_center, _str_left

_str_set


Descrip
Sets all characters in a string to a specified character.

Syntax
#include <sastring.h>
char *_str_set(char *string, int chr);

Returns
A pointer to string.
string all characters are replaced with chr

Notes
This function sets all characters in string (except the terminating NULL) to chr. A pointer to string is returned.

C/C++ Example
	{
	   char string1[10];
	   ...
	   _str_set (string1, ' ');
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10];
	   ...
	   lea si,string1
	   mov al,' '
	   str_set ();
	   ...
	}

Source file _STRSET.ASM ASM equiv STR_SET
See also
_fstr_set, _mem_set, _str_nset

_str_skips


Descrip
Skips past space characters in a string.

Syntax
#include <sastring.h>
char *_str_skips(const char *string);

Returns
A pointer to the first non-space character in string.
Notes
This function returns a pointer to the first non-space character in string. For this function, space characters are defined as the space and tab characters (0x20, 0x09).

If string is a NULL string or all characters in string are space characters, a pointer to the terminating NULL of string is returned.

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_skips (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_skips ();/* DS:SI -> first non-space character */
	   ...
	}

Source file _STRSKPS.ASM ASM equiv STR_SKIPS
See also
_fstr_skips, _mem_skips, _str_skipw, _str_trims

_str_skipw


Descrip
Skips past whitespace characters in a string.

Syntax
#include <sastring.h>
char *_str_skipw(const char *string);

Returns
A pointer to the first non-whitespace character in string.

Notes
This function returns a pointer to the first non-whitespace character in string. For this function, white space is defined as the space, tab, carriage, return, and linefeed characters (0x20, 0x09, 0x0D, 0x0A).

If string is a NULL string or all characters in string are whitespace characters, a pointer to the terminating NULL of string is returned.

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_skipw (string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_skipw ();/* SI = offset of first non-whitespace
		      character */
	...
	}

Source file _STRSKPW.ASM ASM equiv STR_SKIPW
See also
_fstr_skipw, _mem_skipw, _str_skips, _str_trimw

_str_spn


Descrip
Determines the number of characters at the beginning of a string which match any character in a given character set.

Syntax
#include <sastring.h>
int _str_spn(const char *string, const char far *charset);

Returns
The number of characters at the beginning of the string that match any character in charset.

Notes
This function compares each character in string to all characters in charset. The comparison starts with the first character of string and continues until one of the characters in string does not match a character in charset. The number of consecutive characters found in charset is returned.

charset must be a NULL-terminated string containing all characters in the character set.

The terminating NULL is never included in the count, so a NULL string always results in a count of 0.

C/C++ Example
	{
	   char string1[10], string2[10];
	   int num;
	   ...
	   num = _str_spn (string1, string2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string1[10], string2[10];
	   ...
	   pushss
	   pop es	 /* ES = SS */
	   lea si,string1
	   lea di,string2
	   str_spn ();/* CX=number of matching characters */
	   ...
	}

Source file _STRSPN.ASM ASM equiv STR_SPN
See also
_fstr_spn, _mem_spn, _str_cspn

_str_str


Descrip
Searches a string for the first occurrence of a substring.

Syntax
#include <sastring.h>
char *_str_str(const char *string, const char far *substr);

Returns
A pointer to the beginning of the first occurrence substr in string.

NULL if substr was not found in string.

Notes
This function searches string for the first occurrence of substr. The search continues until substr is found or until the end of string is encountered, whichever comes first. A pointer to the first occurrence of substr is returned, if one was found. NULL is returned if substr was not found in string.

NULL is returned if the length of either string or substr is 0.

C/C++ Example
	{
	   char string[100], substring[10], *pointer;
	   ...
	   pointer = _str_str (string, substring);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[100], substring[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,string
	   lea di,substring
	   str_str ();	/* SI = offset of first occurrence
	   	  	 	   of substr in string */
	    jc str_str_010/* if substr not found in str */
	   ...
	str_str_010:
	   ...
	}

Source file _STRSTR.ASM ASM equiv STR_STR
See also
_fstr_str, _mem_mem, _str_str

_str_stri


Descrip
Searches a string for the first occurrence of a substring, ignoring case.

Syntax
#include <sastring.h>
char *_str_stri(const char *string, const char far *substr);

Returns
A pointer to the beginning of the first occurrence substr in string.

NULL if substr was not found in string.

Notes
This function searches string for the first occurrence of substr. The case if ASCII characters is ignored. The search continues until substr is found oruntil the end of string is encountered, whichever comes first. A pointer to the first occurrence of substr is returned, if one was found. NULL is returned if substr was not found in string.

NULL is returned if the length of either string or substr is 0.

C/C++ Example
	{
	   char string[100], substring[10], *pointer;
	   ...
	   pointer = _str_stri (string, substring);
	   if (pointer == NULL)
	   {
	      ...
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[100], substring[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,string
	   lea di,substring
	   str_stri ();	/* SI = offset of first occurrence
	   	  	 	   of substr in string */
	    jc str_stri_010/* if substr not found in str */
	   ...
	str_stri_010:
	   ...
	}

Source file _STRSTRI.ASM ASM equiv STR_STRI
See also
_fstr_str, _mem_mem, _str_str

_str_tok


Descrip
Breaks a string into tokens by matching characters in the string with a set of delimiting characters.

Syntax
#include <sastring.h>
char *_str_tok(const char *charset);

Returns
A pointer to a NULL-terminated token in the string initialized by _str_toks.

NULL if no more tokens were found.

Notes
This function parses string, which must have been initialized by _str_toks. This original string is considered to consist of zero or more tokens, each separated by one or more delimiting characters. string is scanned until a non-delimiter character is found. The offset of this character is noted and search continues until a delimiter character or the terminating NULL of string is found. If a delimiter from charset is found, it is replaced with a NULL character. This NULL character marks the end of a token. A pointer to this token is returned. Subsequent calls to _str_tok continue parsing stringfrom where the last call left off. Each call to _str_tok may be made with a different set of delimiting characters.

_str_tok continues parsing the same string for tokens each time it is called (even if none remain) until _str_toks is called again.

When a delimiting character is found following a previous delimiting character (which was changed to NULL by the previous call to _str_tok), it is changed to a NULL. Once the terminating NULL of string is encountered, all subsequent calls to _str_tok return NULL.

C/C++ Example
	{
	   char buffer[100], delimiters[10], *pointer;
	   ...
	   _str_toks(buffer);
	   while ((pointer = _str_tok (delimiters)) != NULL)
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char buffer[100], delimiters[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,buffer
	   str_toks ();
	   lea di,delimiters
	str_tok_010:
	   str_tok ();	/* DS:SI -> next token */
	    jb str_tok_020/* if no more tokens */
	    je str_tok_010/* if a NULL token was found */
	   ... 	 	/* process tokens here */
	   jmp str_tok_010

	str_tok_020:
	   ...
	}

Source file _STRTOK.ASM ASM equiv STR_TOK
See also
_fstr_tok, _str_tok

_str_toks


Descrip
Initializes a string for subsequent tokenization by _str_tok.

Syntax
#include <sastring.h>
void _str_toks(const char *string);
Returns
None

Notes
This function starts a tokenizing process on string in preparation for subsequent calls to _str_tok. This function has no effect on string.

C/C++ Example
	{
	   char buffer[100], delimiters[10], *pointer;
	   ...
	   _str_toks(buffer);
	   while ((pointer = _str_tok (delimiters)) != NULL)
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char buffer[100], delimiters[10];
	   ...
	   pushss
	   pop es	 	/* ES = SS */
	   lea si,buffer
	   str_toks ();
	   lea di,delimiters
	str_tok_010:
	   str_tok ();	/* DS:SI -> next token */
	    jb str_tok_020/* if no more tokens */
	    je str_tok_010/* if a NULL token was found */
	   ... 	 	/* process tokens here */
	   jmp str_tok_010

	str_tok_020:
	   ...
	}

Source file _STRTOK.ASM ASM equiv STR_TOKS
See also
_fstr_tok, _str_tok

_str_trims


Descrip
Removes space characters from the end of a string.

Syntax
#include <sastring.h>
char *_str_trims(char *string);

Returns
A pointer to string.
string a copy of string with trailing space characters removed

Notes
This function removes all space characters from the end of string, if any are found. If all characters in string are space characters, string is returned as aNULL string. A pointer to string is returned. For this function, space characters are defined as the space and tab characters (0x20 and 0x09).

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_trims(string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_trims ();
	   ...
	}

Source file _STRTRMS.ASM ASM equiv STR_TRIMS
See also
_fstr_trims, _str_skips, _str_trimw

_str_trimw


Descrip
Removes whitespace characters from the end of a string.

Syntax
#include <sastring.h>
char *_str_trimw(char *string);

Returns
A pointer to string.
string a copy of string with trailing space characters removed

Notes
This function removes all whitespace characters from the end of string, if any are found. If all characters in string are whitespace characters, string is returned as a NULL string. For this function, whitespace characters are defined as the space, tab, carriage return, and linefeed characters (0x20, 0x09, 0x0D, and 0x0A).

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_trimw(string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char string[10];
	   ...
	   lea si,string
	   str_trimw ();
	   ...
	}

Source file _STRTRMW.ASM ASM equiv STR_TRIMW
See also
_fstr_trimw, _str_skipw, _str_trims

_str_upr


Descrip
Converts lowercase letters in a string to uppercase.

Syntax
#include <sastring.h>
char *_str_upr(char *string);

Returns
A pointer to string.
string a copy of string with ASCII characters converted to uppercase

Notes
This function converts ASCII lowercase letters (a-z) in string to uppercase letters (A-Z). No other characters are modified. A pointer to string is returned.

C/C++ Example
	{
	   char string[10];
	   ...
	   _str_upr(string);
	}

Inline Assembly Example
	#include <inline.h>
	{
	char string[10];
	   ...
	   lea si,string
	   str_upr();
	   ...
	}

Source file _STRUPR.ASM ASM equiv STR_UPR
See also
_fstr_upr, _mem_upr, _str_lwr