;+
; NAME:
;	TimeLimits
; PURPOSE:
;	Extract information about a array of times
; CATEGORY:
;	Tell time
; CALLING SEQUENCE:
	FUNCTION TimeLimits, T, unit, $
		mint	= mint	, $
		maxt	= maxt	, $
		bounds	= bounds, $
		range	= range	, $
		mid		= mid	, $
		t0		= t0
; INPUTS:
;	T			array; type: time structure
;					times to be processed
; OPTIONAL INPUT PARAMETERS:
;	unit		scalar; type: integer
;					If'unit' is not specified all times are returned
;					as a time structure
;					If 'unit' ist specified then times are returned
;					as a difference from T[0] in units of 'unit'.
;
;	/mint		return earliest time
;	/maxt		return latest time
;	/mid		return center time
;	/bounds		return earliest and latest time
;					(earliest time = R[0], latest time = R[1])
;					This is the default if no keyword is specified.
;	/range		(use only with chronological or reverse
;				chronological arrays, SEE RESTRICTIONS)
;				return earliest and latest time,
;					The pair of times is returned in the
;					same order as they occur in the input array T,
;					e.g. if the array is in reverse chronological order
;					than R[0] is the latest, and R[1] the earliest time.
;					(this keyword is primarily use in plotting routines
;					to reverse the time axis).
; OUTPUTS:
;	R			array[1], array[2]; type: time structure of float
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
; CALLS:
;	IsType, InitVar, TimeUnit, TimeOp
; RESTRICTIONS:
;	If the min and max time is required for an input array T  that is
;	not (reverse) chronological the /range keyword can produce unexpected
;	results (the minimum time may end up in R[1], not R[0]).
;	Use trange = TimeLimits(T,/bounds) if you need to be sure
;	that the minimum time is R[0] and the maximum time R[1].
; PROCEDURE:
;	R = TimeLimits(T, /mint  [, unit])
;	R = TimeLimits(T, /maxt  [, unit])
;	R = TimeLimits(T, /mid   [, unit])
;	R = TimeLimits(T, /bounds[, unit])
;	R = TimeLimits(T, /range [, unit])
; MODIFICATION HISTORY:
;	NOV-1999, Paul Hick (UCSD/CASS)
;	SEP-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added /bounds keyword
;-

urange = IsType(unit,/defined)
InitVar, unit, TimeUnit(/days)

InitVar, mint  , /key
InitVar, maxt  , /key
InitVar, mid   , /key
InitVar, range , /key
InitVar, bounds, /key

InitVar, t0, T[0]
TT = TimeOp(/subtract,T,t0,unit)

IF NOT maxt THEN ttmin = min(TT, imin)
IF NOT mint THEN ttmax = max(TT, imax)

CASE 1 OF
mint  : IF urange THEN TT = ttmin ELSE TT = T[imin]
maxt  : IF urange THEN TT = ttmax ELSE TT = T[imax]
bounds: IF urange THEN TT = [ttmin,ttmax] ELSE TT = [T[imin],T[imax]]
mid   : IF urange THEN TT = mean([ttmin,ttmax]) ELSE TT = TimeOp(/meant, T[imin], T[imax])
range : BEGIN
	CASE urange OF
	0: IF imin LE imax THEN TT = [T[imin],T[imax]] ELSE TT = [T[imax],T[imin]]
	1: IF imin LE imax THEN TT = [ttmin  ,ttmax  ] ELSE TT = [ttmax  ,ttmin  ]
	ENDCASE
END
ELSE: IF urange THEN TT = [ttmin,ttmax] ELSE TT = [T[imin],T[imax]]
ENDCASE

RETURN, TT  &  END