OBJ_VALID

The OBJ_VALID function verifies the validity of its argument object references, or alternatively returns a vector of references to all the existing valid objects.

If called with an argument, OBJ_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 object reference in the argument refers to an existing object, and False (0) otherwise.

If called with an integer or array of integers as its argument and the CAST keyword is set, OBJ_VALID returns an array of object references. Each element of the result is a reference 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 the 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, OBJ_VALID returns a vector of references to all existing valid objects. If no valid objects exist, a scalar null object reference is returned.

Calling Sequence

Result = OBJ_VALID([ Arg ])

Arguments

Arg

Scalar or array argument of object reference type.

Keywords

CAST

Set this keyword equal to an integer that indexes a heap variable to create a new pointer to that heap variable. 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 the 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.

COUNT

Set this keyword equal to a named variable that will contain the number of currently valid objects. This value is returned as a longword integer.

Examples

To determine if a given object reference refers to a valid heap variable

IF (OBJ_VALID(obj)) THEN ...

To destroy all existing pointer heap variables:

OBJ_DESTROY, OBJ_VALID()

You can use the CAST keyword to "reclaim" lost object references. For example:

junk = {junk, data1:0, data2:0.0} ; Create a class structure.

A = OBJ_NEW('junk') ; Create an object.

PRINT, A Find the integer index.

IDL prints:

<ObjHeapVar3(JUNK)>

In this case, the integer index to the heap variable is 3. If we reassign the variable A, we will "lose" the object reference, but the heap variable will still exist:

A = 0 ; Lose the object reference.

PRINT, A, OBJ_VALID()

IDL prints:

0 <ObjHeapVar3(JUNK)>

We can reclaim the lost heap variable using the CAST keyword:

A = OBJ_VALID(3, /CAST) ; Reclaim the reference.

PRINT, A

IDL prints:

<ObjHeapVar3(JUNK)>