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 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