;+
; Function to return the value of a specific element of the stack.
;
; @param elem {in}{required}{type=long integer} The index of
; the element to return.
;
; @returns -1 on error (out of limits), a warning message also
; appears.
; @examples
; <pre>
;    ; stack contains [ 10,  12,  14,  20,  25, 28] to begin
;    my_elem = astack(3)
;    ; my_elem contains the value 20
; </pre>
;
; @version $Id: astack.pro,v 1.4 2005/05/29 22:44:15 bgarwood Exp $
;-
function astack, elem
    compile_opt idl2

    if n_elements(elem) eq 0 then begin
       message, 'Usage: addstack(elem)',/info
       return, -1
    endif
    if (elem lt 0 or elem ge !g.acount) then begin
        message, 'elem is out of bounds', /info
        result = -1
    endif else begin
        result = (*!g.astack)[elem]
    endelse

    return, result
end