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

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

;+
;
; @file_comments
; This function labels axes with dates and times.
;
; @categories
; Plotting
;
; @param AXIS {in}{required}
;
; @param INDEX {in}{required}
;
; @param X {in}{required}
;
; @keyword 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).
;
; @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
; LABEL_DATE_COM.
;
; @restrictions
; Only one date axis may be simultaneously active.
;
; @examples
; 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
;
; @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