Click above to get retro games delivered to your door ever month!

 ptr()               Pointer data type
------------------------------------------------------------------------------
 Syntax
   ptr( <type>[( <width> )] )

 Arguments
   <type> is the data or function type to be referenced by the pointer.
   <width> is an optional width specifier for char data.

 Features
   +----------------------------------------------------------------------+
   | Category             | numeric (integral)                            |
   | Size                 | 4 bytes                                       |
   | Range                | 0 to 4294967295                               |
   | Parameter: value     | yes                                           |
   | Parameter: reference | yes                                           |
   | Parameter: const     | yes                                           |
   | Return               | yes                                           |
   +----------------------------------------------------------------------+

 Description
   The ptr() data type (commonly called as pointer) is a numeric
   entity whose value refers to a specific memory location. The type
   argument of ptr() specifies what type of data is found at the
   memory address where it points to.

   The type of a pointer can not be some of the special data types, like
   file or memo. The width specifier can only be present for pointers for
   the char data type.

   Pointers can be assigned to memory addresses of objects of the respective
   data type by using the & address operator or the addr() library function.
   The target data of a pointer can be accessed after dereferencing with
   the * operator.

   It is essential to initialize a pointer, with the address of a proper
   memory object, before attempting any use of the pointer in question.
   Before initialization the pointer has an accidental value, so it can
   point to any location in the computer's memory. Reading via an
   uninitialized pointer will not result in n a proper value. Writing via an
   uninitialized pointer is likely to cause a system crash, by overwriting
   a random (potentially vital) memory area.

   The ptr( ptr ) type is a special kind of a pointer which can be
   dereferenced to another type of pointer, that is it can be used as a
   pointer to a pointer. Variables declared as ptr( ptr ) can be applied for
   type casting pointers to incompatible types, or for using a ptr() in a
   situation where a specific type is illegal (i. e. to return a pointer to a
   structure from a function). The ptr( ptr ) type provides extra flexibility
   in accessing structured memory objects.

   A pointer to a structure is declared as ptr( <struct> ), where
   <struct> refers to a certain structure type, earlier declared in
   a typedef struct block. The members of structures are referred to using
   the -> (indirect structure member) operator.

   The pointer to structure data type can not be directly returned from
   functions. In such cases, declare the function as returning type
   ptr( ptr ), then assign the returned address value to a ptr( <struct> )
   variable in the caller code, for accessing the members with the ->
   operator.

   The pointer to structure data type can not be associated with the
   value modifier, when passed as a parameter (although in fact it is
   passed by value). This is not to be confused with passing a structure
   itself (not a pointer), which is always done by reference.

   Pointers can refer to code as well as data. Pointers that refer to the
   address of a function or procedure are called function pointers. The
   type of the function must be declared using the ptr keyword. The type
   of a function pointer is checked by the compiler at declaration and
   execution, but not when assigning an address.

   Function pointers are assigned using the & operator or the addr()
   function. The code referred to by a function pointer can be executed
   similarly to direct function calls.

   Pointers to both data and code can generally be used as parameters,
   and be returned from functions, with the above-mentioned exception of
   structure pointers.

 Example
   #define EXAMPLE_DATATYPE
   #include example.hdr

   proc CharStep static
   para value ptr( char ) pTxt
   vardef
      uint n
   enddef
   for n := 1 to 12
      ? *pTxt
      pTxt++
   next
   endproc
   
   func ptr( byte ) StringCopy
   param value ptr( byte ) pDest, value ptr( byte ) pSrc
   // C-like pointer-based string copy function
   do while *pSrc
      *pDest := *pSrc
      pDest++
      pSrc++
   enddo
   *pDest := 0
   return( pDest )
   endfunc
   
   proc TestPtrChar
   vardef
      char        cString
      ptr( byte ) pChar
   enddef
   cString := "hello"
   ? cString
   pChar := &cString + len( cString ) // point to end of string
   StringCopy( pChar, &" world" )     // append second part of string
   ? cString
   ?
   CharStep( &cString )
   endproc
   
   /*
   The example below demonstrates the use of ptr( ptr ) for multiple
   dereferencing, and for masking the ptr( struct ) type.
   */
   
   typedef struct _MONTH // structure to hold
      char( 15 ) cName   // month names and
      uint       nOrder  // their order number
   enddef
   
   vardef static
      // this variable must not be a local, as its address is used
      // accross functions
      _MONTH sMonth
   enddef
   
   func ptr( ptr ) Months
   vardef
      ptr( ptr )    pMonthList
      ptr( ptr )    pTemp
      ptr( _MONTH ) pMonth
      uint          n
   enddef
   // allocate space for storing 13 pointers
   pMonthList := malloc( 13 * sizeof( ptr( ptr ) ) )
   pTemp := pMonthList                     // point to the base of space
   for n := 1 to 12
      pMonth := malloc( sizeof( sMonth ) ) // allocate space for one structure
      pMonth->cName := __monthnames[ n - 1 ] // fill in the allocated
      pMonth->nOrder := n                    // structure using its pointer
      *pTemp := pMonth                       // store the structure pointer
      pTemp += sizeof( ptr( ptr ) )          // point to next pointer
   next
   sMonth.cName := "Nonsense" // fill in a statically allocated structure
   sMonth.nOrder := 13
   *pTemp := &sMonth          // store a pointer to this structure, too
   return( pMonthList ) // return pointer to base of pointers to structures
   endfunc
   
   proc TestPtrPtr
   vardef
      ptr( ptr )    pMonthList
      ptr( char )   pName
      ptr( _MONTH ) pMonth
      uint          n
   enddef
   pMonthList := Months()   // get months in pointer list form
   for n := 1 to 13         // process all "13" months
      pMonth := *pMonthList // dereference the pointer into pointer to struct
      pName  := *pMonthList // ptr( ptr ) can be dereferenced to ptr( char )
      ? pMonth->nOrder, pMonth->cName, *pName // print the data
      if n < 13 // do not attempt to deallocate the non-allocated structure
         free( pMonth ) // free dynamically allocated space for 12 months
      endif
      pMonthList += sizeof( ptr( ptr ) ) // point to next structure pointer
   next
   free( pMonthList )   // free pointer list
   endproc
   
   proc Test_ptr
   TestPtrChar()
   wait
   TestPtrPtr()
   wait
   endproc

   proc main
   Test_ptr()
   endproc