IDL

PTR_NEW

PTR_NEW

The PTR_NEW function provides the primary mechanism for creating heap variables.

Syntax


Result = PTR_NEW( [InitExpr] [, /ALLOCATE_HEAP] [, /NO_COPY] )

Return Value


It returns a pointer to the created variable.

Arguments


InitExpr

If InitExpr is provided, PTR_NEW uses it to initialize the newly created heap variable. Note that the new heap variable does not point at the InitExpr variable in any sense—the new heap variable simply contains a copy of its value.

If InitExpr is not provided, PTR_NEW does not create a new heap variable, and returns the Null Pointer, a special pointer with a fixed known value that can never point at a heap variable. The null pointer is useful as a terminator in dynamic data structures, or as a placeholder in structure definitions.

Keywords


ALLOCATE_HEAP

Set this keyword to cause PTR_NEW to allocate an undefined heap variable rather than return a null pointer when InitExpr is not specified.

NO_COPY

Usually, when the InitExpr argument is provided, PTR_NEW allocates additional memory to make a copy. If the NO_COPY keyword is set, the value data is taken away from the InitExpr variable and attached directly to the heap variable. This feature can be used to move data very efficiently. However, it has the side effect of causing the InitExpr variable to become undefined.

Using the NO_COPY keyword is completely equivalent to the statement:

Result = PTR_NEW(TEMPORARY(InitExpr))

and is provided as a syntactic convenience.

Version History


5.0

Introduced

See Also


PTR_FREE, PTR_VALID, PTRARR



Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions