As illustrated above, you must use a special IDL routine to create a pointer to a heap variable. Two routines are available: PTR_NEW and PTRARR. Before discussing these functions, however, it is useful to examine the concept of a null pointer.

Null Pointers

The Null Pointer is a special pointer value that is guaranteed to never point at a valid heap variable. It is used by IDL to initialize pointer variables when no other initializing value is present. It is also a convenient value to use at the end nodes in data structures such as trees and linked lists.

It is important to understand the difference between a null pointer and a pointer to an undefined or invalid heap variable. The second case is a valid pointer to a heap variable that does not currently contain a usable value. To make the difference clear, consider the following IDL statements:

;The variable A contains a null pointer.
A = PTR_NEW()
;The variable B contains a pointer to a heap variable with an 
;undefined value.
B = PTR_NEW(/ALLOCATE_HEAP)
 
HELP, A, B, *B

IDL prints:

A               POINTER  = <NullPointer>
B               POINTER  = <PtrHeapVar1>
<PtrHeapVar1>   UNDEFINED = <Undefined>

The primary difference is that it is possible to write a useful value into a pointer to an undefined variable, but this is never possible with a null pointer. For example, attempt to assign the value 34 to the null pointer:

*A = 34

IDL prints:

% Unable to dereference NULL pointer: A.
% Execution halted at:  $MAIN$

Assign the value 34 to a previously-undefined heap variable:

*B = 34
PRINT, *B

IDL prints:

      34

Similarly, the null pointer is not the same thing as the result of PTR_NEW(0). PTR_NEW(0) returns a pointer to a heap variable that has been initialized with the integer value 0.

The PTR_NEW Function

Use the PTR_NEW function to create a single pointer to a new heap variable. If you supply an argument, the newly-created heap variable is set to the value of the argument. For example, the command:

ptr1 = PTR_NEW(FINDGEN(10))

creates a new heap variable that contains the ten-element floating point array created by FINDGEN, and places a pointer to this heap variable in ptr1.

Note that the argument to PTR_NEW can be of any IDL data type, and can include any IDL expression, including calls to PTR_NEW itself. For example, the command:

ptr2 = PTR_NEW({name:'', next:PTR_NEW()})

creates a pointer to a heap variable that contains an anonymous structure with two fields: the first field is a string, the second is a pointer. We will develop this idea further in the examples at the end of this section.

If you do not supply an argument, the newly-created pointer will be a null pointer. To create a new heap variable but do not wish to initialize it, use the ALLOCATE_HEAP keyword.

See PTR_NEW for further details.

The PTRARR Function

Use the PTRARR function to create an array of pointers of up to eight dimensions. By default, every element of the array created by PTRARR is set to the null pointer. For example:

;Create a 2 by 2 array of null pointers.
ptarray = PTRARR(2,2)
 
;Display the contents of the ptarray variable, and of the first 
;array element.
HELP, ptarray, ptarray(0,0)

IDL prints:

PTARR           POINTER   = Array(2, 2)
<Expression>    POINTER   = <NullPointer>

To have each element of the array to point to a new heap variable (as opposed to being a null pointer), use the ALLOCATE_HEAP keyword. Note that in either case, you will need to initialize the array with another IDL statement.

See PTRARR for further details.