home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 1: Amiga
/
FrozenFish-Apr94.iso
/
bbs
/
alib
/
d5xx
/
d592
/
ezasm.lha
/
EZAsm
/
EZLib.doc
< prev
next >
Wrap
Text File
|
1992-01-31
|
13KB
|
537 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
please let me know.
Enjoy!