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

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

;+
; 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.
;-

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