;+
; Add a data container into an ongoing accumulation in a given
; accum_struct structure.
;
; <p>If this is the first item to be "accum"ed, it will also be used as a template,
; stored in accumbuf.template, to be used by <a
; href="dcave.html">dcave</a>.
;
; <p>If the polarization of any items being accumed does not match
; that of template, the polarization of the template is changed to 'I'.
;
; <p>This combines the UniPOPS functionality of ACCUM and SUM.  The SUM
; name is already in use in IDL.
;
; <p>This is primarily for use inside procedures and functions where
; it is useful to average several data containers without disturbing
; the public data containers in the guide structure.  Most users will
; find using <a href="../guide/accum.html">accum</a> preferable to using dcaccum.
;
; @param accumbuf {in}{out}{required}{type=accum_struct}  The
; structure containing the accumulation that you want to add to.
;
; @param dc {in}{requiredl}{type=spectrum} The data container to
; accum.
;
; @keyword weight {in}{optional}{type=float} The weight to use for this
; data.  If this is not set, a weight of exposure/Tsys^2 will be used.
;
; @examples
;    average some data
; <pre>
;   a = {accum_struct}
;   accumclear,a  ; not necessary here, but a good habit to follow
;   ; get several records at once
;   s = !g.lineoutio->get_spectra(index=0)
;   dcaccum,a,s
;   data_free,s ; be sure to clean up, else leaks memory
;   s = !g.lineoutio->get_spectra(index=1)
;   dv = dcvshift, a, s ; align in velocity
;   dcshift, a, dv ; actually do the shift to align
;   dcaccum,a,s
;   data_free, s
;   accumave,a,s
;   show, s
;   data_free, s  
; </pre>
; See <a href="ave.html">ave</a> for additional examples.
;
; @uses <a href="../../devel/toolbox/accumulate.html">accumulate</a>
; @uses <a href="../toolbox/data_valid.html">data_valid</a>
; @uses <a href="../toolbox/data_free.html">data_free</a>
;
; @version $Id: dcaccum.pro,v 1.5 2005/06/02 17:10:43 bgarwood Exp $
;-
pro dcaccum, accumbuf, dc, weight=weight
    compile_opt idl2

    on_error, 2

    if n_params() ne 2 then begin
        message,'Usage: dcaccum, accumbuf, dc[, weight=weight]',/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

    dataOk = data_valid(dc,name=name)
    if dataOk le 0 then begin
        message,'dc is empty or  invalid, can not continue.',/info
        return
    endif
    if name ne 'SPECTRUM' then begin
        message,'data container is not a SPECTRUM, only spectral line data can be accumed currently',/info
        return
    endif

    if (accumbuf.n eq 0) then begin
        data_free, accumbuf.template
        accumbuf.template = dc
        ; now copy the pointer values, making new pointers here
        accumbuf.template.data_ptr = ptr_new(*dc.data_ptr)
    endif else begin
        if dc.polarization ne accumbuf.template.polarization then accumbuf.template.polarization = 'I'
    endelse

    accumulate, accumbuf, *dc.data_ptr, dc.duration, $
                dc.tsys, dc.exposure, dc.frequency_interval, $
                wt=weight
end