ncbitime.hpp

ncbi源码

    ///   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.