ncbitime.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbitime.hpp,v $
 * PRODUCTION Revision 1000.5  2004/04/21 14:34:55  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.33
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CORELIB__NCBITIME__HPP
#define CORELIB__NCBITIME__HPP

/*  $Id: ncbitime.hpp,v 1000.5 2004/04/21 14:34:55 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Anton Butanayev, Denis Vakatov, Vladimir Ivanov
 *
 * DayOfWeek():  Used code has been posted on comp.lang.c on March 10th, 1993
 *               by Tomohiko Sakamoto ([e-mail]).
 *
 */

/// @file ncbitime.hpp
/// Defines CTime, the standard Date/Time class which also can be used
/// to span time (to represent elapsed time).
///
/// NOTE: 
///   - Do not use Local time and time_t and its dependent functions with
///     dates outside range January 1, 1970 to January 18, 2038.
///     Also avoid to use GMT -> Local time conversion functions.
///
///   - Do not use DataBase conversion functions with dates
///     less than January 1, 1900.
///
///   - Mac OS 9 does not correctly support daylight savings flag.
///     CTime implementation does not support Daylight on this platform.


#include <corelib/ncbistd.hpp>
#include <corelib/ncbitype.h>
#include <time.h>


BEGIN_NCBI_SCOPE

/** @addtogroup Time
 *
 * @{
 */


/////////////////////////////////////////////////////////////////////////////
///
/// CTimeException --
///
/// Define exceptions generated by CTime.
///
/// CTimeException inherits its basic functionality from CCoreException
/// and defines additional error codes.

class NCBI_XNCBI_EXPORT CTimeException : public CCoreException
{
public:
    /// Error types that CTime can generate.
    enum EErrCode {
        eInvalid,       ///< Invalid time value
        eArgument,      ///< Bad function argument
        eFormat         ///< Incorrect format
    };

    /// Translate from the error code value to its string representation.
    virtual const char* GetErrCodeString(void) const
    {
        switch (GetErrCode()) {
        case eInvalid:   return "eInvalid";
        case eFormat:    return "eFormat";
        default:    return CException::GetErrCodeString();
        }
    }

    // Standard exception boilerplate code.
    NCBI_EXCEPTION_DEFAULT(CTimeException, CCoreException);
};


/// Number of nanoseconds in one second.
///
/// Interval for it is from 0 to 999,999,999. 
const long kNanoSecondsPerSecond = 1000000000;

/// Number of microseconds in one second.
///
/// Interval for it is from 0 to 999,999. 
const long kMicroSecondsPerSecond = 1000000;

/// Number milliseconds in one second.
///
/// Interval for it is from 0 to 999.
const long kMilliSecondsPerSecond = 1000;


// Time formats in databases (always contain local time only!)

/// Database format for time where day and time is unsigned 16 bit.
typedef struct {
    Uint2 days;   ///< Days from 1/1/1900
    Uint2 time;   ///< Minutes from begin of current day
} TDBTimeU, *TDBTimeUPtr;

/// Database format for time where day and time is signed 32 bit.
typedef struct {
    Int4  days;   ///< days from 1/1/1900
    Int4  time;   ///< x/300 seconds from begin of current day
} TDBTimeI, *TDBTimeIPtr;



/////////////////////////////////////////////////////////////////////////////
///
/// CTime --
///
/// Defines a standard Date/Time class.
///
/// Can be used to span time (to represent elapsed time). Can operate with
/// local and UTC time. The time is kept in class in the format in which it
/// was originally given. 
///
/// Throw exception of type CTimeException on errors.
///
/// NOTE: Do not use local time with time span and dates < "1/1/1900"
/// (use GMT time only!!!).

class NCBI_XNCBI_EXPORT CTime
{
public:
    /// Which initial value to use for time.
    enum EInitMode {
        eCurrent,     ///< Use current time
        eEmpty        ///< Use "empty" time
    };
    
    /// Which initial value to use for timezone.
    enum ETimeZone {
        eLocal,       ///< Use local time
        eGmt          ///< Use GMT (Greenwich Mean Time)
    };

    /// Current timezone. Used in AsString() method.
    enum {
	    eCurrentTimeZone= -1
    };

    /// Which format use to get name of month or week of day.
    enum ENameFormat {
        eFull,        ///< Use full name.
        eAbbr         ///< Use abbreviated name.
    };

    // Month names.
    enum EMonth {
        eJanuary = 1,
        eFebruary,
        eMarch,
        eApril,
        eMay,
        eJune,
        eJuly,
        eAugust,
        eSeptember,
        eOctober,
        eNovember,
        eDecember
    };

    // Day of week names.
    enum EDayOfWeek {
        eSunday = 0,
        eMonday,
        eTuesday,
        eWednesday,
        eThursday,
        eFriday,
        eSaturday
    };

    /// What time zone precision to use for adjusting daylight saving time.
    ///
    /// Controls when (if ever) to adjust for the daylight saving time
    /// (only if the time is represented in local timezone format).
    ///
    /// NOTE: if diff between previous time value and the time
    /// after manipulation is greater than this range, then try apply
    /// daylight saving conversion on the result time value.
    enum ETimeZonePrecision {
        eNone,    ///< Daylight saving not to affect time manipulations.
        eMinute,  ///< Check condition - new minute.
        eHour,    ///< Check condition - new hour.
        eDay,     ///< Check condition - new day.
        eMonth,   ///< Check condition - new month.
        eTZPrecisionDefault = eNone
    };

    /// Whether to adjust for daylight saving time.
    enum EDaylight {
        eIgnoreDaylight,   ///< Ignore daylight savings time.
        eAdjustDaylight,   ///< Adjust for daylight savings time.
        eDaylightDefault = eAdjustDaylight
    };

    /// Constructor.
    ///
    /// @param mode
    ///   Whether to build time object with current time or empty
    ///   time (default).
    /// @param tz
    ///   Whether to use local time (default) or GMT. 
    /// @param tzp
    ///   What time zone precision to use.
    CTime(EInitMode          mode = eEmpty,
          ETimeZone          tz   = eLocal,
          ETimeZonePrecision tzp  = eTZPrecisionDefault);

    /// Explicit conversion constructor for time_t representation of time.
    ///
    /// Construct time object from UTC time_t value (assuming it is eGMT).
    ///
    /// @param t
    ///   Time in the UTC time_t format.
    /// @param tzp
    ///   What time zone precision to use.
    explicit CTime(time_t t, ETimeZonePrecision tzp = eTZPrecisionDefault);

    /// Constructor.
    ///
    /// Construct time given the year, month, day, hour, minute, second,
    /// nanosecond parts of a time value.
    ///
    /// @param year
    ///   Year part of time.
    /// @param month
    ///   Month part of time. Note month starts from 1.
    /// @param day
    ///   Day part of time. Note day starts from 1.
    /// @param second
    ///   Second part of time.
    /// @param nanosecond
    ///   Nanosecond part of time.
    /// @param tz
    ///   Whether to use local time (default) or GMT. 
    /// @param tzp
    ///   What time zone precision to use.
    CTime(int year, int month, int day,
          int hour = 0, int minute = 0, int second = 0, long nanosecond = 0,
          ETimeZone tz = eLocal,
          ETimeZonePrecision tzp = eTZPrecisionDefault);

    /// Constructor.
    ///
    /// Construct date as N-th day of the year.
    ///
    /// @param year
    ///   Year part of date.
    /// @param yearDayNumber
    ///   N-th day of the year.
    /// @param tz
    ///   Whether to use local time (default) or GMT. 
    /// @param tzp
    ///   What time zone precision to use.
    CTime(int year, int yearDayNumber,
          ETimeZone tz = eLocal,
          ETimeZonePrecision tzp = eTZPrecisionDefault);

    /// Explicit conversion constructor for string representation of time.
    ///
    /// Construct time object from string representation of time.
    ///
    /// @param str
    ///   String representation of time in format "fmt".
    /// @param fmt
    ///   Format in which "str" is presented. Default value of kEmptyStr,
    ///   implies the "M/D/Y h:m:s" format.
    /// @param tz
    ///   Whether to use local time (default) or GMT. 
    /// @param tzp
    ///   What time zone precision to use.
    explicit CTime(const string& str, const string& fmt = kEmptyStr,
                   ETimeZone tz = eLocal,
                   ETimeZonePrecision tzp = eTZPrecisionDefault);

    /// Copy constructor.
    CTime(const CTime& t);

    /// Assignment operator.
    CTime& operator = (const CTime& t);

    /// Assignment operator -- rhs is string.
    ///
    /// If current format contains 'Z', then TimeZone will be set to:
    /// - eGMT if "str" has word "GMT" in the appropriate position;
    /// - eLocal otherwise.
    ///
    /// If current format does not contain 'Z', TimeZone will not be changed.
    CTime& operator = (const string& str);

    /// Set time using time_t time value.
    ///
    /// @param t
    ///   Time to set in time object. This is always in GMT time format, and
    ///   nanoseconds will be truncated. 
    /// @return
    ///   Time object that is set.
    CTime& SetTimeT(const time_t& t);

    /// Get time (time_t format).
    ///
    /// The function return the number of seconds elapsed since midnight
    /// (00:00:00), January 1, 1970. Do not use this function if year is
    /// less 1970.
    /// @return
    ///   Time in time_t format.
    time_t GetTimeT(void) const;

    /// Set time using database format time, TDBTimeU.
    ///
    /// Object's time format will always change to eLocal after call.
    ///
    /// @param t
    ///   Time to set in time object in TDBTimeU format.
    ///   This is always in local time format, and seconds, and nanoseconds
    ///   will be truncated. 
    /// @return
    ///   Time object that is set.
    CTime& SetTimeDBU(const TDBTimeU& t);

    /// Set time using database format time, TDBTimeI.
    ///
    /// Object's time format will always change to eLocal after call.
    ///
    /// @param t
    ///   Time to set in time object in TDBTimeI format.
    ///   This is always in local time format, and seconds, and nanoseconds
    ///   will be truncated. 
    /// @return
    ///   Time object that is set.
    CTime& SetTimeDBI(const TDBTimeI& t);

    /// Get time in database format time, TDBTimeU.
    ///
    /// @return
    ///   Time value in database format, TDBTimeU.
    TDBTimeU GetTimeDBU(void) const;

    /// Get time in database format time, TDBTimeI.
    ///
    /// @return
    ///   Time value in database format TDBTimeI.
    TDBTimeI GetTimeDBI(void) const;

    /// Make the time current in the presently active time zone.
    CTime& SetCurrent(void);
    
    /// Make the time "empty",
    CTime& Clear(void);
    
    /// Truncate the time to days (strip H,M,S and Nanoseconds.
    CTime& Truncate(void);

    /// Set the current time format.
    /// 
    /// The default format is: "M/D/Y h:m:s".
    /// @param fmt
    ///   String of letters describing the time format. The letters having
    ///   the following meanings:
    ///   - Y = year with century
    ///   - y = year without century (00-99)
    ///   - M = month as decimal number (01-12)
    ///   - B = full month name
    ///   - b = abbeviated month name
    ///   - D = day as decimal number (01-31)
    ///   - h = hour in 24-hour format (00-23)
    ///   - m = minute as decimal number (00-59)
    ///   - s = second as decimal number (00-59)
    ///   - S = nanosecond as decimal number (000000000-999999999)
    ///   - Z = timezone format (GMT or none) 
    ///   - W = full day of week name
    ///   - w = abbreviated day of week name
    /// @sa
    ///   GetFormat()
    static void SetFormat(const string& fmt);

    /// Get the current time format.
    /// 
    /// The default format is: "M/D/Y h:m:s".
    /// @return
    ///   A string of letters describing the time format. The letters having
    ///   the following meanings:
    ///   - Y = year with century
    ///   - y = year without century (00-99)
    ///   - M = month as decimal number (01-12)
    ///   - B = full month name
    ///   - b = abbeviated month name
    ///   - D = day as decimal number (01-31)
    ///   - h = hour in 24-hour format (00-23)
    ///   - m = minute as decimal number (00-59)
    ///   - s = second as decimal number (00-59)
    ///   - S = nanosecond as decimal number (000000000-999999999)
    ///   - Z = timezone format (GMT or none) 
    ///   - W = full day of week name
    ///   - w = abbreviated day of week name
    /// @sa
    ///   SetFormat()
    static string GetFormat(void);

    /// Get numerical value of the month by name.
    ///
    /// @param month
    ///   Full or abbreviated month name.
    /// @return
    ///   Numerical value of a given month (1..12).
    /// @sa
    ///   MonthNumToName(), Month()
    static int MonthNameToNum(const string& month);

    /// Get name of the month by numerical value.
    ///
    /// @param month
    ///   Full or abbreviated month name.
    /// @param format
    ///   Format for returned value (full or abbreviated).
    /// @return
    ///   Name of the month.
    /// @sa