;+
; Get the average from an ongoing accumulation. The dc argument will
; contain the result.
; The contents of the accum buffer are cleared as a 
; consequence of calling ave, unless the noclear keyword is set.
;
; <p>Note: It is a good idea to use <a href="accumclear.html">accumclear</a> 
; to clear the accum buffer before using it the first time so that
; you can be certain it is starting from a cleared (empty) state.
;
; @param accumbuf {in}{out}{required}{type=accum_struct} The
; accumulation buffer to use.
;
; @param dc {out}{required}{type=spectrum} The resulting average.
;
; @keyword noclear {in}{optional}{type=boolean}{default=F} When set, the
; contents of the global accum buffer are not cleared.  This is useful
; when you want to see what the current average is but also plan on
; continuing to add data to that average.  If this is not set, you
; would need to restart the accumulation to average more data.
;
; @keyword quiet {in}{optional}{type=boolean}{default=F} Normally, accumave
; announces how many spectra were averaged.  Setting this turns that
; announcement off.  This is especially useful when multiple accum
; buffers are used within a procedure.
;
; @examples
; <pre>
; a = {accum_struct}
; accumclear, a  ; not necessary here, but good practice
; get,index=1
; dcaccum, a, !g.s[0]
; get,index=2
; dcaccum, a, !g.s[0]
; accumave, a, myavg
; show, myavg
; data_free, myavg ; be sure and clean up when done
; </pre>
;
; <p> Note: the accum_struct structure used here has internal
; pointers.  Use <a href="accumclear.html">sclear</a> to clear them,
; either implicitly (by use of accumave) or explicitly.
;
; @uses <a href="accumclear.html">accumclear</a>
; @uses <a href="data_copy.html">data_copy</a>
;
; @version $Id: accumave.pro,v 1.2 2005/05/19 20:43:56 bgarwood Exp $
;-
pro accumave, accumbuf, dc, noclear=noclear, quiet=quiet
    compile_opt idl2

    on_error, 2

    if n_params() ne 2 then begin
        message,'Usage: accumave, accumbuf, dc[, /noclear]',/info
        return
    endif

    if (size(accumbuf,/type) ne 8 or tag_names(accumbuf,/structure_name) ne "ACCUM_STRUCT") then begin
        message,"accumbuf is not an accum_struct structure",/info
        return
    endif

    if (accumbuf.n ne 0) then begin
        navg = accumbuf.n

        *accumbuf.template.data_ptr = *accumbuf.data_ptr / accumbuf.wt
        accumbuf.template.duration = accumbuf.tint
        accumbuf.template.tsys = sqrt(accumbuf.tsys_sq / accumbuf.wt)
        accumbuf.template.exposure = accumbuf.teff

        data_copy, accumbuf.template, dc

        if (not keyword_set(noclear)) then accumclear, accumbuf

        if not keyword_set(quiet) then message, 'Average of :' + string(navg) + ' spectra',/info
    endif else begin
        message, 'Nothing in the accum buffer, no change in dc argument',/info
    endelse
end