PRO POINTER_CREATE, POINTER, NPOINTERS=NPOINTERS

;+
; NAME:
;    POINTER_CREATE
;
; PURPOSE:
;    Create a new pointer.
;
;    This routine uses pointers if run under IDL5 or higher,
;    and handles if run under IDL4.
;
; CATEGORY:
;    Pointers
;
; CALLING SEQUENCE:
;    POINTER_CREATE, POINTER
;
; INPUTS:
;    POINTER      Named variable to hold the newly created pointer
;
; OPTIONAL INPUTS:
;    None.
;
; INPUT KEYWORD PARAMETERS:
;    NPOINTERS    If set to a value greater than 1, creates an array of
;                 pointers
;
; OUTPUT KEYWORD PARAMETERS:
;    None.
;
; OUTPUTS:
;    POINTER      Pointer variable which points to an undefined heap variable
;
; OPTIONAL OUTPUTS:
;    None.
;
; COMMON BLOCKS:
;    None.
;
; SIDE EFFECTS:
;    If POINTER is a valid pointer on entry, it is freed, then re-created.
;    This avoids creating dangling references.
;
; RESTRICTIONS:
;    None.
;
;    See also POINTER_FREE, POINTER_VALID, POINTER_VALUE.
;
; EXAMPLE:
;
; ;Create a new pointer
;
; pointer_create, ptr
; help, pointer_valid(ptr)
;
; MODIFICATION HISTORY:
; http://cimss.ssec.wisc.edu/~gumley
; $Id: pointer_create.pro,v 1.10 1999/06/15 15:15:31 gumley Exp $
;-

rcs_id = '$Id: pointer_create.pro,v 1.10 1999/06/15 15:15:31 gumley Exp $'

;- Check arguments

if n_params() ne 1 then message, 'Usage: POINTER_CREATE, POINTER'

;- Check keywords

if n_elements(npointers) eq 0 then npointers = 1
npointers = npointers > 1

;- Check if pointer is defined. If it is defined and valid, free it.

version = long(!version.release)
if n_elements(pointer) gt 0 then begin
  for i = 0, n_elements(pointer) - 1 do begin
    if pointer_valid(pointer(i)) then begin
      case 1 of
        version ge 5 : ptr_free, pointer(i)
        else         : handle_free, pointer(i)
      endcase
    endif
  endfor
endif

;- Create the pointer.

case 1 of
  version ge 5 : pointer = call_function('ptrarr', npointers, /allocate_heap)
  else : begin
    pointer = lonarr(npointers)
    for i = 0, npointers - 1 do begin
      pointer(i) = call_function('handle_create')
    endfor
  end
endcase

END