PTR_VALID
The PTR_VALID function verifies the validity of its pointer arguments, or alternatively returns a vector of pointers to all the existing valid pointer heap variables.
Examples
To determine if a given pointer refers to a valid heap variable:
IF (PTR_VALID(p)) THEN …
To destroy all existing pointer heap variables:
PTR_FREE, PTR_VALID()
You can use the CAST keyword to “reclaim” lost heap variables. For example:
A = PTR_NEW(10)
PRINT, A
IDL prints:
<PtrHeapVar2>
In this case, the integer index to the heap variable is 2. If we reassign the variable A, we will “lose” the pointer, but the heap variable will still exist:
A=0
PRINT, A
PRINT, PTR_VALID()
IDL prints:
0
<PtrHeapVar2>
We can reclaim the lost heap variable using the CAST keyword:
A = PTR_VALID(2, /CAST)
PRINT, A
IDL prints:
<PtrHeapVar2>
Syntax
Result = PTR_VALID( [Arg] [, /CAST] [, COUNT=variable] [, /GET_HEAP_IDENTIFIER] )
Return Value
If called with a pointer or array of pointers as its argument, PTR_VALID returns a byte array of the same size as the argument. Each element of the result is set to True (1) if the corresponding pointer in the argument refers to an existing valid heap variable, or to False (0) otherwise. If the GET_HEAP_IDENTIFIER keyword is set, PTR_VALID returns the heap identifier value(s) for the input pointer(s).
If called with an integer or array of integers as its argument and the CAST keyword is set, PTR_VALID returns an array of pointers. Each element of the result is a pointer to the heap variable indexed by the integer value. Integers used to index heap variables are shown in the output of the HELP and PRINT commands. This is useful primarily in programming/debugging when you have lost a reference but see it with HELP and need to get a reference to it interactively in order to determine what it is and take steps to fix the code. See the “Examples” section below for an example.
If no argument is specified, PTR_VALID returns a vector of pointers to all existing valid pointer heap variables—even if there are currently no pointers to the heap variable. This usage allows you to “reclaim” pointer heap variables to which all pointers have been lost. If no valid pointer heap variables exist, a scalar null pointer is returned.
Arguments
Arg
Arg can be one of the following:
- A scalar or array argument of pointer type.
- If the CAST keyword is set, an integer index or array of integer indices to heap variables. Integers used to index heap variables are shown in the output of the HELP and PRINT commands.
Keywords
CAST
Set this keyword to create a new pointer to each heap variable index specified in Arg.
COUNT
Set this keyword equal to a named variable that will contain the number of currently valid heap variables. This value is returned as a longword integer.
GET_HEAP_IDENTIFIER
If Arg is a pointer or array of pointers, set this keyword to return the pointer heap identifier value(s) instead of the default array of True or False values. The value(s) will be unsigned long integers, and the return value will have the same dimensions as Arg.
Version History
|
5.0 |
Introduced |
|
8.0 |
Added GET_HEAP_IDENTIFIER keyword |