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. 

Only one pointer may be active at a time, but it's contents may be saved 
and restored using the following code:

  savelo = ptrlo; savehi = ptrhi; //save current pointer
  ptrlo = savelo; ptrhi = savehi; //restore current pointer
  
where savelo and savehi are an arbitrary pair of variables defined in the
program. 

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. 

In the equivalent C code examples below, the system pointer is represented 
as the variable p. In all cases, assume the following declaration :

  int *p;

Usage: at the beginning of the program use the directives

  #include <pointer.h02>

The following application functions are defined:

  ptrset(&v);         Pointer Set: Set pointer contents to the address of
                      variable v.

                      This is equivalent to the C code 
                      
                        p = &v;
                      
                      Note: Sets variables ptrlo and ptrhi.

  ptrput(b);          Pointer Put: Stores value of b in the byte currently 
                      pointed to and increments the pointer.

                      This is equivalent to the C code 
                      
                        *p = b; p++;
                      
                      Note: Updates variables ptrlo and ptrhi.

  b = ptrget();       Pointer Get: Retrieves the contents of the byte 
                      currently pointed to and increments the pointer.

                      This is equivalent to the C code 
                      
                        b = *p; p++;
                      
                      Note: Updates variables ptrlo and ptrhi.

  ptrinc();           Pointer Increment: Increases the pointer value by 1,
                      causing it to point to the next byte in memory.  

                      This is equivalent to the C code 
                      
                        p++;
                      
                      Note: Updates variables ptrlo and ptrhi.

  ptrdec();           Pointer Decrement: Decreases the pointer value by 1,
                      causing it to point to the previous byte in memory.  

                      This is equivalent to the C code 
                      
                        p++;
                      
                      Note: Updates variables ptrlo and ptrhi.

  ptradd(n);          Pointer Add: Adds the value n to the address contained 
                      in the pointer, moving it that many bytes forward in
                      memory.

                      This is equivalent to the C code 
                      
                        p += n;
                      
                      Note: Updates variables ptrlo and ptrhi.

  ptrsub(n);          Pointer Subtract: Adds the value n to the address 
                      contained in the pointer, moving it that many bytes 
                      backward in memory.

                      This is equivalent to the C code 
                      
                        p -= n;
                      
                      Note: Updates variables ptrlo and ptrhi.

  ptrcmp(&v);         Pointer Compare: Compares pointer contents against
                      the address of variable v.

                      Returns 255 if the pointer is less than the address
                      (pointing to a byte lower in memory), 0 if the pointer
                      is equal to the address (pointing to the same byte),
                      and 1 if greater than tge address (pointing to a 
                      byte higher in memory).
                      These results can be evaluated using the C02 
                      unary comparator ! or the test-operators :+ or :-.

                      This is equivalent to the C code 
                      
                        if (p < &v) return 255;
                        else if (p > &v) return 1;
                        else return 0;
                      
                      Note: Sets variables srclo and srchi.


Note: This library expects the following to be defined: 

the zero page variable pair
  
  ptrlo, ptrhi        System Pointer 

and the transient variable 

  temp0               Temporary storage