; $Id$
;
; Copyright (c) 1993-1998, Research Systems, Inc.  All rights reserved.
;	Unauthorized reproduction prohibited.

FUNCTION LABEL_DATE, axis, index, x, DATE_FORMAT = format, MONTHS = months, $
              OFFSET= offs, _EXTRA = ex
;+
; NAME:
;	LABEL_DATE
;
; PURPOSE:
;	This function labels axes with dates and times.
;
; CATEGORY:
;	Plotting.
;
; CALLING SEQUENCE:
;	To set up:
;		dummy = LABEL_DATE(DATE_FORMAT='string')
;	To use:
;		PLOT, x, y, XTICKFORMAT='LABEL_DATE'
;
; INPUTS:
;	No explicit user defined inputs. When called from the plotting
;	routines, the input parameters are (Axis, Index, Value)
;
; KEYWORD PARAMETERS:
;	DATE_FORMAT: a format string which may contain the following:
;		       %M for month (3 character abbr)
;		       %N for month (2 digit abbr)
;		       %D for day of month,
;		       %Y for 4 digit year.
;		       %Z for last two digits of year.
;	     For time:
;		       %H for Hours, 2 digits.
;		       %I for mInutes, 2 digits.
;		       %S for Seconds, 2 digits.
;		       %% is %.
;		     Other characters are passed directly thru.
;		     For example, '%M %D, %Y' prints DEC 11, 1993
;		       '%M %2Y' yields DEC 93
;		       '%D-%M' yields 11-DEC
;		       '%D/%N/%Y' yields 11/12/1993
;		       '%M!C%Y' yields DEC on the top line, 1993 on
;		       the bottom (!C is the new line graphic command).
;
;	MONTHS:      The names of the months, a twelve element string array.
;		     If omitted, use Jan, Feb, ..., Dec.
;
;	OFFSET:	     An optional starting offset of the plot.
;		Unfortunately, single precision floating point is not accurate
;		enough to properly represent Julian times.  This offset, which
;		may be double precision, contains an offset that is added to
;		all x values, before conversion to Julian date and time.

; OUTPUTS:
;	The date string to be plotted.
;
; COMMON BLOCKS:
;	LABEL_DATE_COM.
;
; RESTRICTIONS:
;	Only one date axis may be simultaneously active.
;
; PROCEDURE:
;	Straightforward.
;
;       For an alternative way to label a plot axis with dates, refer to
;       the C() format code accepted within format strings (applicable via
;       the [XYZ]TICKFORMAT keywords).  This new format code was 
;       introduced in IDL 5.2.
;
; EXAMPLE:
;	For example, to plot from Jan 1, 1993, to July 12, 1994:
;	  Start_date = julday(1, 1, 1993)
;	  End_date = julday(7, 12, 1994)
;	  Dummy = LABEL_DATE(DATE_FORMAT='%N/%D')  ;Simple mm/dd
;	  x = findgen(end_date+1 - start_date) + start_date ;Time axis
;	  PLOT, x, sqrt(x), XTICKFORMAT = 'LABEL_DATE', XSTYLE=1
;	  (Plot with X axis style set to exact.)
;	
; Example with times:
;	For example, to plot from 3PM, Jan 1, 1993, to 5AM, Jan 3,
;	1993:
;	Start_date = Julday(1,1,1993)   ;Also starting offset
;	Start_time = (3+12)/24.         ;Starting_time less offset
;	End_time = (Julday(1,3,1993) - Start_date) + 5./24. ;Ending
;       	;date/time - offset, note that the order of operations is
;               ; important to avoid loss of precision.
;	Dummy = LABEL_DATE(DATE_FORMAT='%D %M!C%H:%I', $
;		offset=Start_date)       ;MMM NN <new line> HH:MM format
;	x = findgen(20) * (End_time - Start_time) / 19 + start_time ;Time axis
;	PLOT, x, sqrt(x), XTICKFORMAT = 'LABEL_DATE', XSTYLE=1
;
; MODIFICATION HISTORY:
;	DMS, RSI.	April, 1993.	Written.
;	DMS, RSI.	March, 1997.	Added Time format.
;-

COMMON label_date_com, fmt, month_chr, offset

if keyword_set(format) then begin ;Save format string?
    if n_elements(offs) ne 0 then offset = double(offs) else offset = 0.0d0
    if keyword_set(months) then month_chr = months $
    else month_chr = ['Jan','Feb','Mar', 'Apr', 'May', 'Jun', 'Jul', $
                      'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
    fmt = format
    return, 0
endif

if n_elements(month_chr) ne 12 or n_elements(fmt) le 0 $
  or n_elements(offset) eq 0 then $
  message,' Not initialized.'

x1 = x + offset
caldat, long(x1), month, day, year, _EXTRA = ex;Get the calendar date from julian
frac = x1 - long(x1)            ;time of day, from 0 to 1.

n = strlen(fmt)
out = ''

for i=0, n-1 do begin           ;Each format character...
    c = strmid(fmt, i, 1)       ;The character.
    if c eq '%' then begin
        i = i + 1
        c = strmid(fmt, i, 1)   ;The function
        case c of		;format character?
            'M' : out = out + month_chr[month-1]
            'N' : out = out + string(format='(i2.2)', month)
            'D' : out = out + string(format='(i2.2)', day)
            'Y' : out = out + string(format='(i4)', year)
            'Z' : out = out + string(format='(i2.2)', year  mod 100)
            'H' : out = out + string(format='(i2.2)', floor(24*frac))
            'I' : out = out + string(format='(i2.2)', floor(1440 * frac mod 60))
            'S' : out = out + string(format='(i2.2)', 86400L * frac mod 60)
            '%' : out = out + '%'
            else : message, 'Illegal character in date format string: '+fmt
        endcase
    endif else out = out + c
endfor
return, out
end