home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / prog-asm / ezasm.lha / EZLib.doc < prev    next >
Encoding:
Text File  |  1992-07-14  |  9.8 KB  |  421 lines
  1.  
  2.  
  3.    ez.lib      Version 1.3                  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.         Inclusion in a PD series is OK as long as the charge
  17.         ( for disk, copying etc. ) is REASONABLE.
  18.  
  19.     NOTE: The author does not accept any responsibility for any damage
  20.            that might result from the use of this program.
  21.  
  22.  
  23.  
  24.  
  25.         ---  New for Version 1.3  ---
  26.  
  27.  
  28. o    All function arguments are now pushed onto the stack to avoid
  29.     register corruption.
  30.  
  31. o    New function sprint( ), replaces ItoA( ).  Works just like
  32.     C's sprintf().
  33.  
  34. o    Print( ) and KPrint( ) improved!  No more PrintInit( ) and
  35.     PrintClose( )!  Now accepts multiple DataStream arguments!
  36.     ( also sprint( ) )
  37.  
  38.  
  39.  
  40.  
  41.  
  42. Ez.lib is a scanned library consisting of object files which are
  43. individually loaded if there is an external reference to one of them.
  44. Many "c.lib" like functions are included which are not normally available
  45. with assembly language.  With these functions, EZAsm can be used
  46. for a much wider range of programming applications.
  47.  
  48.  
  49.  
  50. WARNING:
  51.  
  52. Since some of these functions write characters into memory locations,
  53. they have the potential to cause disastrous results.  Always make
  54. sure your "strings" are null terminated, and your address registers
  55. are pointing to the right address.
  56.  
  57.  
  58.  
  59. *********************
  60. *  Print Functions  *
  61. *********************
  62.  
  63.  
  64. Usage:  Print( FormatString DataStream []... )
  65.  
  66.        KPrint( FormatString DataStream []... )
  67.  
  68.  
  69.  
  70. Performs C-like formatting of the data stream.
  71. Where % formatting commands are found in the FormatString, they're
  72. replaced with the corresponding element(s) in the DataStream.
  73. Print( ) outputs the results to the current output handle.
  74. KPrint( ) is like Kprintf() in that it sends its output
  75. out the serial port at 9600 baud, where if you have another computer
  76. running a terminal program, and hooked up with a null modem cable,
  77. all the output can be captured and reviewed, even if your program is
  78. taking over the machine, or crashes!  This is a fantastic debugging tool!
  79.  
  80. More FormatString options and information can be found by looking up
  81. RawDoFmt() ( ExecBase ) which this uses.
  82.  
  83.  
  84. FormatString
  85.  
  86.     A C-like null terminated format string,
  87.     with these % options:
  88.  
  89.     %[length]type
  90.  
  91.     length - data size:  'l' for LONG  ( WORD is the default size )
  92.          ( BYTE data MUST be moved to a WORD or LONG for display )
  93.  
  94.     type   - types supported:
  95.  
  96.          d - decimal
  97.          x - hexadecimal
  98.          s - string
  99.          c - character
  100.  
  101.  
  102. DataStream
  103.  
  104.     Accepts multiple variable names, registers or constants.
  105.  
  106.     Constant data ( 2, $f4, '#', etc. ) is pushed as LONG, so use 'l'.
  107.     ( %ld  %lx  %lc )
  108.  
  109.  
  110. Examples:
  111.  
  112.     Print( "Hello, World!\n" * )
  113.  
  114.     Print( "word %ld = %s\n" 1 "YHWH" )
  115.  
  116.     KPrint( "foo = %08lx  D2 = %08lx\n" foo d2 )
  117.  
  118.  
  119.  
  120.  
  121.     A 200 byte buffer for K/Print( ) is allocated on the stack frame
  122.     ( at .pbuf ) so no AllocMem( ) is needed.  Be careful when using "%s"
  123.     and printing large strings, as this can overflow the buffer and
  124.     trash your variables.
  125.  
  126.     Print( ) needs the current output handle, and _DosBase,
  127.     and will get these automatically.  "OutHandle" will contain
  128.     the current output handle, and is available for use.
  129.  
  130.  
  131. o    EZAsm supports argument strings surrounded by double quotes.
  132.     Strings are automatically null terminated.
  133.     The following C character constants are supported:
  134.  
  135.         \b    backspace
  136.         \f    form feed
  137.         \n    newline
  138.         \r    carriage return
  139.         \t    horizontal tab
  140.         \v    vertical tab
  141.  
  142.  
  143.  
  144. *************************
  145. *  Character Functions  *
  146. *************************
  147.  
  148.  
  149. Usage:   [!] is.....( StringPointer ) {
  150.                        .
  151.                        .
  152.              }
  153.  
  154.  
  155.          [!] is.....( StringPointer ) {
  156.                        .
  157.                        .
  158.              } else {
  159.                        .
  160.                        .
  161.              }
  162.  
  163.  
  164.          [!] is.....( StringPointer ) label
  165.  
  166.  
  167.  
  168. Looks at the character ( byte ) at StringPointer address and,
  169. if the test is satisfied, performs the TRUE action.
  170.  
  171.  
  172. These C-like functions are supported:
  173.  
  174.  
  175. isalnum( )    alphabetic or digit character?
  176. isalpha( )    alphabetic character?
  177. isascii( )    ASCII character?    ( $0-$7f )
  178. iscntrl( )    control character?    ( $0-$1f or $7f )
  179. isdigit( )    digit character?
  180. isgraph( )    graphics character?    ( $21-$7e )
  181. islower( )    lowercase letter?
  182. isprint( )    printable character? ( including space )
  183. ispunct( )    punctuation character?
  184. isspace( )    white space character?    ( $20 $09-$0c ) 
  185. isupper( )    uppercase letter?
  186. isxdigit( )    hexadecimal digit character?
  187.  
  188.  
  189.  
  190.  
  191. ********************
  192. *  String Compare  *
  193. ********************
  194.  
  195.  
  196. Usage:    [result =] strcmp( String1 String2 ) 
  197.  
  198.  
  199.           [result =] strncmp( String1 String2 Length )
  200.  
  201.  
  202.  
  203.                  [!] str...( String1 String2 ) {
  204.                               .
  205.                               .
  206.                      }
  207.  
  208.  
  209.                  [!] str...( String1 String2 ) {
  210.                               .
  211.                               .
  212.                      } else {
  213.                               .
  214.                               .
  215.                      }
  216.  
  217.  
  218.                  [!] str...( String1 String2 ) label
  219.  
  220.  
  221.  
  222. Compares strings String1 and String2 ( for strncmp( ), at most,
  223. Length characters are compared )  The return value is -1 if String1
  224. was less, 1 if String1 was greater, and 0 if String1 and String2
  225. match exactly.
  226.  
  227.  
  228. The zero or non-zero result in D0 "sets" the Z flag.
  229. Its the state of this flag that determines what action is taken.
  230. As with the C versions, a non-zero result will perform the TRUE
  231. action.  The most common test is for strings being equal, so "!"
  232. must be used to "flip" the zero result.  To test for not equal
  233. omit the "!".  Use the "result =" form to save the result
  234. for specific condition testing or just test D0.
  235.  
  236.  
  237.  
  238. *********************
  239. *  Data Conversion  *
  240. *********************
  241.  
  242.  
  243.  
  244. Usage:  D0 = AtoI( StrAddr  FormatString )
  245.  
  246.  
  247.  
  248. Converts ASCII digit characters found at StrAddr, according to
  249. the format specified by FormatString, and places the result in D0.
  250. Conversion is stopped when a non-valid digit character is found.
  251.  
  252. Buffer
  253.     Address of first ASCII digit character.
  254.  
  255. FormatString
  256.  
  257.     "%d"    convert [signed] decimal number
  258.     "%x"    convert hexadecimal number
  259.  
  260. ----------------------------------------------
  261.  
  262. Usage:    sprint( Buffer FormatString DataStream []... )
  263.  
  264.  
  265.  
  266. Performs C-like formatting of the data stream.
  267. Where % formatting commands are found in the FormatString, they're
  268. replaced with the corresponding element(s) in the DataStream.
  269. The result is placed in Buffer.
  270.  
  271. More FormatString options and information can be found by looking up
  272. RawDoFmt() ( ExecBase ) which this uses.
  273.  
  274.  
  275. Buffer
  276.  
  277.     Address of buffer large enough to hold the resulting string.
  278.  
  279.  
  280. FormatString
  281.  
  282.     A C-like null terminated format string,
  283.     with these % options:
  284.  
  285.     %[length]type
  286.  
  287.     length - data size:  'l' for LONG  ( WORD is the default size )
  288.          ( BYTE data MUST be moved to a WORD or LONG )
  289.  
  290.     type   - types supported:
  291.  
  292.          d - decimal
  293.          x - hexadecimal
  294.          s - string
  295.          c - character
  296.                   
  297.  
  298. DataStream
  299.  
  300.     Accepts multiple variable names, registers or constants.
  301.  
  302.     Constant data ( 2, $f4, '#', etc. ) is pushed as LONG, so use 'l'.
  303.     ( %ld  %lx  %lc )
  304.  
  305.  
  306.  
  307. Example:
  308.  
  309.     sprint( Buf "\t\tmove%s\t#%ld,d1\n" ".l" 0 )
  310.  
  311.     ( see Mk.s for more examples )
  312.  
  313.  
  314.  
  315. **********************
  316. *  String Functions  *
  317. **********************
  318.  
  319.  
  320.  
  321.  
  322. Usage:  [location =] search( StrAddr String )
  323.  
  324.  
  325. Searches for the first occurance of String starting at
  326. StrAddr.  If a match is found, the address of the first
  327. matching byte from StrAddr is returned in D0, otherwise D0 = 0.
  328.  
  329. ( Use this function when searching for two or more characters
  330. ( strchr( ) is better for single character searches )) 
  331.  
  332. ----------------------------------------
  333.  
  334. Usage:    insert( StrAddr String )
  335.  
  336.  
  337. Inserts String ( excluding null byte ) starting at
  338. StrAddr ( address returned by a previous string search function etc. ). 
  339. ( buffer at StrAddr must be large enough to hold the extra bytes )
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346. *********************************
  347. *  Standard C string functions  *
  348. *********************************
  349.  
  350.  
  351. Usage: [location =] strcat( StrAddr String )
  352.  
  353.  
  354. Concatenates character string String to the end of StrAddr,
  355. placing a null byte at the end of the final string.
  356. Returns ( original ) address of StrAddr in D0.        
  357.  
  358. ----------------------------------------
  359.  
  360. Usage: [location =] strchr( StrAddr Char )
  361.  
  362.  
  363. Searches at StrAddr for the first occurance of character Char.
  364. If it's found, the address of the character is
  365. returned in D0, otherwise D0 = 0.
  366.  
  367. ( be sure the actual character value is loaded into Char, not
  368. its address ( use: #'x' ))
  369.  
  370. ----------------------------------------
  371.  
  372. Usage: [location =] strcpy( StrAddr String )
  373.  
  374.  
  375. Copies String to StrAddr, returning ( original ) addr of StrAddr
  376. in D0.
  377.  
  378. ----------------------------------------
  379.  
  380. Usage: [length =] strlen( StrAddr )
  381.  
  382.  
  383. Returns the number of characters at StrAddr, excluding the
  384. null byte in D0.
  385.  
  386. ----------------------------------------
  387.  
  388. Usage: [location =] strncat( StrAddr String Length )
  389.  
  390.  
  391. Concatenates character string String to the end of StrAddr,
  392. until either the null byte is reached, or Length bytes have been
  393. concatenated, whichever occurs first.  Returns ( original ) addr
  394. of StrAddr in D0.
  395.  
  396. ----------------------------------------
  397.  
  398. Usage: [location =] strncpy( StrAddr String Length )
  399.  
  400.  
  401. Copies String to StrAddr until either the null byte is reached,
  402. or Length bytes have been copied, whichever occurs first.
  403. Returns ( original ) addr of StrAddr in D0.
  404.  
  405. ----------------------------------------
  406.  
  407. Usage: [location =] strrchr( StrAddr Char )
  408.  
  409.  
  410. Searches at StrAddr for the last occurance of the character Char.
  411. If found, its address is returned in D0, otherwise D0 = 0.
  412.  
  413. ( be sure the actual character value is loaded into Char, not
  414. its address ( use: #'x' ))
  415.  
  416. ----------------------------------------
  417.  
  418.  
  419. Enjoy!
  420.  
  421.