;+
; NAME:
;   GTIENLARGE
;   
;
; AUTHOR:
;   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
;   craigm@lheamail.gsfc.nasa.gov
;
; PURPOSE:
;   Enlarge (or shrink) each Good Time Interval (GTI) by fixed amounts
;
; CALLING SEQUENCE:
;   NEWGTI = GTIENLARGE(GTI, COUNT=COUNT, PRE=PRE, POST=POST)
;
; DESCRIPTION: 
;
;   The function GTIENLARGE accepts an existing valid Good Time
;   Interval (GTI) array and creates a new GTI array in which the
;   intervals have been enlarged (or shrunken) by a fixed amount.
;
;   The keywords PRE and POST are used to specify the enlargement.
;   Given an existing good interval such as this one:
;
;                  100                 200              GTI=[[100,200]]
;      <------------|===================|------------->
;
;   a positive value of PRE will enlarge the lead edge of the interval
;   and a positive value of POST will enlarge the trailing edge of the
;   interval.  Thus PRE=10 and POST=20 will create a new interval from
;   the above example:
;
;               90<--                   --->220      NEWGTI=[[ 90,220]]
;      <---------|==.===================.====|-------->
;             PRE=10                   POST=20
;
;   Negative values of PRE and POST are allowed, which will shrink the
;   interval from the leading and trailing edges respectively.
;
;   Users should be aware that the number of intervals may shrink
;   under this operation, since it is possible either for two
;   intervals to be merged if they are enlarged and overlap, or if
;   they are shrunken to a size of zero.
;
;   It should be noted that this function is not constrained to
;   operation only on time arrays.  It should work on any
;   one-dimensional quantity with intervals.
;
; INPUTS:
;
;   GTI - a 2xNINTERVAL array where NINTERVAL is the number of
;         intervals.  GTI(*,i) represents the start and stop times of
;         interval number i.  The intervals must be non-overlapping
;         and time-ordered (use GTITRIM to achieve this).
;
;         A scalar value of zero indicates that the GTI is empty, ie,
;         there are no good intervals.
;
; KEYWORDS:
;
;   PRE - the amount each interval should be enlarged from its leading
;         edge.  A negative value indicates the interval should
;         shrink.
;         Default: 0
;
;   POST - the amount each interval should be enlarged from its
;          trailing edge.  A negative value indicates the interval
;          should shrink. 
;          Default: 0
;
;   COUNT - upon return, the number of resulting intervals.  A value
;           of zero indicates no good time intervals.
;
; RETURNS:
;
;   A new GTI array containing the enlarged or shrunken intervals.
;   The array is 2xCOUNT where COUNT is the number of resulting
;   intervals.  GTI(*,i) represents the start and stop times of
;   interval number i.  The intervals are non-overlapping and
;   time-ordered. 
;
;   If COUNT is zero then the returned array is a scalar value of
;   zero, indicating no good intervals were found.
;
;
; SEE ALSO:
;
;   GTITRIM, GTIENLARGE
;
; MODIFICATION HISTORY:
;   Written, CM, 1997-2001
;   Documented, CM, Apr 2001
;
;  $Id: gtienlarge.pro,v 1.3 2001/04/30 16:03:03 craigm Exp $
;
;-
; Copyright (C) 1997-2001, Craig Markwardt
; This software is provided as is without any warranty whatsoever.
; Permission to use, copy, modify, and distribute modified or
; unmodified copies is granted, provided this copyright and disclaimer
; are included unchanged.
;-
function gtienlarge, gti, count=count, pre=pre, post=post, query=query

  if keyword_set(query) then return, 1

  ;; When PRE and POST are given, we must be very careful, for the
  ;; GTIs may become overlapping.  That will confuse everything else.
  ;; The strategy I choose here is to look at adjacent GTIs and remove
  ;; any that overlap.  I think that gets everything, but I worry that
  ;; it won't get (say) triply overlapping GTIs.
  count = n_elements(gti)/2
  if count EQ 0 then return, 0L
  if n_elements(pre) EQ 0 AND n_elements(post) EQ 0 then return, gti

  newgti = gti

  if n_elements(pre)  GT 0 then newgti(0,*) = newgti(0,*) - pre(0)
  if n_elements(post) GT 0 then newgti(1,*) = newgti(1,*) + post(0)

  wh = where(newgti(1,*) GT newgti(0,*), count)
  if count EQ 0 then return, 0

  ;; If only one GTI entry, then no need for special treatment
  if count EQ 1 then return, reform(newgti(*, wh), 2, 1)

  newgti = newgti(*,wh)
  
  ;; Get first and last GTI values
  t0 = newgti(0)
  t1 = newgti(count*2-1)
  ;; Get possibly "overlapping" values
  vgti = reform(newgti(1:count*2-2), 2, count-1)
  ;; Make sure they *don't* overlap
  wh = where(vgti(1,*) GT vgti(0,*), ct)
  
  if ct GT 0 then begin
      count = ct + 1
      newgti = reform([t0, (vgti(*,wh))(*), t1], 2, count)
  endif else begin
      count = 1L
      newgti = reform([t0, t1], 2, 1)
  endelse

  return, newgti
end