;+
; Convenience function for setting data array of a data container.
;
; @param value {in}{required}{type=float} data values to be inserted into the
; data container.  Either a single float value or an array of floats are valid.
; @param elements {in}{optional}{type=long} The data array indices to be 
; changed.  Use one integer to set a single element in the data array.  Use
; a two element array to specify a range to be set.
; @keyword index {in}{optional}{type=integer} The data container index.
; Default = 0.
;
; @examples
; Put the first spectra into !g.s[0], retrieve all its data, and then just the first element
; <pre>
;    filein,'file.fits'
;    getrec,1
;    help, *!g.s[0].data_ptr
;    <PtrHeapVar257> FLOAT     = Array[2048]
;    x = fltarr(1026)
;    setdata, x
;    help, *!g.s[0].data_ptr
;    <PtrHeapVar257> FLOAT     = Array[1026]
;    setdata, 2.5, 0
;    help, (*!g.s[0].data_ptr)[0]
;    <PtrHeapVar257> FLOAT     = 2.5
; </pre>
;
; @uses <a href="../toolbox/getdcdata.html">getdcdata</a>
;
;-
pro setdata, value, elements, index=index 
    compile_opt idl2

    if (n_elements(value) eq 0) then begin
        message,'Usage: setdata, value[, elements][, index=index]',/info
        return
    endif
    ; default - retrieve data from the primary data container
    if n_elements(index) eq 0 then to_index=0 else to_index=index

    if (!g.line) then begin
        if (to_index gt n_elements(!g.s) or to_index lt 0) then begin
            message, string((n_elements(!g.s)-1),format='("index must be >= 0 and <= ",i2)')
            return
        endif
        if (data_valid(!g.s[to_index]) le 0) then begin
            message,'No data at given index',/info
            return
        endif
        if n_elements(elements) ne 0 then begin
            setdcdata,!g.s[to_index], value, elements
        endif else begin
            setdcdata,!g.s[to_index], value
        endelse    
    endif else begin
        if (to_index gt n_elements(!g.c) or to_index lt 0) then begin
            message, string((n_elements(!g.c)-1),format='("index must be >= 0 and <= ",i2)')
            return
        endif
        if (data_valid(!g.c[to_index]) le 0) then begin
            message,'No data at given index',/info
            return
        endif
        if n_elements(elements) ne 0 then begin
            setdcdata,!g.c[to_index], value, elements
        endif else begin
            setdcdata,!g.c[from_index], value
        endelse    
    endelse

    if (to_index eq 0 and not !g.frozen) then show

    return

END