Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 529a.lha / EZAsm_v1.5 / EZLib.doc.pp / EZLib.doc

Wrap

Text File | 1991-07-02 | 12.5 KB | 538 lines

ez.lib Version 1.0 by Joe Siebenmann DISCLAIMER: You have the right to freely use, copy and distribute this program as long as the following conditions are met: 1. The documentation is included with the program, and neither is modified in any way. 2. The program is not included in any package for profit unless written consent from the author is obtained. NOTE: The author does not accept any responsibility for any damage that might result from the use of this program. Ez.lib is a scanned library consisting of object files which are individually loaded if there is an external reference to any of them. Many "c.lib" like functions are included which are not normally available with assembly language. All these functions were written in assembly and should be fast. With these functions, EZAsm can be used for a much wider range of programming applications. NOTE: In the functions below, references to "String1", "StringPointer", "Buffer" etc. refer to the starting address of, or an address within a null terminated buffer or memory area. WARNING: Since some of these functions write characters into memory locations, they have the potential to cause disastrous results. Always make sure your "strings" are null terminated, and your address registers are pointing to the right address. Register Corruption All functions save and restore all registers used internally. Unfortunately, in a function call, just passing data to the function's registers corrupts them. So, if you're using A0 or A1, you'll need to save and later restore them. ( I could push and pull them from the stack, but it would take longer ) ********************* * Print Functions * ********************* Usage: PrintInit( ) D0 = Initializes further usage of Print( ) and KPrint( ) functions. Gets output handle, calls AllocMem() for 127 byte output buffer, and RawIOInit(). Preserves all registers used. This should be placed in your "opening" routine before any Print( ) or KPrint( ) calls. D0 will contain a non-zero value ( Z = 0 ) if AllocMem() was successful, otherwise D0 = 0 ( Z = 1 ) on return if failure. ( If PrintInit( ) fails, you don't need to quit. Print( ) and KPrint( ) can tell that the allocation failed and will return without doing anything. ) Usage: PrintClose( ) If AllocMem() from PrintInit( ) was successful, this does a FreeMem() freeing the 127 byte output buffer. Preserves all registers used. This should be placed in your "closing" routine after all Print( ) and KPrint( ) calls. Usage: Print( FormatString DataStream ) KPrint( FormatString DataStream ) A0 A1 Performs "C" language like formatting of the data stream. Where % formatting commands are found in the FormatString, they're replaced with the corresponding element in the DataStream. Print( ) outputs the results to the current output handle, usually the CLI. KPrint( ) is like Kprintf() in that it sends its output out the serial port at 9600 baud, where if you have another Amiga hooked up with a null modem cable, running a terminal program, all the output can be captured and reviewed even if your program is taking over the machine, or crashes! This is a fantastic debugging tool! More FormatString options and information can be found by looking up RawDoFmt() ( ExecBase ) which this uses. FormatString A "C" language like null terminated format string, with these % options: %[length]type length - data size: 'l' for LONG ( WORD is the default size ) ( BYTE data must be moved to a WORD or LONG for display ) type - types supported: d - decimal x - hexadecimal s - string c - character DataStream Address of a variable ( single ), or address of buffer containing contents of multiple variables, or values. o EZAsm now supports argument strings surrounded by double quotes. The following "C" character constants are supported: \b backspace \f form feed \n newline \r carriage return \t horizontal tab \v vertical tab Strings are automatically null terminated. ------------------------------------------------------------------ *Example: LONG Buf bar WORD foo Buf = AllocMem( 6 $10001 ) ;get DataStream buffer beq Quit PrintInit( ) ;initialize... beq Quit ;failed? bar = 1024 foo = 110 ;give 'um some values.. * This first example just prints a string ( A1 contents arn't important ) Print( "Hello, World!\n" * ) * This is how to print just one variable. The use of "&" ( address of ) * replaces the need to use "lea foo(a5),a1" to pre-load A1, and can * ONLY be used inside function arguments. Print( "The answer is %d\n" &foo ) * This is how to print two or more variables.. ( a little more work ) a1 = Buf ;load addr of buffer into A1 (a1) = foo ;load contents of "foo" into first two bytes 2(a1) = bar ;load contents of "bar" into next four bytes Print( "foo = %d bar = %ld\n" * ) ;( A1 is already loaded ) Quit PrintClose( ) Buf != 0 { FreeMem( Buf 6 ) } END ----------------------------------------------------------------- ************************* * Character Functions * ************************* A0 Usage: [!] is.....( StringPointer ) { . . } [!] is.....( StringPointer ) { . . } else { . . } [!] is.....( StringPointer ) label Takes the character ( byte ) that A0 points to, and if the test is satisfied, performs the TRUE action. These "C" like functions are supported: isalnum( ) alphabetic or digit character? isalpha( ) alphabetic character? isascii( ) ASCII character? ( $0-$7f ) iscntrl( ) control character? ( $0-$1f or $7f ) isdigit( ) digit character? isgraph( ) graphics character? ( $21-$7e ) islower( ) lowercase letter? isprint( ) printable character ( including space )? ispunct( ) punctuation character? isspace( ) white space character? ( $20 $09-$0c ) isupper( ) uppercase letter? isxdigit( ) hexadecimal digit character? ******************** * String Compare * ******************** Usage: [result =] strcmp( String1 String2 ) D0 = A0 A1 [result =] strncmp( String1 String2 Length ) D0 = A0 A1 D0 [!] str...( String1 String2 ) { . . } [!] str...( String1 String2 ) { . . } else { . . } [!] str...( String1 String2 ) label Compares strings String1 and String2 ( for strncmp( ), at most, Length characters are compared ) The return value is -1 if String1 was less, 1 if String1 was greater, and 0 if String1 and String2 match exactly. The zero or non-zero result in D0 "sets" the Z flag. Its the state of this flag that determines what action is taken. As with the "C" versions, a non-zero result will perform the TRUE action. The most common test is for strings being equal, so "!" must be used to "flip" the zero result. To test for not equal just don't use "!". Use the "result =" form to save the result for specific condition testing or just test D0. Note: One of the unique features of using assembly is the ability to do to following: tst.l d0 ;( or other instruction that sets condition flags ) beq EQUAL bne NOTEQUAL bmi NEG bpl POS No "re-testing" of the condition is needed! The branch on condition instructions don't alter the condition code flags, so you can keep on testing. I'd like to come up with a new statement to take advantage of this, also getting rid of the "!". ********************* * Data Conversion * ********************* Usage: D0 = AtoI( Buffer FormatString ) A0 A1 Converts ASCII digit characters found at Buffer address, according to the format specified by FormatString, and places the result in D0. Conversion is stopped when a non-valid digit character is found. Buffer Address of first ASCII digit character. FormatString "%d" convert to signed decimal number "%x" convert to hexadecimal number ---------------------------------------------- Usage: ItoA( Buffer FormatString Number ) A0 A1 D0 Converts binary value in Number, according to the format specified by the FormatString, and the resulting ASCII digit characters are placed at Buffer address. Buffer Address of buffer you've allocated. Must be large enough to hold all the digit characters and a leading "-" if needed. FormatString "%d" convert to signed decimal number string "%x" convert to hexadecimal number string Number long, word, or byte sized number in D0 ---------------------------------------------- ********************** * String Functions * ********************** Usage: [location =] search( String1 String2 ) D0 = A0 A1 Searches for the first occurance of String2 starting at address specified by String1. If a match is found, the address of the first matching byte in String1 is returned in D0 ( Z = 0 ), otherwise null is returned ( D0 = 0 ) ( Z = 1 ) ( Use this function when searching for two or more characters ( strchr( ) is better for single character searches )) ---------------------------------------- Usage: insert( String1 String2 ) A0 A1 Inserts String2 ( excluding null byte ) starting at address specified by String1. ( String1 must be large enough to hold the extra bytes ) ---------------------------------------- The following work the same as standard "C" functions: Usage: [location =] strcat( String1 String2 ) D0 = A0 A1 Concatenates character string String2 to the end of String1, placing a null byte at the end of the final string. Returns ( original ) address of String1 in D0. ---------------------------------------- Usage: [location =] strchr( String1 Char ) D0 = A0 D0 Searches String1 for the first occurance of character Char. If it's found, the address of the character is returned in D0 ( Z = 0 ), otherwise D0 = 0 ( Z = 1 ). ( be sure the actual character value is loaded into D0, not its address ( use: #'x' )) ---------------------------------------- Usage: [location =] strcpy( String1 String2 ) D0 = A0 A1 Copies String2 to String1, returning ( original ) addr of String1. ---------------------------------------- Usage: [length =] strlen( String1 ) D0 = A0 Returns the number of characters in String1, excluding the null byte. ---------------------------------------- Usage: [location =] strncat( String1 String2 Length ) D0 = A0 A1 D1 Concatenates character string String2 to the end of String1, until either the null byte is reached, or Length bytes have been concatenated, whichever occurs first. Returns ( original ) addr of String1. ---------------------------------------- Usage: [location =] strncpy( String1 String2 Length ) D0 = A0 A1 D1 Copies String2 to String1 until either the null byte is reached, or Length bytes have been copied, whichever occurs first. Returns ( original ) addr of String1. ---------------------------------------- Usage: [location =] strrchr( String1 Char ) D0 = A0 D0 Searches String1 for the last occurance of the character Char. If found, its address is returned in D0 ( Z = 0 ), otherwise D0 = 0 ( Z = 1 ). ( be sure the actual character value is loaded into D0, not its address ( use: #'x' )) ---------------------------------------- *Example: LONG CharAddr Buf Buf = AllocMem( 8 $10001 ) ;"string" buffer beq Quit strcpy( Buf "abc" ) strcat( Buf "xyz" ) * ( Buf will now contain "abcxyz" ) CharAddr = strchr( Buf #'b' ) * ( #'b' is an easy way to load a search character into D0 ) a0 = Buf ;load address of Buf into A0 a0 ++ ;inc to next byte ( "b" ) isalpha( * ) { ;A0 already loaded CharAddr = 0 ;"b" is alpha, so this would be done.. } Quit Buf != 0 { FreeMem( Buf 8 ) } END -------------------------------------------- If you have any ideas for more functions to add ( especially new ideas for string functions ) please let me know. Enjoy!