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 >
Text File  |  1992-01-31  |  13KB  |  537 lines
  1.  
  2.  
  3.    ez.lib      Version 1.0                  by Joe Siebenmann
  4.  
  5.  
  6.     DISCLAIMER:
  7.  
  8.     You have the right to freely use, copy and distribute this program
  9.     as long as the following conditions are met:
  10.  
  11.     1.  The documentation is included with the program, and neither
  12.         is modified in any way.
  13.  
  14.     2.  The program is not included in any package for profit
  15.         unless written consent from the author is obtained.
  16.  
  17.     NOTE: The author does not accept any responsibility for any damage
  18.            that might result from the use of this program.
  19.  
  20.  
  21.  
  22. Ez.lib is a scanned library consisting of object files which are
  23. individually loaded if there is an external reference to any of them.
  24. Many "c.lib" like functions are included which are not normally available
  25. with assembly language.  All these functions were written in
  26. assembly and should be fast.  With these functions, EZAsm can
  27. be used for a much wider range of programming applications.
  28.  
  29.  
  30.  
  31. NOTE:
  32.  
  33. In the functions below, references to "String1", "StringPointer",
  34. "Buffer" etc. refer to the starting address of, or an address
  35. within a null terminated buffer or memory area.
  36.  
  37.  
  38. WARNING:
  39.  
  40. Since some of these functions write characters into memory locations,
  41. they have the potential to cause disastrous results.  Always make
  42. sure your "strings" are null terminated, and your address registers
  43. are pointing to the right address.
  44.  
  45.  
  46. Register Corruption
  47.  
  48. All functions save and restore all registers used internally.
  49. Unfortunately, in a function call, just passing data to the function's
  50. registers "corrupts" them.  So, if you're using A0 or A1, you'll need to
  51. save and later restore them.  ( I could push and pull them from the stack,
  52. but it would take longer )
  53.  
  54.  
  55.  
  56. *********************
  57. *  Print Functions  *
  58. *********************
  59.  
  60.  
  61. Usage:  PrintInit( )
  62.  
  63.    D0 =
  64.  
  65. Initializes further usage of Print( ) and KPrint( ) functions.
  66. Gets output handle, calls AllocMem() for 127 byte output buffer, and
  67. RawIOInit().  Preserves all registers used.  This should be placed
  68. in your "opening" routine before any Print( ) or KPrint( ) calls.
  69. D0 will contain a non-zero value ( Z = 0 ) if AllocMem() was successful,
  70. otherwise D0 = 0 ( Z = 1 ) on return if failure.
  71.  
  72. ( If PrintInit( ) fails, you don't need to quit.  Print( ) and
  73. KPrint( ) can tell that the allocation failed and will return
  74. without doing anything. )
  75.  
  76.  
  77.  
  78. Usage:  PrintClose( )
  79.  
  80.  
  81. If AllocMem() from PrintInit( ) was successful, this does a FreeMem()
  82. freeing the 127 byte output buffer.  Preserves all registers used.
  83. This should be placed in your "closing" routine after all Print( ) and
  84. KPrint( ) calls.
  85.  
  86.  
  87.  
  88. Usage:  Print( FormatString DataStream )
  89.  
  90.        KPrint( FormatString DataStream )
  91.  
  92.                    A0            A1
  93.  
  94.  
  95. Performs "C" language like formatting of the data stream.
  96. Where % formatting commands are found in the FormatString, they're
  97. replaced with the corresponding element in the DataStream.
  98. Print( ) outputs the results to the current output handle, usually
  99. the CLI.  KPrint( ) is like Kprintf() in that it sends its output
  100. out the serial port at 9600 baud, where if you have another Amiga
  101. hooked up with a null modem cable, running a terminal program,
  102. all the output can be captured and reviewed even if your program
  103. is taking over the machine, or crashes!  This is a fantastic debugging tool!
  104.  
  105. More FormatString options and information can be found by looking up
  106. RawDoFmt() ( ExecBase ) which this uses.
  107.  
  108.  
  109. FormatString
  110.  
  111.     A "C" language like null terminated format string,
  112.     with these % options:
  113.  
  114.     %[length]type
  115.  
  116.     length - data size:  'l' for LONG  ( WORD is the default size )
  117.          ( BYTE data must be moved to a WORD or LONG for display )
  118.  
  119.     type   - types supported:
  120.  
  121.          d - decimal
  122.          x - hexadecimal
  123.          s - string
  124.          c - character
  125.  
  126.  
  127. DataStream
  128.  
  129.     Address of a variable ( single ), or address of buffer
  130.     containing contents of multiple variables, or values.
  131.  
  132.  
  133. o    EZAsm now supports argument strings surrounded by double quotes.
  134.     The following "C" character constants are supported:
  135.  
  136.         \b    backspace
  137.         \f    form feed
  138.         \n    newline
  139.         \r    carriage return
  140.         \t    horizontal tab
  141.         \v    vertical tab
  142.  
  143.     Strings are automatically null terminated.
  144.  
  145.  
  146.  
  147.  
  148. ------------------------------------------------------------------
  149.  
  150. *Example:
  151.  
  152.  
  153.  
  154. LONG    Buf bar
  155. WORD    foo
  156.  
  157.  
  158.     Buf = AllocMem( 6 $10001 )    ;get DataStream buffer
  159.     beq    Quit
  160.  
  161.     PrintInit( )    ;initialize...
  162.     beq    Quit    ;failed?
  163.  
  164.     bar = 1024
  165.     foo = 110    ;give 'um some values..
  166.  
  167.  
  168. *  This first example just prints a string ( A1 contents arn't important )
  169.  
  170.     Print( "Hello, World!\n" * )
  171.  
  172.  
  173. *  This is how to print just one variable.  The use of "&" ( address of )
  174. *  replaces the need to use "lea  foo(a5),a1" to pre-load A1, and can
  175. *  ONLY be used inside function arguments.
  176.  
  177.     Print( "The answer is %d\n" &foo )
  178.  
  179.  
  180. *  This is how to print two or more variables.. ( a little more work )
  181.  
  182.  
  183.     a1 = Buf    ;load addr of buffer into A1
  184.     (a1) = foo    ;load contents of "foo" into first two bytes
  185.     2(a1) = bar    ;load contents of "bar" into next four bytes 
  186.     
  187.     Print( "foo = %d  bar = %ld\n" * )    ;( A1 is already loaded )
  188.  
  189. Quit
  190.  
  191.     PrintClose( )
  192.  
  193.     Buf != 0 {
  194.         FreeMem( Buf 6 )
  195.     }
  196.  
  197.  
  198.     END
  199.  
  200. -----------------------------------------------------------------
  201.  
  202.  
  203.  
  204. *************************
  205. *  Character Functions  *
  206. *************************
  207.  
  208.                            A0
  209.  
  210. Usage:   [!] is.....( StringPointer ) {
  211.                        .
  212.                        .
  213.              }
  214.  
  215.  
  216.          [!] is.....( StringPointer ) {
  217.                        .
  218.                        .
  219.              } else {
  220.                        .
  221.                        .
  222.              }
  223.  
  224.  
  225.          [!] is.....( StringPointer ) label
  226.  
  227.  
  228. Takes the character ( byte ) that A0 points to, and if the test is satisfied,
  229. performs the TRUE action.
  230.  
  231.  
  232. These "C" like functions are supported:
  233.  
  234.  
  235. isalnum( )    alphabetic or digit character?
  236. isalpha( )    alphabetic character?
  237. isascii( )    ASCII character?    ( $0-$7f )
  238. iscntrl( )    control character?    ( $0-$1f or $7f )
  239. isdigit( )    digit character?
  240. isgraph( )    graphics character?    ( $21-$7e )
  241. islower( )    lowercase letter?
  242. isprint( )    printable character ( including space )?
  243. ispunct( )    punctuation character?
  244. isspace( )    white space character?    ( $20 $09-$0c ) 
  245. isupper( )    uppercase letter?
  246. isxdigit( )    hexadecimal digit character?
  247.  
  248.  
  249.  
  250.  
  251. ********************
  252. *  String Compare  *
  253. ********************
  254.  
  255.  
  256. Usage:    [result =] strcmp( String1 String2 ) 
  257.                D0 =            A0      A1
  258.  
  259.  
  260.           [result =] strncmp( String1 String2 Length )
  261.                D0 =              A0      A1     D0      
  262.  
  263.  
  264.  
  265.                  [!] str...( String1 String2 ) {
  266.                               .
  267.                               .
  268.                      }
  269.  
  270.  
  271.                  [!] str...( String1 String2 ) {
  272.                               .
  273.                               .
  274.                      } else {
  275.                               .
  276.                               .
  277.                      }
  278.  
  279.  
  280.                  [!] str...( String1 String2 ) label
  281.  
  282.  
  283. Compares strings String1 and String2 ( for strncmp( ), at most,
  284. Length characters are compared )  The return value is -1 if String1
  285. was less, 1 if String1 was greater, and 0 if String1 and String2
  286. match exactly.
  287.  
  288.  
  289. The zero or non-zero result in D0 "sets" the Z flag.
  290. Its the state of this flag that determines what action is taken.
  291. As with the "C" versions, a non-zero result will perform the TRUE
  292. action.  The most common test is for strings being equal, so "!"
  293. must be used to "flip" the zero result.  To test for not equal
  294. just don't use "!".  Use the "result =" form to save the result
  295. for specific condition testing or just test D0.
  296.  
  297. Note:
  298.  
  299. One of the unique features of using assembly is the ability
  300. to do to following:
  301.  
  302.     tst.l d0    ;( or other instruction that sets condition flags )
  303.     beq   EQUAL
  304.     bne   NOTEQUAL
  305.     bmi   NEG
  306.     bpl   POS
  307.  
  308. No "re-testing" of the condition is needed!  The branch on condition
  309. instructions don't alter the condition code flags, so you can keep on
  310. testing.  I'd like to come up with a new statement to take
  311. advantage of this, also getting rid of the "!".
  312.  
  313.  
  314.  
  315.  
  316. *********************
  317. *  Data Conversion  *
  318. *********************
  319.  
  320.  
  321.  
  322. Usage:  D0 = AtoI( Buffer  FormatString )
  323.  
  324.                      A0         A1
  325.  
  326.  
  327. Converts ASCII digit characters found at Buffer address, according to
  328. the format specified by FormatString, and places the result in D0.
  329. Conversion is stopped when a non-valid digit character is found.
  330.  
  331. Buffer
  332.     Address of first ASCII digit character.
  333.  
  334. FormatString
  335.  
  336.     "%d"    convert to signed decimal number
  337.     "%x"    convert to hexadecimal number
  338.  
  339. ----------------------------------------------
  340.  
  341. Usage:  ItoA( Buffer  FormatString  Number )
  342.  
  343.                A0         A1          D0
  344.  
  345.  
  346. Converts binary value in Number, according to the format specified by
  347. the FormatString, and the resulting ASCII digit characters are
  348. placed at Buffer address.
  349.  
  350.  
  351. Buffer
  352.     Address of buffer you've allocated.  Must be large enough to hold
  353.     all the digit characters and a leading "-" if needed.
  354.  
  355. FormatString
  356.  
  357.     "%d"    convert to signed decimal number string
  358.     "%x"    convert to hexadecimal number string
  359.  
  360. Number
  361.     long, word, or byte sized number in D0
  362.  
  363. ----------------------------------------------
  364.  
  365.  
  366.  
  367.  
  368.  
  369. **********************
  370. *  String Functions  *
  371. **********************
  372.  
  373.  
  374.  
  375.  
  376. Usage:  [location =] search( String1 String2 )
  377.  
  378.                D0 =            A0      A1       
  379.  
  380. Searches for the first occurance of String2 starting at address
  381. specified by String1.  If a match is found, the address of the first
  382. matching byte in String1 is returned in D0 ( Z = 0 ),
  383. otherwise null is returned ( D0 = 0 ) ( Z = 1 )
  384.  
  385. ( Use this function when searching for two or more characters
  386. ( strchr( ) is better for single character searches )) 
  387.  
  388. ----------------------------------------
  389.  
  390. Usage:    insert( String1 String2 )
  391.  
  392.                   A0       A1
  393.  
  394. Inserts String2 ( excluding null byte ) starting at address specified by
  395. String1.  ( String1 must be large enough to hold the extra bytes )
  396.  
  397. ----------------------------------------
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407. The following work the same as standard "C" functions:
  408.  
  409.  
  410. Usage: [location =] strcat( String1 String2 )
  411.  
  412.               D0 =            A0       A1
  413.  
  414.  
  415. Concatenates character string String2 to the end of String1,
  416. placing a null byte at the end of the final string.
  417. Returns ( original ) address of String1 in D0.        
  418.  
  419. ----------------------------------------
  420.  
  421. Usage: [location =] strchr( String1 Char )
  422.  
  423.               D0 =            A0     D0
  424.  
  425.  
  426. Searches String1 for the first occurance of character Char.
  427. If it's found, the address of the character is
  428. returned in D0 ( Z = 0 ), otherwise D0 = 0 ( Z = 1 ).
  429.  
  430. ( be sure the actual character value is loaded into D0, not
  431. its address ( use: #'x' ))
  432.  
  433. ----------------------------------------
  434.  
  435. Usage: [location =] strcpy( String1 String2 )
  436.  
  437.               D0 =            A0       A1
  438.  
  439.  
  440. Copies String2 to String1, returning ( original ) addr of String1.
  441.  
  442. ----------------------------------------
  443.  
  444. Usage: [length =] strlen( String1 )
  445.  
  446.             D0 =             A0
  447.  
  448. Returns the number of characters in String1, excluding the
  449. null byte.
  450.  
  451. ----------------------------------------
  452.  
  453. Usage: [location =] strncat( String1 String2 Length )
  454.  
  455.               D0 =              A0      A1    D1
  456.  
  457.  
  458. Concatenates character string String2 to the end of String1,
  459. until either the null byte is reached, or Length bytes have been
  460. concatenated, whichever occurs first.  Returns ( original ) addr
  461. of String1.
  462.  
  463. ----------------------------------------
  464.  
  465. Usage: [location =] strncpy( String1 String2 Length )
  466.  
  467.               D0 =             A0       A1    D1
  468.  
  469.  
  470. Copies String2 to String1 until either the null byte is reached,
  471. or Length bytes have been copied, whichever occurs first.
  472. Returns ( original ) addr of String1.
  473.  
  474. ----------------------------------------
  475.  
  476. Usage: [location =] strrchr( String1 Char )
  477.  
  478.               D0 =             A0     D0
  479.  
  480.  
  481. Searches String1 for the last occurance of the character Char.
  482. If found, its address is returned in D0 ( Z = 0 ), otherwise
  483. D0 = 0 ( Z = 1 ).
  484.  
  485. ( be sure the actual character value is loaded into D0, not
  486. its address ( use: #'x' ))
  487.  
  488. ----------------------------------------
  489.  
  490. *Example:
  491.  
  492.  
  493.  
  494. LONG    CharAddr Buf
  495.  
  496.  
  497.     Buf = AllocMem( 8 $10001 )    ;"string" buffer
  498.     beq    Quit
  499.  
  500.     strcpy( Buf "abc" )
  501.     strcat( Buf "xyz" )
  502.  
  503. *    ( Buf will now contain "abcxyz" )
  504.  
  505.  
  506.     CharAddr = strchr( Buf #'b' )
  507.  
  508. *   (  #'b' is an easy way to load a search character into D0 )
  509.  
  510.  
  511.     a0 = Buf    ;load address of Buf into A0
  512.     a0 ++        ;inc to next byte ( "b" )
  513.  
  514.     isalpha( * ) {        ;A0 already loaded
  515.         CharAddr = 0    ;"b" is alpha, so this would be done..
  516.     }
  517.  
  518.  
  519. Quit
  520.  
  521.     Buf != 0 {
  522.         FreeMem( Buf 8 )
  523.     }
  524.  
  525.  
  526.     END
  527.  
  528.  
  529. --------------------------------------------
  530.  
  531. If you have any ideas for more functions to add
  532. please let me know.
  533.  
  534.  
  535. Enjoy!
  536.  
  537.