home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / develop / ezasm / ezlib.doc < prev    next >
Text File  |  1995-02-27  |  10KB  |  449 lines
  1.  
  2.  
  3.    ez.lib      Version 1.3                  by Joe Siebenmann
  4.  
  5.  
  6.  
  7.          ***  See the Disclaimer in EZAsm.doc  ***
  8.  
  9.  
  10.     ------ NO LIABILITY FOR CONSEQUENTIAL DAMAGES ------
  11.  
  12.     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES
  13.     WHATSOEVER ARISING OUT OF THE USE OF OR INABILITY TO USE
  14.     THESE PROGRAMS.
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.         ---  New for Version 1.3  ---
  22.  
  23.  
  24. o    New functions:
  25.  
  26.         stricmp()
  27.         gets()
  28.  
  29.  
  30. o    sprint() now returns number of characters processed in D0.
  31.  
  32. o    KPrint(), Print() and AtoI() are now kprint(), print(), and atoi().
  33.  
  34.  
  35.  
  36.  
  37.  
  38. Ez.lib is a scanned library consisting of object files which are
  39. individually loaded if there is an external reference to one of them.
  40. Many "c.lib" like functions are included which are not normally available
  41. with assembly language.  With these functions, EZAsm can be used
  42. for a much wider range of programming applications.
  43.  
  44.  
  45.  
  46. *********************
  47. *  Print Functions  *
  48. *********************
  49.  
  50.  
  51. Usage:  print( FormatString DataStream [...] )
  52.  
  53.        kprint( FormatString DataStream [...] )
  54.  
  55.  
  56.  
  57. Performs C-like formatting of the data stream.
  58. Where % formatting commands are found in the FormatString, they're
  59. replaced with the corresponding element(s) in the DataStream.
  60. print() outputs the results to the current output handle.
  61.  
  62. kprint() is like Kprintf() in that it sends its output
  63. out the serial port at 9600 baud, where if you have another computer
  64. running a terminal program, and hooked up with a null modem cable,
  65. all the output can be captured and reviewed, even if your program is
  66. taking over the machine, or crashes!  This is a fantastic debugging tool!
  67.  
  68. More information on RawDoFmt() ( ExecBase ), which these use, can
  69. be found in the AutoDocs.
  70.  
  71.  
  72. FormatString
  73.  
  74.     A C-like null terminated format string.
  75.     The following % options are supported:
  76.  
  77.     %[flags][width.limit][length]type
  78.  
  79.  
  80.     flags  - '-' specifies left justification.
  81.     width  - field width.  If fist character is a '0', field is
  82.             padded with leading zeros.
  83.     limit  - maximum number of characters output from a string ( %s only )
  84.     length - data size:  'l' for LONG  ( WORD is the default size )
  85.          ( BYTE data MUST be moved to a WORD or LONG for display )
  86.  
  87.     type   - types supported:
  88.  
  89.          d - decimal
  90.          x - hexadecimal
  91.          s - string
  92.          c - character
  93.  
  94.  
  95. DataStream
  96.  
  97.     Accepts MULTIPLE variable names, registers, constants etc..
  98.  
  99.     Constant data ( 2, $f4, 'a', etc. ) is pushed as LONG, so use 'l'.
  100.     ( %ld  %lx  %lc )
  101.  
  102.  
  103. Examples:
  104.  
  105.     print( "word %ld = %s\n" 1 "YHWH" )
  106.  
  107.     kprint( "foo = %08lx  D2 = %08lx\n" foo d2 )
  108.  
  109.  
  110.  
  111.     In print() statements without a DataStream argument, you
  112.     can drop the extra "*" argument and use it like this:
  113.  
  114.     print( "Hello, World!\n" )
  115.  
  116.  
  117.  
  118. o    A 200 byte buffer for k/print() is allocated on the stack frame
  119.     ( at .pbuf ) so no AllocMem() is needed.  Be careful when using "%s"
  120.     and printing large strings, as this could overflow the buffer and
  121.     trash your variables/program.
  122.  
  123. o    print() needs the current output handle, and _DOSBase,
  124.     and will get these automatically.  "OutHandle" will contain
  125.     the current output handle.
  126.  
  127.  
  128. o    EZAsm supports argument strings surrounded by double quotes.
  129.     Strings are automatically NULL terminated.
  130.     The following C character constants are supported:
  131.  
  132.         \b        backspace
  133.         \f        form feed
  134.         \n        newline
  135.         \r        carriage return
  136.         \t        horizontal tab
  137.         \v        vertical tab
  138.         \\        backslash
  139.         \"        double quote
  140.         \'        single quote
  141.         \nnn    octal character value
  142.         \xnn    hex character value
  143.  
  144.  
  145.     Examples:  
  146.  
  147.         "Hello, World!\n"
  148.     
  149.         "\x1b[32mEZAsm  1.8\x1b[39m\n"
  150.  
  151.  
  152.  
  153.  
  154. *************************
  155. *  Character Functions  *
  156. *************************
  157.  
  158.  
  159. Usage:   [!] is.....( StringPointer ) {
  160.                        .
  161.                        .
  162.              }
  163.  
  164.  
  165.          [!] is.....( StringPointer ) {
  166.                        .
  167.                        .
  168.              } else {
  169.                        .
  170.                        .
  171.              }
  172.  
  173.  
  174.          [!] is.....( StringPointer ) label
  175.  
  176.  
  177.  
  178. Looks at the character at StringPointer address and,
  179. if the test is satisfied, based on the Z flag,
  180. performs the TRUE action.
  181.  
  182.  
  183. These C-like functions are supported:
  184.  
  185.  
  186. isalnum()    alphabetic or digit character?
  187. isalpha()    alphabetic character?
  188. isascii()    ASCII character?    ( $0-$7f )
  189. iscntrl()    control character?    ( $0-$1f or $7f )
  190. isdigit()    digit character?
  191. isgraph()    graphics character?    ( $21-$7e )
  192. islower()    lowercase letter?
  193. isprint()    printable character?    ( including space )
  194. ispunct()    punctuation character?
  195. isspace()    white space character?    ( $20 $09-$0c ) 
  196. isupper()    uppercase letter?
  197. isxdigit()    hexadecimal digit character?
  198.  
  199.  
  200.  
  201.  
  202. ********************
  203. *  String Compare  *
  204. ********************
  205.  
  206.  
  207. Usage:    [D0 =] strcmp( String1 String2 ) 
  208.  
  209.           [D0 =] strncmp( String1 String2 Length )
  210.  
  211.           [D0 =] stricmp( String1 String2 )
  212.  
  213.  
  214.  
  215.                  [!] str...( String1 String2 ) {
  216.                               .
  217.                               .
  218.                      }
  219.  
  220.  
  221.                  [!] str...( String1 String2 ) {
  222.                               .
  223.                               .
  224.                      } else {
  225.                               .
  226.                               .
  227.                      }
  228.  
  229.  
  230.                  [!] str...( String1 String2 ) label
  231.  
  232.  
  233.  
  234. Compares strings String1 and String2 ( for strncmp(), at most,
  235. Length characters are compared )  The return value is -1 if String1
  236. was less, 1 if String1 was greater, and 0 if String1 and String2
  237. match exactly.
  238.  
  239. stricmp() is a case insensitive string compare ( "Cat" = "cat" )
  240. returning 0 for equal, <0 if String1 was less, and >0 if String1
  241. was greater.
  242.  
  243. As with the C versions, you'll need to use "!" to "flip" the
  244. zero result when testing for strings being equal.  To test for
  245. not equal, omit the "!".
  246.  
  247.  
  248.  
  249. *********************
  250. *  Data Conversion  *
  251. *********************
  252.  
  253.  
  254.  
  255. Usage:  D0 = atoi( StrAddr  FormatString )
  256.  
  257.  
  258.  
  259. Converts ASCII digit characters found at StrAddr, according to
  260. the format specified by FormatString, and places the result in D0.
  261. Conversion is stopped when a non-valid digit character is found.
  262.  
  263. StrAddr
  264.     Address of first ASCII digit character.
  265.  
  266. FormatString
  267.  
  268.     "%d"    convert (signed) decimal number
  269.     "%x"    convert hexadecimal number
  270.  
  271. ----------------------------------------------
  272.  
  273. Usage:    [D0 =] sprint( Buffer FormatString DataStream [...] )
  274.  
  275.  
  276.  
  277. Performs C-like formatting of the data stream.
  278. Where % formatting commands are found in the FormatString, they're
  279. replaced with the corresponding element(s) in the DataStream.
  280. The result is placed in Buffer.  The number of characters placed into
  281. Buffer is returned in D0, excluding the terminating NULL.
  282.  
  283. More information on RawDoFmt() ( ExecBase ), which this uses, can
  284. be found in the AutoDocs.
  285.  
  286.  
  287. FormatString
  288.  
  289.     A C-like null terminated format string.
  290.     The following % options are supported:
  291.  
  292.     %[flags][width.limit][length]type
  293.  
  294.  
  295.     flags  - '-' specifies left justification.
  296.     width  - field width.  If fist character is a '0', field is
  297.             padded with leading zeros.
  298.     limit  - maximum number of characters output from a string ( %s only )
  299.     length - data size:  'l' for LONG  ( WORD is the default size )
  300.          ( BYTE data MUST be moved to a WORD or LONG for display )
  301.  
  302.     type   - types supported:
  303.  
  304.          d - decimal
  305.          x - hexadecimal
  306.          s - string
  307.          c - character
  308.  
  309.  
  310. DataStream
  311.  
  312.     Accepts MULTIPLE variable names, registers, constants etc..
  313.  
  314.     Constant data ( 2, $f4, 'a', etc. ) is pushed as LONG, so use 'l'.
  315.     ( %ld  %lx  %lc )
  316.  
  317.     
  318.     
  319.  
  320.  
  321.  
  322. Example:
  323.  
  324.     sprint( Buf "\t\tmove%s\t#%ld,d1\n" ".l" 0 )
  325.  
  326.     ( see Mk.s for more examples )
  327.  
  328.  
  329.  
  330. **********************
  331. *  String Functions  *
  332. **********************
  333.  
  334.  
  335.  
  336.  
  337. Usage:  [location =] search( StrAddr String )
  338.  
  339.  
  340. Searches for the first occurance of String starting at
  341. StrAddr.  If a match is found, the address of the first
  342. matching byte from StrAddr is returned in D0, otherwise D0 = 0.
  343.  
  344. ( Use this function when searching for two or more characters
  345. ( strchr() is better for single character searches )) 
  346.  
  347. ----------------------------------------
  348.  
  349. Usage:    insert( StrAddr String )
  350.  
  351.  
  352. Inserts String ( excluding null byte ) starting at
  353. StrAddr ( address returned by a previous string search function etc. ). 
  354. ( buffer at StrAddr must be large enough to hold the extra bytes )
  355.  
  356.  
  357.  
  358. ***********
  359. *  Input  *
  360. ***********
  361.  
  362.  
  363. Usage:    [D0 =] gets( Buffer )
  364.  
  365.  
  366. Reads characters into your Buffer until a newline character is read.
  367. The newline character isn't stored in Buffer, and the character
  368. string is NULL terminated.  The Buffer address is returned in D0.
  369. Buffer should not exceed 127 bytes.
  370.  
  371.  
  372.  
  373.  
  374. *********************************
  375. *  Standard C string functions  *
  376. *********************************
  377.  
  378.  
  379. Usage: [location =] strcat( StrAddr String )
  380.  
  381.  
  382. Concatenates character string String to the end of StrAddr,
  383. placing a null byte at the end of the final string.
  384. Returns ( original ) address of StrAddr in D0.        
  385.  
  386. ----------------------------------------
  387.  
  388. Usage: [location =] strchr( StrAddr Char )
  389.  
  390.  
  391. Searches at StrAddr for the first occurance of character Char.
  392. If it's found, the address of the character is
  393. returned in D0, otherwise D0 = 0.
  394.  
  395. ( be sure the actual character value is loaded into Char, not
  396. its address ( use: #'x' ))
  397.  
  398. ----------------------------------------
  399.  
  400. Usage: [location =] strcpy( StrAddr String )
  401.  
  402.  
  403. Copies String to StrAddr, returning ( original ) addr of StrAddr
  404. in D0.
  405.  
  406. ----------------------------------------
  407.  
  408. Usage: [length =] strlen( StrAddr )
  409.  
  410.  
  411. Returns the number of characters at StrAddr, excluding the
  412. null byte in D0.
  413.  
  414. ----------------------------------------
  415.  
  416. Usage: [location =] strncat( StrAddr String Length )
  417.  
  418.  
  419. Concatenates character string String to the end of StrAddr,
  420. until either the null byte is reached, or Length bytes have been
  421. concatenated, whichever occurs first.  Returns ( original ) addr
  422. of StrAddr in D0.
  423.  
  424. ----------------------------------------
  425.  
  426. Usage: [location =] strncpy( StrAddr String Length )
  427.  
  428.  
  429. Copies String to StrAddr until either the null byte is reached,
  430. or Length bytes have been copied, whichever occurs first.
  431. Returns ( original ) addr of StrAddr in D0.
  432.  
  433. ----------------------------------------
  434.  
  435. Usage: [location =] strrchr( StrAddr Char )
  436.  
  437.  
  438. Searches at StrAddr for the last occurance of the character Char.
  439. If found, its address is returned in D0, otherwise D0 = 0.
  440.  
  441. ( be sure the actual character value is loaded into Char, not
  442. its address ( use: #'x' ))
  443.  
  444. ----------------------------------------
  445.  
  446.  
  447. Enjoy!
  448.  
  449.