; docformat = 'rst'
;
; NAME:
;   cgTimeStamp
;
; PURPOSE:
;   This is a utility program to obtain a time stamp string suitable
;   for using in a filename or some other string.
;
;******************************************************************************************;
;                                                                                          ;
;  Copyright (c) 2013, by Fanning Software Consulting, Inc. All rights reserved.           ;
;                                                                                          ;
;  Redistribution and use in source and binary forms, with or without                      ;
;  modification, are permitted provided that the following conditions are met:             ;
;                                                                                          ;
;      * Redistributions of source code must retain the above copyright                    ;
;        notice, this list of conditions and the following disclaimer.                     ;
;      * Redistributions in binary form must reproduce the above copyright                 ;
;        notice, this list of conditions and the following disclaimer in the               ;
;        documentation and/or other materials provided with the distribution.              ;
;      * Neither the name of Fanning Software Consulting, Inc. nor the names of its        ;
;        contributors may be used to endorse or promote products derived from this         ;
;        software without specific prior written permission.                               ;
;                                                                                          ;
;  THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY        ;
;  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES    ;
;  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT     ;
;  SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,             ;
;  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    ;
;  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;         ;
;  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND             ;
;  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              ;
;  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS           ;
;  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                            ;
;******************************************************************************************;
;
;+
; This is a utility program to obtain a time stamp string suitable
; for using in a filename or some other string.
;
; :Categories:
;    Utilities
;    
; :Returns:
;    A string variable containing the time stamp is returned from the function.
;    
; :Params:
;    format: in, optional, type=integer, default=0
;       An integer value that selects the time stamp format. Default is 0. Possible values are::
;          0: _sun_feb_07_10:56:37_2010
;          1: _Sun_Feb_07_10:56:37_2010
;          2: _07_02_2010_10:56:37
;          3: _07022010_10:56:37
;          4: _07022010
;          5: _07Feb2010_10:56:37
;          6: _07feb2010_10:56:37
;          7: _07FEB2010_10:56:37
;          8: _02_07_2010_10:56:37
;          9: _02072010_10:56:37
;          10: _02072010
;          11: _20100207@10:56:37
;       
; :Keywords:
;    no_prefix: in, optional, type=boolean, default=0
;         Set this keyword to remove the underscore prefix normally present at the start of the time stamp.
;    random_digits: in, optional, type=integer
;         Set this keyword to the number of random digits you would like to append to the time stamp.
;    utc: in, optional, type=boolean, default=0
;         Set this keyword to use UTC time in the time stamp, rather than the local time.
;    valid: in, optional, type=boolean, default=0
;         If this keyword is set, the time stamp is passed through the IDL program IDL_VALIDNAME, and 
;         all characters that are not allowed in IDL variable names are replaced by ones that are allowed. 
;         In other words, a character like ":", which is not allowed, is turned into the character "_", which
;         is allowed.
;    
; :Examples:
;    Here is how to use this program::
;       IDL> filename = 'mydatafile' + cgTimeStamp() + '.dat'
;       
; :Author:
;    FANNING SOFTWARE CONSULTING::
;       David W. Fanning 
;       1645 Sheely Drive
;       Fort Collins, CO 80526 USA
;       Phone: 970-221-0438
;       E-mail: david@idlcoyote.com
;       Coyote's Guide to IDL Programming: http://www.idlcoyote.com
;
; :History:
;     Change History::
;       Written by David W. Fanning, 7 February 2010.
;       Added format number 11: YYYYMMDD@HH:MM:SS so that when files are created they
;          will list in descending time order. Matt Savoie suggestion. DWF. 10 Sept 2010.
;       Added NO_PREFIX keyword that, if set, will prevent an underscore character from being
;          added to the time stamp. 10 Sept 2010. DWF.
;       Discovered that Windows and UNIX computers report the UTC time differently, resulting
;          in the day string being a one digit integer on UNIX and a two digit integer on
;          Windows. Fixed so the day string is always forced to be two digits. 8 October 2010.
;       Renamed from TimeStamp to cgTimeStamp to avoid conflict with IDL's own TimeStamp function
;          introduced in IDL 8.2.2. 6 February 2013. DWF.
;
; :Copyright:
;     Copyright (c) 2010-2013, Fanning Software Consulting, Inc.
;-
FUNCTION cgTimeStamp, format, $
    No_Prefix=no_prefix, $
    Random_Digits=random_digits, $
    UTC=utc, $
    Valid=valid

    On_Error, 2

    ; Set keyword values.
    no_prefix = Keyword_Set(no_prefix)
    IF N_Elements(format) EQ 0 THEN format = 0
    IF N_Elements(random_digits) GT 0  THEN BEGIN
        DEFSYSV, '!FSC_RandomNumbers', EXISTS=exists
        IF exists THEN BEGIN
            randomNumber = !FSC_RandomNumbers -> GetRandomDigits(random_digits)
        ENDIF ELSE BEGIN
            DEFSYSV, '!FSC_RandomNumbers', Obj_New('RandomNumberGenerator')
            randomNumber = !FSC_RandomNumbers -> GetRandomDigits(random_digits)
        ENDELSE
    ENDIF
    
    ; Get some values for the current time.
    time = Systime(UTC=Keyword_Set(utc))
    day = Strmid(time, 0, 3)
    date = String(StrMid(time, 8, 2), Format='(I2.2)') ; Required because UNIX and Windows differ in time format.
    month = Strmid(time, 4, 3)
    year = Strmid(time, 20, 4)
    stamp = Strmid(time, 11, 8)
    months = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC']
    m = (Where(months EQ StrUpCase(month))) + 1
   
    ; Select the time stamp format.
    CASE format OF
        1:  timeStamp = day + '_' +month + '_' + date + '_' + stamp + '_' + year
        2:  timestamp = date + '_' + String(m, FORMAT='(I2.2)') + '_' + year + '_' + stamp
        3:  timestamp = date + String(m, FORMAT='(I2.2)') + year + '_' + stamp
        4:  timestamp = date + String(m, FORMAT='(I2.2)') + year
        5:  timestamp = date + cgMonths(m, /ABBREVIATION) + year + '_' + stamp
        6:  timestamp = date + cgMonths(m, /ABBREVIATION, /LOWCASE) + year + '_' + stamp
        7:  timestamp = date + cgMonths(m, /ABBREVIATION, /ALLCAPS) + year + '_' + stamp
        8:  timestamp = String(m, FORMAT='(I2.2)') + '_' + date + '_' + year + '_' + stamp
        9:  timestamp = String(m, FORMAT='(I2.2)') + date + year + '_' + stamp        
        10: timestamp = String(m, FORMAT='(I2.2)') + date + year
        11: timestamp = year + String(m, FORMAT='(I2.2)') + date + '@' + stamp
        ELSE: timeStamp = StrLowCase(day) + '_' + StrLowCase(month) + '_' + date + '_' + stamp + '_' + year
    ENDCASE

    ; Add an first-letter underscore, unless the user explicitly asked not to.
    IF ~no_prefix THEN BEGIN 
       timestamp = '_' + timestamp
    ENDIF

    ; Convert to a valid string, if required.
    IF Keyword_Set(valid) THEN timestamp = IDL_Validname(timeStamp, /CONVERT_ALL)
    
    ; Add the random numbers, if required.
    IF N_Elements(randomNumber) NE 0 THEN BEGIN
        timeStamp = timeStamp + '_' + randomNumber
    ENDIF
    
    RETURN, timeStamp
    
END