C02/doc/pointer.txt

Pointer Functions

This library contains functions for basic pointer access and manipulation.

These functions are intended to allow sequential reading and writing of
individual bytes to arbitrary locations in memory. 

A pointer consists of any two consecutive bytes in Zero Page and is 
referenced using the single byte zeto page address (0-254).

Note: There is no concept of a null pointer in C02. A pointer containing
the value 0 simply points to the first byte of memory. 

Usage: at the beginning of the program use the directives

  #include <pointer.h02>

The following application functions are defined:

  ptr, msb, lsb =       Pointer Set: Set the contents of the pointer at
    ptrset(zp, &addr);  location zp to the address &addr.
    
                        Returns the zsro-page pointer location, address
                        high byte, and address low byte.

  ptr, msb, lsb =       Pointer Address: Retrieves the contents of the 
    ptradr(zp);         pointer at location zp.
    
                        Returns the zsro-page pointer location, address
                        high byte, and address low byte.

  ptr, b =              Pointer Put: Stores byte of b at the address 
    ptrput(zp, b);      pointed to by the pointer at location zp, then
                        increments the pointer contents.

                        Returns the zsro-page pointer location and value
                        written to address.

  b = ptrget(zp);       Pointer Get: Retrieves the contents of the byte 
                        at the address pointed to by the pointer at 
                        location zp, then increments the pointer contents.

  ptrinc(zp);           Pointer Increment: Increases the contents of the
                        pointer at location zp by one.

  ptrdec(zp);           Pointer Decrement: Decreases the contents of the
                        pointer at location zp by one.

  ptr, msb, lsb =       Pointer Add: Adds the 16-bit value specified by &addr 
    ptradd(zp, &addr);  or msb, lsb to the contents of the pointer at 
    ptradd(zp,msb,lsb); location zp.

  ptr, msb, lsb =       Pointer Add: Subtracts the 16-bit value specified by  
    ptrsub(zp, &addr);  &addr or msb, lsb to the contents of the pointer at 
    ptrsub(zp,msb,lsb); location zp.

  r =                   Pointer Compare: Compares the contents of the pointer
    ptrcmp(zp, &addr);  at location zp to the address &addr.

                        Returns 255 if the contents are less than the address
                        (pointing to a byte lower in memory), 0 if the contents
                        are equal to the address (pointing to the same byte),
                        and 1 if the contents are greater than the address 
                        (pointing to a byte higher in memory).

                        These results can be evaluated using the C02 unary
                        comparator ! or the test-operators :+ or :-.

Note: This library expects the following to be defined: 

the transient variables  

  temp0, temp1, temp2   Temporary storage