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 <stddef.h02>
  #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 ends on a 256 byte
                      boundary, this is not required.
                      
                      Note: Sets variables blkelo and blkehi.

  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: Fills entire block with character c,
                      leaving block pointer at end of block.
  
                      Should be called with an argument of 0, to initialize
                      a block before use.

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

  blkptr(&d);         Block Pointer: Sets the block pointer to the address 
                      of b. 

                      Does not validate that the address is within the
                      beginning and ending address of the block.
                      
                      Note: Sets variables blkslo and blkshi.
                      
  blknxt();           Block Next: Moves 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, or the segmebt length is set to 0, a value of 
                      #TRUE is returned. Otherwise, a value of #FALSE is 
                      returned.
                      
  blkprv();           Block Previous: Moves block pointer backward by the 
                      segment length set by a prior blkseg call.

                      If the block pointer is moved past the beginning of 
                      the block, or the segmebt length is set to 0, a value  
                      of #TRUE is returned. Otherwise, a value of #FALSE is 
                      returned.
                      
  blkput(n ,&m);      Block Put: Copies n bytes of array m to a block at the
                      current pointer location, and moves block the 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 #FALSE is
                      returned. Otherwise, the bytes are copied and a value
                      of #TRUE is returned.
                      
                      Note: Sets dstlo and dsthi to blklo and blkhi prior
                      to the copy, updates blklo and blkhi, then calls
                      the memcpy function.
                      
  blkget(n ,&m);      Block Get: Copies n bytes from a block at the current 
                      pointer location to array m, and moves the 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 #FALSE is
                      returned. Otherwise, the bytes are copied and a value
                      of #TRUE is returned.
                      
                      Note: Sets dstlo and dsthi to the address of m, 
                      srclo and srchi to blklo and blkhi prior to the 
                      copy, updates blkslo and blkshi, then calls the 
                      memcpy function.
                      
  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.

  blkmem(n ,&m);      Block Memory search: Search block for n byte long
                      segment matching array m. 
                      
                      If a matching segment is found, the value #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 #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. 

  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.

  blkdst();           Block Destination: Sets the destination pointer to the
                      block segment pointer.

                      This is a utility function called by other functions in
                      this module.

                      Note: Sets dstlo and dsthi to blklo and blkhi.

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