C02/doc/block.txt

Block Memory Functions

This library contains functions for accessing data in blocks of memory. 
A block consists of up to 65,535 contiguous bytes. This allows for the
storage, retrieval, and manipulation of data exceeding the maximum
array length of 255.

These functions assume that a block is divided into equally sized segments
of up to 255 bytes in length. Data in the block is accessed by copying
data into and out of arrays with the same length as the segment size.

A segment consists of a string field, which is used as a key, followed 
by a number of individual bytes. For example, the segments in a variable
table might be 9 bytes long, consisting of a 7 byte variable name string
(6 characters plus a terminator), the variable type (at index 7) and 
the variable length (at index 8).

Usage: at the beginning of the program use the directives

  #include <memory.h02>
  #include <string.h02>
  #include <block.h02>

The following application functions are defined:

  blkbgn(&b);         Block Begin: Set beginning of block to address b. 

                      The beginning of a block is the first byte of memory 
                      in the block.

                      Although a block usually begins on a 256 byte
                      boundary, this is not required.
                      
                      Note: Sets variables blkslo and blkshi.

  blkend(&e);         Block End: Set end of block to address b. The end of 
                      a block is the byte after the last byte of memory in 
                      the block.

                      Although a block usually begins on a 256 byte
                      boundary, this is not required.
                      
                      Note: Sets variables blkslo and blkshi.

  blkseg(n);          Block Segment: Set block segment size to n.
  
                      Required before calls any calls that manipulate
                      block segments.
                      
                      Note: Sets blklen to n.

  blkset(c);          Block Set: Fill entire block with character c,
                      leaving block pointer at end of block.
  
                      Used to initialize a block before use.

  blkrst();           Block Reset: Set block segment pointer to block 
                      begin address.
  
                      This routine is called before populating a block with
                      calls to the blkapd function.

  blknxt();           Block Next: Move block pointer forward by the segment
                      length set by a prior blkseg call.

                      If the block pointer is moved past the end of the
                      block, a value of 0 (false) is returned. Otherwise,
                      a value of 255 (true) is returned.
                      
  blkput(n ,&m);      Block Append: Copy n bytes of array m to block
                      at current pointer location, and moves block pointer 
                      forward by the segment length set by a prior blkseg
                      call.
                      
                      If the appended bytes would overflow the end of the
                      block, no bytes are copied and a value of 0 (false)
                      is returned. Otherwise, the bytes are copied and
                      a value of 255 (true) is returned.
                      
                      Note: Sets dstlo and dsthi to the block pointer prior
                      to the copy, updates blkslo and blkshi, then calls
                      the memcpy function.
                      
  blkget(n ,&m);      Block Get: Copy n bytes from block at current 
                      pointer location to array m, and moves block pointer 
                      forward by the segment length set by a prior blkseg
                      call.
                      
                      If the copied bytes would overflow the end of the
                      block, no bytes are copied and a value of 0 (false)
                      is returned. Otherwise, the bytes are copied and
                      a value of 255 (true) is returned.
                      
                      Note: Sets dstlo and dsthi to the address of m, 
                      srclo and srchi to the block pointer prior to the 
                      copy, updates blkslo and blkshi, then calls the 
                      memcpy function.
                      
  blkmem(n ,&m);      Block Memory search: Search block for n byte long
                      segment matching array m. 
                      
                      If a matching segment is found, the value 255 (true)
                      is returned and the destination pointer is set to the 
                      address of the matching segment, allowing it to be 
                      overwritten with a subsequent memcpy call. Otherwise,
                      the value 0 (false) is returned.
    
                      Note: Sets srclo and srchi to the address of m, 
                      dstlo and dsthi to the address of the matching segment,
                      and temp0 to n. Does not change the block pointer. 

  blkstr(n ,&s);      Block String Search: Search block for n byte long
                      segments beginning with string s.
                      
                      If a matching segment is found, the value 255 (true)
                      is returned and the segment is copied to the array set 
                      by a prior memdst call. Otherwise, the value 0 (false) 
                      is returned.
    
                      Note: Sets srclo and srchi to the address of the
                      segment, temp0 to n, and copies dstlo and dsthi to
                      temp1 and temp2. Does not change the block pointer. 

  blkswp(n);          Block Swap: Swaps n bytes of array m with the current
                      block segment (pointed to by the block pointer. The
                      block pointer is not changed.
                      
                      Requires a prior call to the memdst function specifying 
                      an array at least n bytes long, which is used for 
                      temporary storage.
    
                      Note: Sets temp0 to n, copies blklo and blkhi to dstlo,
                      and dsthi, and calls memswp.

  blksrt(&m);         Block Sort: Sort segments in block by initial string,
                      using array m as temporary storage.
                      
                      Segments are sorted in alphabetical order, with segment
                      length set by a prior blkseg call, and sorting stops at 
                      the first segment that begins with an empty string (the 
                      first byte is 0), leaving the block pointer at that 
                      segment.
                      
                      Note: Uses the selection sort algorithm. Sets temp1
                      and temp2 to the address of array m.

Note: This library expects the following functions to be defined

  setdst(&s);           Set destination string pointer
  setsrc(&s);           Set source string pointer and initialize index
  memcmp                Compare memory
  memcpy                Copy memory
  memsrc                Set memory source and count
  strcml                Compare string (alternate entry point)

along with the zero page variable pairs
  
  srclo, srchi          Source String Pointer 
  dstlo, dsthi          Destination String Pointer
  blklo, blkhi          Block Pointer

the static variable

  blkslo, blkshi        Block Start Address
  blkelo, blkehi        Block End Address
  blklen                Block Segment Length
  
as well as the transient variables 

  temp0, temp1, temp2   Temporary storage