C02/doc/include/block.txt

Block Memory Functions

This library contains functions and variables 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 typically consists of a string field, which is used as a key, 
followed by a number of mixed type fields. 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 variables are defined:

  int blkbgn;         Start address of the block.
  int blkend;         End address of the block.
  int blklen:         Size of Segments in the block.
  
                      These variables must be assigned before calling
                      any of the functions in this module. They may be
                      reassigned at any time, allowing the program to
                      access different blocks.
                      
                      Note: Although a block usually begins and ends 
                      on a 256 byte boundary, this is not required.
                       
  int blkptr;         Pointer to the next segment. This can be reset
                      to blkbgn using the blkrst() function.
                      
                      To preserve the segment position, this value must
                      be saved before reassigning to another block, then r
                      estored when reassigning back to the original block. 
                      
The following application functions are defined:

                      
  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 pointer to first segment. 
  
                      This routine is called before populating a block with
                      calls to the blkput function.

  blknxt();           Block Next: Moves the block pointer to the bext 
                      segment.

                      If the block pointer is moved past the end of the
                      block, or the segment 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 segment 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