source: trunk/SRC/ToBeReviewed/PLOTS/LABEL/label_date.pro

;+
;
; @file_comments
; This function labels axes with dates and times.
;
; @categories
; Plotting
;
; @param AXIS {in}
;
; @param INDEX {in}
;
; @param X {in}
;
; @keyword DATE_FORMAT
; a format string which may contain the following:
; %M for month (3 characters abbr)
; %N for month (2 digits abbr)
; %D for day of month,
; %Y for 4 digits 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).
;
; @keyword MONTHS
; The names of the months, a twelve element string array.
; If omitted, use Jan, Feb, ..., Dec.
;
; @keyword 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.
;
; @uses
;
; @restrictions
; Only one date axis may be simultaneously active.
;
; @examples
;
; For example, to plot from Jan 1, 1993, to July 12, 1994:
;
;   IDL> Start_date = julday(1, 1, 1993)
;   IDL> End_date = julday(7, 12, 1994)
;   IDL> ; Simple mm/dd
;   IDL> Dummy = LABEL_DATE(DATE_FORMAT='%N/%D')
;   IDL> ;Time axis
;   IDL> x = findgen(end_date+1 - start_date) + start_date
;   IDL> ; Plot with X axis style set to exact
;   IDL> PLOT, x, sqrt(x), XTICKFORMAT = 'LABEL_DATE', XSTYLE=1
;
; Example with times:
;
; For example, to plot from 3PM, Jan 1, 1993, to 5AM, Jan 3, 1993:
;
;   IDL> ; Also starting offset
;   IDL> Start_date = Julday(1,1,1993)
;   IDL> ; Starting_time less offset
;   IDL> Start_time = (3+12)/24.
;   IDL> End_time = (Julday(1,3,1993) - Start_date) + 5./24.
;   IDL> ; Ending date/time - offset, note that the order of operations is
;   IDL> ; important to avoid loss of precision
;   IDL> ; MMM NN <new line> HH:MM format
;   IDL> Dummy = LABEL_DATE(DATE_FORMAT='%D %M!C%H:%I', offset=Start_date)
;   IDL> ;Time axis
;   IDL> x = findgen(20) * (End_time - Start_time) / 19 + start_time
;   IDL> PLOT, x, sqrt(x), XTICKFORMAT = 'LABEL_DATE', XSTYLE=1
;
; @history
;     DMS, RSI.     April, 1993.     Written.
;     DMS, RSI.     March, 1997.     Added Time format.
;
; Copyright (c) 1993-1998, Research Systems, Inc.  All rights reserved.
;     Unauthorized reproduction prohibited.
;
; @version
; $Id$
;
;-
FUNCTION label_date, axis, index, x, DATE_FORMAT=format, MONTHS=months $
                   , OFFSET=offs, _EXTRA=ex
;
  compile_opt idl2, strictarrsubs
;
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