生物技术

开发平台：
C/C++

ncbitime.hpp：源码内容
							/*
 * ===========================================================================
 * 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 (sakamoto@sm.sony.co.jp).
 *
 */
/// @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
    ///   MonthNameToNum(), Month()
    static string MonthNumToName(int month, ENameFormat format = eFull);
    /// Get numerical value of the day of week by name.
    ///
    /// @param day
    ///   Full or abbreviated day of week name.
    /// @return
    ///   Numerical value of a given day of week (0..6).
    /// @sa
    ///   DayOfWeekNumToName(), DayOfWeek()
    static int DayOfWeekNameToNum(const string& day);
    /// Get name of the day of week by numerical value.
    ///
    /// @param day
    ///   Full or abbreviated day of week name.
    /// @param format
    ///   Format for returned value (full or abbreviated).
    /// @return
    ///   Name of the day of week.
    /// @sa
    ///   DayOfWeekNameToNum(), DayOfWeek()
    static string DayOfWeekNumToName(int day, ENameFormat format = eFull);
    
    /// Transform time to string.
    ///
    /// Use GetFormat() to obtain format, if "fmt" is not defined (=kEmptyStr).
    /// @param fmt
    ///   Format specifier used to convert time to string.
    /// @param out_tz
    ///   Output timezone. This is a difference in seconds between GMT time
    ///   and local time for some place (for example, for EST5 timezone
    ///   its value is 18000). This parameter works only with local time.
    ///   If the time object have GMT time that it is ignored.
    ///   Before transformation to string the time will be converted to output
    ///   timezone. Timezone can be printed as string 'GMT[+|-]HHMM' using
    ///   format symbol 'z'. By default current timezone is used.
    /// @sa
    ///   GetFormat(), SetFormat()
    string AsString(const string& fmt = kEmptyStr,
                    long out_tz       = eCurrentTimeZone) const;
    /// Return time as string using the format returned by GetFormat().
    operator string(void) const;
    //
    // Get various components of time.
    //
    /// Get year.
    ///
    /// Year = 1900 ..  
    int Year(void) const;
    /// Get month.
    ///
    /// Month number = 1..12
    int Month(void) const;
    /// Get day.
    ///
    /// Day of the month = 1..31
    int Day(void) const;
    /// Get hour.
    ///
    /// Hours since midnight = 0..23
    int Hour(void) const;
    /// Get minute.
    ///
    /// Minutes after the hour = 0..59
    int Minute(void) const;
    /// Get second.
    ///
    /// Seconds after the minute = 0..59
    int Second(void) const;
    /// Get nano seconds.
    ///
    /// Nanoseconds after the second = 0..999999999
    long NanoSecond(void) const;
   
    //
    // Set various components of time.
    //
    /// Set year.
    ///
    /// Beware that this operation is inherently inconsistent.
    /// In case of different number of days in the months, the day number
    /// can change, e.g.:
    ///  - "Feb 29 2000".SetYear(2001) => "Feb 28 2001".
    /// Because 2001 is not leap year.
    /// @param year
    ///   Year to set.
    /// @sa
    ///   Year()
    void SetYear(int year);
    /// Set month.
    ///
    /// Beware that this operation is inherently inconsistent.
    /// In case of different number of days in the months, the day number
    /// can change, e.g.:
    ///  - "Dec 31 2000".SetMonth(2) => "Feb 29 2000".
    /// Therefore e.g. calling SetMonth(1) again that result will be "Jan 28".
    /// @param month
    ///   Month number to set. Month number = 1..12.
    /// @sa
    ///   Month()
    void SetMonth(int month);
    /// Set day.
    ///
    /// Beware that this operation is inherently inconsistent.
    /// In case of number of days in the months, the day number
    /// can change, e.g.:
    ///  - "Feb 01 2000".SetDay(31) => "Feb 29 2000".
    /// @param day
    ///   Day to set. Day of the month = 1..31.
    /// @sa
    ///   Day()
    void SetDay(int day);
    /// Set hour.
    ///
    /// @param day
    ///   Hours since midnight = 0..23.
    /// @sa
    ///   Hour()
    void SetHour(int hour);
    /// Set minute.
    ///
    /// @param minute
    ///   Minutes after the hour = 0..59.
    /// @sa
    ///   Minute()
    void SetMinute(int minute);
    /// Set second.
    ///
    /// @param day
    ///   Seconds after the minute = 0..59.
    /// @sa
    ///   Second()
    void SetSecond(int second);
    /// Set nano seconds.
    ///
    /// @param day
    ///   Nanoseconds after the second = 0..999999999.
    /// @sa
    ///   NanoSecond()
    void SetNanoSecond(long nanosecond);
    /// Get year's day number.
    ///
    /// Year day number = 1..366
    int YearDayNumber(void) const;
    /// Get week number in the year.
    ///
    /// Calculate the week number in a year of a given date.
    /// The week can start on any day accordingly given parameter.
    /// First week always start with 1st January.
    /// @param week_start
    ///   What day of week is first.
    ///   Default is to use Sunday as first day of week. For Monday-based
    ///   weeks use eMonday as parameter value.
    /// @return
    ///   Week number = 1..54.
    int YearWeekNumber(EDayOfWeek first_day_of_week = eSunday) const;
    /// Get week number in current month.
    ///
    /// @return
    ///   Week number in current month = 1..6.
    /// @sa
    ///   YearWeekNumber()
    int MonthWeekNumber(EDayOfWeek first_day_of_week = eSunday) const;
    /// Get day of week.
    ///
    /// Days since Sunday = 0..6
    int DayOfWeek(void) const;
    /// Get number of days in the current month.
    ///
    /// Number of days = 1..31
    int DaysInMonth(void) const;
    /// Add specified years and adjust for day light savings time.
    ///
    /// It is an exact equivalent of calling AddMonth(years * 12).
    /// @sa
    ///   AddMonth()
    CTime& AddYear(int years = 1, EDaylight adl = eDaylightDefault);
    /// Add specified months and adjust for day light savings time.
    ///
    /// Beware that this operation is inherently inconsistent.
    /// In case of different number of days in the months, the day number
    /// can change, e.g.:
    ///  - "Dec 31 2000".AddMonth(2) => "Feb 28 2001" ("Feb 29" if leap year).
    /// Therefore e.g. calling AddMonth(1) 12 times for e.g. "Jul 31" will
    /// result in "Jul 28" (or "Jul 29") of the next year.
    /// @param months
    ///   Months to add. Default is 1 month.
    ///   If negative, it will result in a "subtraction" operation.
    /// @param adl
    ///   Whether to adjust for daylight saving time. Default is to adjust
    ///   for daylight savings time. This parameter is for eLocal time zone
    ///   and where the time zone precision is not eNone. 
    CTime& AddMonth(int months = 1, EDaylight adl = eDaylightDefault);
    /// Add specified days and adjust for day light savings time.
    ///
    /// @param days
    ///   Days to add. Default is 1 day.
    ///   If negative, it will result in a "subtraction" operation.
    /// @param adl
    ///   Whether to adjust for daylight saving time. Default is to adjust
    ///   for daylight savings time. This parameter is for eLocal time zone
    ///   and where the time zone precision is not eNone. 
    CTime& AddDay(int days = 1, EDaylight adl = eDaylightDefault);
    /// Add specified hours and adjust for day light savings time.
    ///
    /// @param hours
    ///   Hours to add. Default is 1 hour.
    ///   If negative, it will result in a "subtraction" operation.
    /// @param adl
    ///   Whether to adjust for daylight saving time. Default is to adjust
    ///   for daylight savings time. This parameter is for eLocal time zone
    ///   and where the time zone precision is not eNone. 
    CTime& AddHour(int hours = 1, EDaylight adl = eDaylightDefault);
    /// Add specified minutes and adjust for day light savings time.
    ///
    /// @param minutes
    ///   Minutes to add. Default is 1 minute.
    ///   If negative, it will result in a "subtraction" operation.
    /// @param adl
    ///   Whether to adjust for daylight saving time. Default is to adjust
    ///   for daylight savings time. This parameter is for eLocal time zone
    ///   and where the time zone precision is not eNone. 
    CTime& AddMinute(int minutes = 1, EDaylight adl = eDaylightDefault);
    /// Add specified seconds.
    ///
    /// @param seconds
    ///   Seconds to add. Default is 1 second.
    ///   If negative, it will result in a "subtraction" operation.
    CTime& AddSecond(int seconds = 1);
    /// Add specified nanoseconds.
    ///
    /// @param nanoseconds
    ///   Nanoseconds to add. Default is 1 nanosecond.
    ///   If negative, it will result in a "subtraction" operation.
    CTime& AddNanoSecond(long nanoseconds = 1);
    // Add/subtract days
    /// Operator to add days.
    CTime& operator += (const int days);
    /// Operator to subtract days.
    CTime& operator -= (const int days);
    /// Operator to increment days.
    CTime& operator ++ (void);
    /// Operator to decrement days.
    CTime& operator -- (void);
    /// Operator to increment days.
    CTime  operator ++ (int);
    /// Operator to decrement days.
    CTime  operator -- (int);
    // Time comparison ('>' means "later", '<' means "earlier")
    /// Operator to test equality of time.
    bool operator == (const CTime& t) const;
    /// Operator to test in-equality of time.
    bool operator != (const CTime& t) const;
    /// Operator to test if time is later.
    bool operator >  (const CTime& t) const;
    /// Operator to test if time is earlier.
    bool operator <  (const CTime& t) const;
    /// Operator to test if time is later or equal.
    bool operator >= (const CTime& t) const;
    /// Operator to test if time is earlier or equal.
    bool operator <= (const CTime& t) const;
    // Time difference
    /// Difference in days from specified time.
    double DiffDay(const CTime& t) const;
    /// Difference in hours from specified time.
    double DiffHour(const CTime& t) const;
    /// Difference in minutes from specified time.
    double DiffMinute(const CTime& t) const;
    /// Difference in seconds from specified time.
    int DiffSecond(const CTime& t) const;
    /// Difference in nanoseconds from specified time.
    double DiffNanoSecond(const CTime& t) const;
    // Checks
    /// Is time empty?
    bool IsEmpty     (void) const;
    /// Is time in a leap year?
    bool IsLeap      (void) const;
    /// Is time valid?
    bool IsValid     (void) const;
    /// Is time local time?
    bool IsLocalTime (void) const;
    /// Is time GMT time?
    bool IsGmtTime   (void) const;
    // Timezone functions
    /// Get time zone format.
    ETimeZone GetTimeZoneFormat(void) const;
    /// Set time zone format.
    ETimeZone SetTimeZoneFormat(ETimeZone val);
    /// Get time zone precision.
    ETimeZonePrecision GetTimeZonePrecision(void) const;
    /// Set time zone precision.
    ETimeZonePrecision SetTimeZonePrecision(ETimeZonePrecision val);
    /// Get difference between local timezone and GMT in seconds.
    int TimeZoneDiff(void) const;
    /// Get current time as local time.
    CTime GetLocalTime(void) const;
    /// Get current time as GMT time.
    CTime GetGmtTime(void) const;
    /// Convert current time into specified time zone time.
    CTime& ToTime(ETimeZone val);
    /// Convert current time into local time.
    CTime& ToLocalTime(void);
    /// Convert current time into GMT time.
    CTime& ToGmtTime(void);
private:
  
    /// Helper method to check if time format "fmt" is valid.
    static void x_VerifyFormat(const string& fmt);
    /// Helper method to set time value from string "str" using format "fmt".
    void x_Init(const string& str, const string& fmt);
    /// Helper method to set time from 'time_t' -- If "t" not specified,
    /// then set to current time.
    CTime& x_SetTime(const time_t* t = 0);
    /// Helper method to adjust day number to correct value after day
    /// manipulations.
    void x_AdjustDay(void);
    /// Helper method to adjust the time to correct timezone (across the
    /// barrier of winter & summer times) using "from" as a reference point.
    ///
    /// This does the adjustment only if the time object:
    /// - contains local time (not GMT), and
    /// - has TimeZonePrecision != CTime::eNone, and
    /// - differs from "from" in the TimeZonePrecision (or larger) part.
    CTime& x_AdjustTime(const CTime& from, bool shift_time = true);
    /// Helper method to forcibly adjust timezone using "from" as a
    /// reference point.
    CTime& x_AdjustTimeImmediately(const CTime& from, bool shift_time = true);
    /// Helper method to check if there is a need adjust time in timezone.
    bool x_NeedAdjustTime(void) const;
    /// Helper method to add hour with/without shift time.
    /// Parameter "shift_time" access or denied use time shift in 
    /// process adjust hours.
    CTime& x_AddHour(int hours = 1, EDaylight daylight = eDaylightDefault, 
                     bool shift_time = true);
    // Time
    int           m_Year;       ///< Private data member year
    unsigned char m_Month;      ///< Private data member month
    unsigned char m_Day;        ///< Private data member day
    unsigned char m_Hour;       ///< Private data member hour
    unsigned char m_Minute;     ///< Private data member minute
    unsigned char m_Second;     ///< Private data member second
    unsigned long m_NanoSecond; ///< Private data member nanosecond
    // Timezone and precision
    ETimeZone          m_Tz;    ///< Private data member timezone
    ETimeZonePrecision m_TzPrecision;///< Private data member time zone prec.
    /// Difference between GMT and local time in seconds,
    /// as stored during the last call to x_AdjustTime***().
    int m_AdjustTimeDiff;
    // Friend operators
    NCBI_XNCBI_EXPORT
    friend CTime operator + (int days, const CTime& t);
    NCBI_XNCBI_EXPORT
    friend CTime operator + (const CTime& t, int days);
    NCBI_XNCBI_EXPORT
    friend CTime operator - (const CTime& t, int days);
};
/////////////////////////////////////////////////////////////////////////////
///
/// CStopWatch --
///
/// Define a stop watch class to measure elasped time.
class NCBI_XNCBI_EXPORT CStopWatch
{
public:
    /// Constructor.
    /// NB. Ctor doesn't start timer, it merely creates it.
    CStopWatch(void);
    /// Start the timer.
    void Start(void);
    /// Return time elapsed time since last Start() call.
    /// Result is underfined if Start() wasn't previously called.
    double Elapsed(void) const;
protected:
    /// Get current time mark.
    static double GetTimeMark();
private:
    double m_Start;  ///< Start time value.
};
/* @} */
//=============================================================================
//
//  Extern
//
//=============================================================================
// Add (subtract if negative) to the time (see CTime::AddXXX)
NCBI_XNCBI_EXPORT
extern CTime AddYear       (const CTime& t, int  years       = 1);
NCBI_XNCBI_EXPORT
extern CTime AddMonth      (const CTime& t, int  months      = 1);
NCBI_XNCBI_EXPORT
extern CTime AddDay        (const CTime& t, int  days        = 1);
NCBI_XNCBI_EXPORT
extern CTime AddHour       (const CTime& t, int  hours       = 1);
NCBI_XNCBI_EXPORT
extern CTime AddMinute     (const CTime& t, int  minutes     = 1);
NCBI_XNCBI_EXPORT
extern CTime AddSecond     (const CTime& t, int  seconds     = 1);
NCBI_XNCBI_EXPORT
extern CTime AddNanoSecond (const CTime& t, long nanoseconds = 1);
// Add/subtract days (see CTime::operator +/-)
NCBI_XNCBI_EXPORT
extern CTime operator + (int days, const CTime& t);
NCBI_XNCBI_EXPORT
extern CTime operator + (const CTime& t, int days);
NCBI_XNCBI_EXPORT
extern CTime operator - (const CTime& t, int days);
// Difference in days (see CTime::operator)
NCBI_XNCBI_EXPORT
extern int   operator - (const CTime& t1, const CTime& t2);
// Get current time (in local or GMT format)
NCBI_XNCBI_EXPORT
extern CTime CurrentTime(
    CTime::ETimeZone          tz  = CTime::eLocal, 
    CTime::ETimeZonePrecision tzp = CTime::eTZPrecisionDefault
    );
// Truncate the time to days (see CTime::Truncate)
NCBI_XNCBI_EXPORT 
extern CTime Truncate(const CTime& t);
//=============================================================================
//
//  Inline
//
//=============================================================================
// CTime
inline 
int CTime::Year(void) const { return m_Year; }
inline 
int CTime::Month(void) const { return m_Month; }
inline 
int CTime::Day(void) const { return m_Day; }
inline 
int CTime::Hour(void) const { return m_Hour; }
inline 
int CTime::Minute(void) const { return m_Minute; }
inline 
int CTime::Second(void) const { return m_Second; }
inline 
long CTime::NanoSecond(void) const { return (long) m_NanoSecond; }
inline 
CTime& CTime::AddYear(int years, EDaylight adl)
{
    return AddMonth(years * 12, adl);
}
inline
CTime& CTime::SetTimeT(const time_t& t) { return x_SetTime(&t); }
inline
CTime& CTime::SetCurrent(void) { return x_SetTime(); }
inline 
CTime& CTime::operator += (const int days) { return AddDay(days); }
inline 
CTime& CTime::operator -= (const int days) { return AddDay(-days); }
inline 
CTime& CTime::operator ++ (void) { return AddDay( 1); }
inline 
CTime& CTime::operator -- (void) { return AddDay(-1); }
inline 
CTime::operator string(void) const { return AsString(); }
inline 
CTime CTime::operator ++ (int)
{
    CTime t = *this;
    AddDay(1);
    return t;
}
inline 
CTime CTime::operator -- (int)
{
    CTime t = *this;
    AddDay(-1);
    return t;
}
inline 
CTime& CTime::operator = (const string& str)
{
    x_Init(str, GetFormat());
    return *this;
}
inline 
CTime& CTime::operator = (const CTime& t)
{
    if ( &t == this )
        return *this;
    m_Year           = t.m_Year;
    m_Month          = t.m_Month;
    m_Day            = t.m_Day;
    m_Hour           = t.m_Hour;
    m_Minute         = t.m_Minute;
    m_Second         = t.m_Second;
    m_NanoSecond     = t.m_NanoSecond;
    m_Tz             = t.m_Tz;
    m_TzPrecision    = t.m_TzPrecision;
    m_AdjustTimeDiff = t.m_AdjustTimeDiff;
    return *this;
}
inline 
bool CTime::operator != (const CTime& t) const
{
    return !(*this == t);
}
inline 
bool CTime::operator >= (const CTime& t) const
{
    return !(*this < t);
}
inline
bool CTime::operator <= (const CTime& t) const
{
    return !(*this > t);
}
inline
CTime& CTime::AddHour(int hours, EDaylight use_daylight)
{
    return x_AddHour(hours, use_daylight, true);
}
inline 
bool CTime::IsEmpty() const
{
    return
        !Day()   &&  !Month()   &&  !Year()  &&
        !Hour()  &&  !Minute()  &&  !Second()  &&  !NanoSecond();
}
inline 
double CTime::DiffDay(const CTime& t) const
{
    return DiffSecond(t) / 60.0 / 60.0 / 24.0;
}
inline 
double CTime::DiffHour(const CTime& t) const
{
    return DiffSecond(t) / 60.0 / 60.0;
}
inline 
double CTime::DiffMinute(const CTime& t) const
{
    return DiffSecond(t) / 60.0;
}
inline 
double CTime::DiffNanoSecond(const CTime& t) const
{
    long dNanoSec = NanoSecond() - t.NanoSecond();
    return (double) DiffSecond(t) * kNanoSecondsPerSecond + dNanoSec;
}
inline 
bool CTime::IsLocalTime(void) const { return m_Tz == eLocal; } 
inline 
bool CTime::IsGmtTime(void) const { return m_Tz == eGmt; }
inline 
CTime::ETimeZone CTime::GetTimeZoneFormat(void) const
{
    return m_Tz;
}
inline 
CTime::ETimeZonePrecision CTime::GetTimeZonePrecision(void) const
{
    return m_TzPrecision;
}
inline 
CTime::ETimeZone CTime::SetTimeZoneFormat(ETimeZone val)
{
    ETimeZone tmp = m_Tz;
    m_Tz = val;
    return tmp;
}
inline 
CTime::ETimeZonePrecision CTime::SetTimeZonePrecision(ETimeZonePrecision val)
{
    ETimeZonePrecision tmp = m_TzPrecision;
    m_TzPrecision = val;
    return tmp;
}
inline 
int CTime::TimeZoneDiff(void) const
{
    return GetLocalTime().DiffSecond(GetGmtTime());
}
inline 
CTime CTime::GetLocalTime(void) const
{
    if ( IsLocalTime() )
        return *this;
    CTime t(*this);
    return t.ToLocalTime();
}
inline 
CTime CTime::GetGmtTime(void) const
{
    if ( IsGmtTime() )
        return *this;
    CTime t(*this);
    return t.ToGmtTime();
}
inline
CTime& CTime::ToLocalTime(void)
{
    ToTime(eLocal);
    return *this;
}
inline
CTime& CTime::ToGmtTime(void)
{
    ToTime(eGmt);
    return *this;
}
inline 
bool CTime::x_NeedAdjustTime(void) const
{
    return GetTimeZoneFormat() == eLocal  &&  GetTimeZonePrecision() != eNone;
}
// CStopWatch
inline
CStopWatch::CStopWatch(void)
    : m_Start(0)
{
}
inline
void CStopWatch::Start()
{
    m_Start = GetTimeMark();
}
inline
double CStopWatch::Elapsed() const
{
    return GetTimeMark() - m_Start;
}
END_NCBI_SCOPE
/*
 * ===========================================================================
 * $Log: ncbitime.hpp,v $
 * Revision 1000.5  2004/04/21 14:34:55  gouriano
 * PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.33
 *
 * Revision 1.33  2004/04/07 19:07:29  lavr
 * Document CStopWatch in a little more details
 *
 * Revision 1.32  2004/03/24 15:52:50  ivanov
 * Added new format symbol support 'z' (local time in format GMT{+|-}HHMM).
 * Added second parameter to AsString() method that specify an output
 * timezone.
 *
 * Revision 1.31  2004/03/10 19:56:38  gorelenk
 * Added NCBI_XNCBI_EXPORT prefix for functions AddYear, AddMonth, AddDay,
 * AddHour, AddMinute, AddSecond, AddNanoSecond and operators:
 * CTime operator + and CTime operator - .
 *
 * Revision 1.30  2004/01/26 18:07:22  siyan
 * Fixed errors in documentation on GetTimeT()
 *
 * Revision 1.29  2003/11/25 20:03:32  ivanov
 * Fixed misspelled eTZPrecisionDefault
 *
 * Revision 1.28  2003/11/25 19:53:33  ivanov
 * Renamed eDefault to eTZPrecisionDefault.
 * Added setters for various components of time -- Set*().
 * Added YearWeekNumber(), MonthWeekNumber().
 * Reimplemented AddYear() as AddMonth(years*12).
 *
 * Revision 1.27  2003/11/21 20:04:41  ivanov
 * + DaysInMonth()
 *
 * Revision 1.26  2003/11/18 11:58:24  siyan
 * Changed so @addtogroup does not cross namespace boundary
 *
 * Revision 1.25  2003/10/03 18:26:48  ivanov
 * Added month and day of week names conversion functions
 *
 * Revision 1.24  2003/09/11 13:26:13  siyan
 * Documentation changes
 *
 * Revision 1.23  2003/07/15 19:34:28  vakatov
 * Comment typo fix
 *
 * Revision 1.22  2003/04/16 20:28:26  ivanov
 * Added class CStopWatch
 *
 * Revision 1.21  2003/04/14 19:41:32  ivanov
 * Rollback to R1.19 -- accidental commit
 *
 * Revision 1.19  2003/04/01 19:18:43  siyan
 * Added doxygen support
 *
 * Revision 1.18  2003/02/10 22:36:55  ucko
 * Make string- and time_t-based constructors explicit, to avoid weird surprises.
 *
 * Revision 1.17  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.16  2002/10/17 16:55:01  ivanov
 * Added new time format symbols - 'b' and 'B' (month abbreviated and full name)
 *
 * Revision 1.15  2002/07/23 19:53:34  lebedev
 * NCBI_OS_MAC: Note about Daylight flag handling added
 *
 * Revision 1.14  2002/07/15 18:17:52  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.13  2002/07/11 14:17:56  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.12  2002/05/13 13:56:30  ivanov
 * Added MT-Safe support
 *
 * Revision 1.11  2002/04/11 20:39:20  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.10  2001/07/06 15:11:30  ivanov
 * Added support DataBase-time's -- GetTimeDBI(), GetTimeDBU()
 *                                  SetTimeDBI(), SetTimeDBU()
 *
 * Revision 1.9  2001/07/04 19:41:07  vakatov
 * Get rid of an extra semicolon
 *
 * Revision 1.8  2001/06/12 16:56:36  vakatov
 * Added comments for the time constituents access methods
 *
 * Revision 1.7  2001/05/29 20:12:58  ivanov
 * Changed type of return value in NanoSecond().
 *
 * Revision 1.6  2001/05/29 16:14:34  ivanov
 * Return to nanosecond-revision. Corrected mistake of the work with local
 * time on Linux. Polish and improvement source code.
 * Renamed AsTimeT() -> GetTimerT().
 *
 * Revision 1.5  2001/04/30 22:01:29  lavr
 * Rollback to pre-nanosecond-revision due to necessity to use
 * configure to figure out names of global variables governing time zones
 *
 * Revision 1.4  2001/04/29 03:06:10  lavr
 * #include <time.h>" moved from .cpp to ncbitime.hpp
 *
 * Revision 1.3  2001/04/27 20:42:29  ivanov
 * Support for Local and UTC time added.
 * Support for work with nanoseconds added.
 *
 * Revision 1.2  2000/11/21 18:15:29  butanaev
 * Fixed bug in operator ++/-- (int)
 *
 * Revision 1.1  2000/11/20 22:17:42  vakatov
 * Added NCBI date/time class CTime ("ncbitime.[ch]pp") and
 * its test suite ("test/test_ncbitime.cpp")
 *
 * ===========================================================================
 */
#endif /* CORELIB__NCBITIME__HPP */

						