;+
; Project     : SOHO - CDS
;
; Name        : BOOST_TAG
;
; Category    : Utility
;
; Purpose     :	boost a tag value
;
; Explanation :	Useful for updating history tags in structures
;
; Syntax      : IDL> new_struct=boost_tag(struct,value,tag_name)
;
; Inputs      : STRUCT = structure to modify
;               VALUE  = value to boost current value
;               TAG_NAME = tag name to boost
;
; Opt. Inputs : None
;
; Outputs     : NEW_STRUCT = modified structure
;
; Opt. Outputs: None
;
; Keywords    : ERR = error string
;               NAME = optional new name for output structure
;               QUIET = don't echo messages
;               RECURSE = recursively search for tag name
;
; Common      : None
;
; Restrictions: None
;
; Side effects: None
;
; History     : Version 1,  13-April-1997,  D.M. Zarro.  Written
;
; Contact     : DZARRO@SOLAR.STANFORD.EDU
;-

function boost_tag,struct,tag_value,tag_name,name=name,err=err,$
                       quiet=quiet,recurse=recurse

on_error,1
err=''

verbose=1-keyword_set(quiet)
recurse=keyword_set(recurse)

if (datatype(struct) ne 'STC') or (n_elements(tag_value) eq 0) or $
   (n_elements(tag_name) eq 0) then begin
 pr_syntax,'new_struct=boost_tag(struct,tag_value,tag_name)'
 if exist(struct) then return,struct else return,0
endif

if n_elements(tag_name) ne 1 then begin
 message,'restricted to boosting one tag at a time',/cont
 if exist(struct) then return,struct else return,0
endif

;- do recursive search 

tags=tag_names(struct) & ntags=n_elements(tags)
if datatype(tag_name) eq 'STR' then begin
 tag_index=(where(strupcase(tag_name) eq tags,cnt))(0)
 if (cnt eq 0) then begin
  if recurse then begin
   for k=0,ntags-1 do begin
    if datatype(struct.(k)) eq 'STC' then begin
     tstruct=boost_tag(struct.(k),tag_value,tag_name,err=err,/quiet)
     if err eq '' then begin
      new_struct=rep_tag_value(struct,tstruct,tags(k),name=name)
      return,new_struct
     endif
    endif
   endfor
  endif
;  err='tag name < '+tag_name+' > not found'
;  if verbose then message,err,/cont
  return,add_tag(struct,tag_value,tag_name,name=name)
;  if exist(struct) then return,struct else return,0
 endif else str_tag_name=tag_name
endif else begin
 tag_index=tag_name 
 if (tag_index lt 0) or (tag_index gt (ntags-1)) then begin
  err='index out of range'
  if verbose then message,err,/cont
  return,struct
 endif
 str_tag_name=tags(tag_index)
endelse

for k=0,n_elements(struct)-1 do begin

;-- some checks first

 old_value=struct(k).(tag_index)
 if datatype(old_value) ne datatype(tag_value) then begin
  if (datatype(old_value,2) gt 5) or (datatype(tag_value,2) gt 5) then begin
   err='New tag value must be of same type as old value'
   if verbose then message,err,/cont
   return,struct
  endif
 endif

 if datatype(old_value) eq 'STC' then begin
  err='Cannot operate on a structured tag'
  if verbose then message,err,/cont
  return,struct
 endif

;-- replace here

; boost_array,old_value,tag_value
 new_value=[old_value,tag_value]
 err=''
 temp_struct=rep_tag_value(struct(k),new_value,str_tag_name,err=err)
 if err ne '' then temp_struct=struct(k) 
 new_struct=merge_struct(new_struct,temp_struct)
endfor

new_struct=rep_struct_name(new_struct,name)
delvarx,temp_struct

return,new_struct & end