NCBI C++ ToolKit
ncbitime.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CORELIB__NCBITIME__HPP
2 #define CORELIB__NCBITIME__HPP
3 
4 /* $Id: ncbitime.hpp 102404 2024-05-01 14:04:19Z ivanov $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Anton Butanayev, Denis Vakatov, Vladimir Ivanov
30  *
31  * DayOfWeek(): Used code has been posted on comp.lang.c on March 10th, 1993
32  * by Tomohiko Sakamoto (sakamoto@sm.sony.co.jp).
33  *
34  */
35 
36 /// @file ncbitime.hpp
37 /// Defines:
38 /// CTimeFormat - storage class for time format.
39 /// CTime - standard Date/Time class to represent an absolute time.
40 /// CTimeSpan - class to represents a relative time span.
41 /// CStopWatch - stop watch class to measure elapsed time.
42 /// CTimeout - timeout interval for various I/O etc activity.
43 /// CNanoTimeout - timeout interval with nanoseconds precision.
44 /// CDeadline - timeout that use absolute time mark (deadline time).
45 /// CFastLocalTime - class for quick and dirty getting a local time.
46 ///
47 /// NOTE(s) about CTime and Time API:
48 ///
49 /// 1) CTime works with Gregorian calendar dates only (with some cut-off).
50 /// Earlier valid date is January 1, 1583.
51 ///
52 /// 2) Do not use local time and time_t and its dependent functions with
53 /// dates outside the range January 1, 1970 UTC to January 18, 2038 UTC.
54 /// Also avoid to use universal->local time conversion functions.
55 ///
56 /// 3) On Windows-based computers the time zone database usually stores
57 /// a single start and end rule for each zone only, regardless of year.
58 /// One of the problems of this approach is that using time-zone
59 /// information for some year in past will get incorrect results,
60 /// if time zone rules changes since then. This affect local time only,
61 /// any calculations with UTC time should be fine.
62 ///
63 /// 4) Do not use DataBase conversion functions for dates prior to January 1, 1900.
64 
65 #include <corelib/ncbistd.hpp>
66 
67 
69 
70 /** @addtogroup Time
71  *
72  * @{
73  */
74 
75 // Forward declarations
76 class CTimeSpan;
77 class CFastLocalTime;
78 
79 /// Number of seconds.
80 typedef Int8 TSeconds;
81 
82 
83 /// Number of nanoseconds in one second.
84 ///
85 /// Interval for it is from 0 to 999,999,999.
86 const long kNanoSecondsPerSecond = 1000000000;
87 
88 /// Number of microseconds in one second.
89 ///
90 /// Interval for it is from 0 to 999,999.
91 const long kMicroSecondsPerSecond = 1000000;
92 
93 /// Number milliseconds in one second.
94 ///
95 /// Interval for it is from 0 to 999.
96 const long kMilliSecondsPerSecond = 1000;
97 
98 /// The average length of the year in the Gregorian (modern) calendar (in days)
99 const double kAverageDaysPerYear = 365.2425;
100 /// The average length of the year in the Gregorian (modern) calendar (in seconds)
101 const TSeconds kAverageSecondsPerYear = 31556952; // 365.2425*24*3600
103 
104 
105 // Time formats in databases (always contain local time only!)
106 
107 /// Database format for time where day and time is unsigned 16 bit.
108 typedef struct {
109  Uint2 days; ///< Days from 1/1/1900
110  Uint2 time; ///< Minutes from the beginning of current day
112 
113 /// Database format for time where day and time is signed 32 bit.
114 typedef struct {
115  Int4 days; ///< days from 1/1/1900
116  Int4 time; ///< x/300 seconds from the beginning of current day
118 
119 
120 
121 /////////////////////////////////////////////////////////////////////////////
122 ///
123 /// CTimeFormat --
124 ///
125 /// Defines a storage class for time format.
126 ///
127 /// See CTime::SetFormat() and CTimeSpan::SetFormat() for description
128 /// of format symbols for specific class.
129 
131 {
132 public:
133  /// Flags.
134  ///
135  /// @note
136  /// It not specified otherwise, format have fDefault value "by default",
137  /// that mean simple format string and strict matching.
138  /// @sa SetFormat, AsString
139  enum EFlags {
140  // Format flags
141 
142  /// Use single characters as format symbols.
143  /// (default)
144  fFormat_Simple = (1 << 0),
145  /// Specify each format symbol with a preceding symbol '$'.
146  /// This can be useful if your format string includes output characters
147  /// that otherwise can be treated as format symbols.
148  /// To include symbol '$' use '$$'.
149  fFormat_Ncbi = (1 << 1),
150 
151  // Time string parsing flags
152 
153  /// A time string should strictly match the format string.
154  fMatch_Strict = (1 << 5), ///< eg "Y" and "1997"
155  /// A time/format string can have extra trailing format symbols,
156  /// that do not have matching symbols in the time string.
157  /// Any missed time components will be initialized by default
158  /// in the time object.
159  fMatch_ShortTime = (1 << 6), ///< eg "Y/M/D h:m:s" and "1997"
160  fMatch_ShortFormat = (1 << 7), ///< eg "Y" and "1997/07/16"
161  /// Combination of both modes above.
162  /// Note that it matches until time or format string have symbols.
163  /// It not allow unprocessed symbols left in both time and format
164  /// strings at the same time.
165  fMatch_Weak = fMatch_ShortTime | fMatch_ShortFormat,
166  /// Ignore all white spaces in the time and format strings
167  /// on the matching/parsing step (CTime only).
168  /// Use it for backward compatibility with old code only.
169  /// Don't recommended to use, can lead to odd results and incorrect
170  /// time on parsing some time strings.
171  fMatch_IgnoreSpaces = (1 << 8),
172 
173  /// Prefer "UTC" over "GMT" abbreviation for universal time.
174  /// Used for output purposes only, parsing accept both.
175  fConf_UTC = (1 << 9),
176 
177  /// Default flags
178  fDefault = 0, // fFormat_Simple | fMatch_Strict
179 
180  /// "Enum"s, used for backward compatibility. Please use flags instead.
181  eNcbiSimple = fFormat_Simple,
182  eNcbi = fFormat_Ncbi,
183  eDefault = fDefault
184  };
185  typedef unsigned int TFlags; ///< Binary OR of "EFlags"
186 
187  /// Predefined formats.
188  ///
189  /// @sa GetPredefined, CTime::SetFormat
190  enum EPredefined {
191  // ISO 8601 formats (without time zone)
192  eISO8601_Year = 0, ///< Y (eg 1997)
193  eISO8601_YearMonth = 1, ///< Y-M (eg 1997-07)
194  eISO8601_Date = 2, ///< Y-M-D (eg 1997-07-16)
195  eISO8601_DateTimeMin = 3, ///< Y-M-DTh:m (eg 1997-07-16T19:20)
196  eISO8601_DateTimeSec = 4, ///< Y-M-DTh:m:s (eg 1997-07-16T19:20:30)
197  eISO8601_DateTimeFrac = 5 ///< Y-M-DTh:m:g (eg 1997-07-16T19:20:30.1234)
198  };
199 
200  /// Default constructor.
201  CTimeFormat(void);
202 
203  /// Copy constructor.
204  CTimeFormat(const CTimeFormat& fmt);
205 
206  /// Constructor.
207  ///
208  /// @sa SetFormat
209  CTimeFormat(const char* fmt, TFlags flags = fDefault);
210 
211  /// Constructor.
212  ///
213  /// @sa SetFormat
214  CTimeFormat(const string& fmt, TFlags flags = fDefault);
215 
216  /// Assignment operator.
217  CTimeFormat& operator= (const CTimeFormat& fmt);
218 
219  /// Set the current time format.
220  ///
221  /// @param fmt
222  /// String of symbols describing the time format.
223  /// @param flags
224  /// Flags specifying how to match a time string against format string.
225  /// @sa
226  /// GetFormat, EFormat, EFlags
227  void SetFormat(const char* fmt, TFlags flags = fDefault);
228 
229  /// Set the current time format.
230  ///
231  /// @param fmt
232  /// String of symbols describing the time format.
233  /// @param flags
234  /// Flags specifying how to match a time string against format string.
235  /// @sa
236  /// GetFormat, EFormat, CTime::SetFormat, CTimeSpan::SetFormat
237  void SetFormat(const string& fmt, TFlags flags = fDefault);
238 
239  /// Get format string.
240  ///
241  /// @return
242  /// A string of symbols describing the time format.
243  /// @sa SetFormat, GetFlags
244  const string& GetString(void) const;
245 
246  /// Get format flags.
247  ///
248  /// @return
249  /// A flags specifying how to match a time string against format string.
250  /// @sa SetFormat, GetString
251  TFlags GetFlags(void) const;
252 
253  /// Check that format string is empty.
254  bool IsEmpty(void) const;
255 
256  /// Get predefined format.
257  /// @param fmt
258  /// String of symbols describing the time format.
259  /// @param fmt_type
260  /// Specify type of the format string.
261  /// @return
262  /// A time format object.
263  /// @sa EPredefined, SetFormat
264  static CTimeFormat GetPredefined(EPredefined fmt, TFlags flags = fDefault);
265 
266 public:
267  /// Return time format as string.
268  /// Note: This method added temporarily, and will be deleted soon.
269  /// @deprecated Use CTimeFormat::GetString()/GetFormat() methods instead.
270  NCBI_DEPRECATED operator string(void) const;
271 
272 private:
273  string m_Str; ///< String format.
274  TFlags m_Flags; ///< Format flags.
275 };
276 
277 
278 /////////////////////////////////////////////////////////////////////////////
279 ///
280 /// CTime --
281 ///
282 /// Defines a standard Date/Time class.
283 ///
284 /// Can be used to span time (to represent elapsed time). Can operate with
285 /// local and universal (GMT/UTC) time. The time is kept in class in
286 /// the format in which it was originally given.
287 ///
288 /// Throw exception of type CTimeException on errors.
289 ///
290 /// NOTE: Do not use local time with time span and dates < "1/1/1900"
291 /// (use universal time only!!!).
292 ///
293 /// @sa CCurrentTime, CTimeSpan
294 
296 {
297 public:
298  /// Which initial value to use for time.
299  enum EInitMode {
300  eCurrent, ///< Use current time. See also CCurrentTime.
301  eEmpty ///< Use "empty" time
302  };
303 
304  /// Which initial value to use for timezone.
305  enum ETimeZone {
306  eLocal = 1, ///< Local time
307  eUTC, ///< UTC (Universal Coordinated Time)
308  eGmt = eUTC, ///< GMT (Greenwich Mean Time)
309  };
310 
311  /// Current timezone. Used in AsString() method.
312  enum {
313  eCurrentTimeZone = -1
314  };
315 
316  /// Which format use to get name of month or week of day.
317  enum ENameFormat {
318  eFull, ///< Use full name.
319  eAbbr ///< Use abbreviated name.
320  };
321 
322  /// Month names.
323  enum EMonth {
324  eJanuary = 1,
335  eDecember
336  };
337 
338  /// Day of week names.
339  enum EDayOfWeek {
340  eSunday = 0,
346  eSaturday
347  };
348 
349  /// What time zone precision to use for adjusting daylight saving time.
350  ///
351  /// Controls when (if ever) to adjust for the daylight saving time
352  /// (only if the time is represented in local timezone format).
353  ///
354  /// NOTE: if diff between previous time value and the time
355  /// after manipulation is greater than this range, then try apply
356  /// daylight saving conversion on the result time value.
358  eNone, ///< Daylight saving not to affect time manipulations.
359  eMinute, ///< Check condition - new minute.
360  eHour, ///< Check condition - new hour.
361  eDay, ///< Check condition - new day.
362  eMonth, ///< Check condition - new month.
363  eTZPrecisionDefault = eNone
364  };
365 
366  /// Whether to adjust for daylight saving time.
367  enum EDaylight {
368  eIgnoreDaylight, ///< Ignore daylight saving time.
369  eAdjustDaylight, ///< Adjust for daylight saving time.
370  eDaylightDefault = eAdjustDaylight
371  };
372 
373  /// Constructor.
374  ///
375  /// @param mode
376  /// Whether to build time object with current time or empty
377  /// time (default).
378  /// @param tz
379  /// Whether to use local time (default) or UTC.
380  /// @param tzp
381  /// What time zone precision to use.
382  CTime(EInitMode mode = eEmpty,
383  ETimeZone tz = eLocal,
384  ETimeZonePrecision tzp = eTZPrecisionDefault);
385 
386  /// Conversion constructor for time_t representation of time.
387  ///
388  /// Construct time object from UTC time_t value.
389  /// The constructed object will be in the eUTC format.
390  ///
391  /// @param t
392  /// Time in the UTC time_t format.
393  /// @param tzp
394  /// What time zone precision to use.
395  /// @sa SetTimeT, GetTimeT
396  explicit CTime(time_t t, ETimeZonePrecision tzp = eTZPrecisionDefault);
397 
398  /// Conversion constructor for "struct tm" local time representation.
399  ///
400  /// Construct time object from "struct tm" time value.
401  /// The constructed object will be in the eLocal format.
402  ///
403  /// @param t
404  /// Time in "struct tm" format.
405  /// @param tzp
406  /// What time zone precision to use.
407  /// @sa SetTimeTM, GetTimeTM
408  CTime(const struct tm& t, ETimeZonePrecision tzp = eTZPrecisionDefault);
409 
410  /// Constructor.
411  ///
412  /// Construct time given the year, month, day, hour, minute, second,
413  /// nanosecond parts of a time value.
414  ///
415  /// @param year
416  /// Year part of time.
417  /// @param month
418  /// Month part of time. Note month starts from 1.
419  /// @param day
420  /// Day part of time. Note day starts from 1.
421  /// @param hour
422  /// Hour part of time.
423  /// @param minute
424  /// Minute part of time.
425  /// @param second
426  /// Second part of time.
427  /// @param nanosecond
428  /// Nanosecond part of time.
429  /// @param tz
430  /// Whether to use local time (default) or UTC.
431  /// @param tzp
432  /// What time zone precision to use.
433  CTime(int year, int month, int day,
434  int hour = 0, int minute = 0, int second = 0, long nanosecond = 0,
435  ETimeZone tz = eLocal,
436  ETimeZonePrecision tzp = eTZPrecisionDefault);
437 
438  /// Constructor.
439  ///
440  /// Construct date as N-th day of the year.
441  ///
442  /// @param year
443  /// Year part of date.
444  /// @param yearDayNumber
445  /// N-th day of the year.
446  /// @param tz
447  /// Whether to use local time (default) or UTC.
448  /// @param tzp
449  /// What time zone precision to use.
450  CTime(int year, int yearDayNumber,
451  ETimeZone tz = eLocal,
452  ETimeZonePrecision tzp = eTZPrecisionDefault);
453 
454  /// Explicit conversion constructor for string representation of time.
455  ///
456  /// Construct time object from string representation of time.
457  ///
458  /// @param str
459  /// String representation of time in format "fmt".
460  /// @param fmt
461  /// Format in which "str" is presented. Default value of kEmptyStr,
462  /// implies the format, that was previously setup using SetFormat()
463  /// method, or default "M/D/Y h:m:s".
464  /// @param tz
465  /// If current format contains 'Z', then objects timezone will be set to:
466  /// - eUTC if "str" has words "GMT", "UTC" or "Z" (zero UTC offset) in
467  /// the appropriate position;
468  /// - eLocal otherwise.
469  /// If current format does not contain 'Z', objects timezone
470  /// will be set to 'tz' value.
471  /// @sa AsString, operator=
472  explicit CTime(const string& str, const CTimeFormat& fmt = kEmptyStr,
473  ETimeZone tz = eLocal,
474  ETimeZonePrecision tzp = eTZPrecisionDefault);
475 
476  /// Copy constructor.
477  CTime(const CTime& t);
478 
479  /// Assignment operator.
480  CTime& operator= (const CTime& t);
481 
482  /// Assignment operator from string.
483  ///
484  /// If current format contains 'Z', then objects timezone will be set to:
485  /// - eUTC if "str" has words "GMT", "UTC" or "Z" (zero UTC offset) in
486  /// the appropriate position;
487  /// - eLocal otherwise.
488  /// If current format does not contain 'Z', objects timezone
489  /// will not be changed.
490  /// @note
491  /// This operator expect a string in the format, that was previously
492  /// set using SetFormat() method.
493  /// @sa
494  /// CTime constructor from string, AsString
495  CTime& operator= (const string& str);
496 
497  /// Set time using time_t time value.
498  ///
499  /// @param t
500  /// Time to set in time object. This is always in UTC time format, and
501  /// nanoseconds will be truncated.
502  /// @return
503  /// Time object that is set.
504  CTime& SetTimeT(const time_t t);
505 
506  /// Get time in time_t format.
507  ///
508  /// The function return the number of seconds elapsed since midnight
509  /// (00:00:00), January 1, 1970 UTC. Do not use this function if the year
510  /// is before 1970.
511  /// @return
512  /// Time in time_t format.
513  time_t GetTimeT(void) const;
514 
515  /// Get current UTC time in time_t format (with nanoseconds).
516  ///
517  /// @param sec
518  /// The function return the number of seconds elapsed since
519  /// midnight (00:00:00), January 1, 1970 UTC.
520  /// @param nanosec
521  /// Number of nanoseconds (0, if not possible to get).
522  /// @attention
523  /// Result can differs from time(NULL) due different implementation
524  /// and taking into account nanosecond part on some platforms (rounding).
525  static void GetCurrentTimeT(time_t* sec, long* nanosec = 0);
526 
527  /// Set time using "struct tm" time value.
528  ///
529  /// @param t
530  /// Time to set in time object. This time always represents a local
531  /// time in current time zone. Time object will be set to have eLocal
532  /// time format, and nanoseconds will be truncated. Note that all
533  /// significant fields in the time structure should be set and have
534  /// correct vales, otherwise exception will be thrown.
535  /// @return
536  /// Time object that is set.
537  CTime& SetTimeTM(const struct tm& t);
538 
539  /// Get time in "struct tm" format.
540  ///
541  /// @return
542  /// Time in "struct tm" format (local time).
543  struct tm GetTimeTM(void) const;
544 
545  /// Set time using database format time, TDBTimeU.
546  ///
547  /// Object's time format will always change to eLocal after call.
548  ///
549  /// @param t
550  /// Time to set in time object in TDBTimeU format.
551  /// This is always in local time format, and seconds, and nanoseconds
552  /// will be truncated.
553  /// @return
554  /// Time object that is set.
555  CTime& SetTimeDBU(const TDBTimeU& t);
556 
557  /// Set time using database format time, TDBTimeI.
558  ///
559  /// Object's time format will always change to eLocal after call.
560  ///
561  /// @param t
562  /// Time to set in time object in TDBTimeI format.
563  /// This is always in local time format, and seconds, and nanoseconds
564  /// will be truncated.
565  /// @return
566  /// Time object that is set.
567  CTime& SetTimeDBI(const TDBTimeI& t);
568 
569  /// Get time in database format time, TDBTimeU.
570  ///
571  /// @return
572  /// Time value in database format, TDBTimeU.
573  TDBTimeU GetTimeDBU(void) const;
574 
575  /// Get time in database format time, TDBTimeI.
576  ///
577  /// @return
578  /// Time value in database format TDBTimeI.
579  TDBTimeI GetTimeDBI(void) const;
580 
581  /// Make the time current in the presently active time zone.
582  CTime& SetCurrent(void);
583 
584  /// Make the time "empty",
585  CTime& Clear(void);
586 
587  /// Set the current time format.
588  ///
589  /// The default format is: "M/D/Y h:m:s".
590  /// @param fmt
591  /// An object contains string of symbols describing the time
592  /// format and its type. The following format letters have
593  /// the special meaning:
594  /// - Y = year with century
595  /// - y = year without century (00-99)
596  /// - M = month as decimal number (01-12)
597  /// - B = full month name (January-December)
598  /// - b = abbreviated month name (Jan-Dec)
599  /// - D = day as decimal number (01-31)
600  /// - d = day as decimal number (w/o 0) (1-31)
601  /// - H = hour in 12-hour format (00-12)
602  /// - h = hour in 24-hour format (00-23)
603  /// - m = minute as decimal number (00-59)
604  /// - s = second as decimal number (00-59)
605  /// - l = milliseconds as decimal number (000-999)
606  /// - r = microseconds as decimal number (000000-999999)
607  /// - S = nanosecond as decimal number (000000000-999999999)
608  /// - G = seconds and fraction part of second as double value
609  /// ("s.nnn") with floating number (1-9) of digits after dot.
610  /// - g = same as "G" but w/o leading "0" if number of seconds < 10.
611  /// - P = am/pm (AM/PM)
612  /// - p = am/pm (am/pm)
613  /// - W = full day of week name (Sunday-Saturday)
614  /// - w = abbreviated day of week name (Sun-Sat)
615  /// - Z = UTC timezone designator (GMT/UTC/Z or none)
616  ///
617  /// following available on POSIX platforms only:
618  /// - z = timezone shift ([GMT/UTC]+/-HHMM)
619  /// - o = timezone shift (+/-HH:MM)
620  ///
621  /// Format string can represent date/time partially, in this case
622  /// current time, or default values, will be used to amplify time
623  /// object, if possible. Current date/time cannot be used
624  /// if format string contains "z" (time shift) format symbol.
625  /// Also, it cannot be used if time format is ambiguous, like "Y/D".
626  /// Note, that you still can use "Y/M", or even "Y", where month and
627  /// day will be defined as 1; or "M/D", where year will be set as the
628  /// current year.
629  /// @sa
630  /// CTimeFormat, GetFormat, AsString
631  static void SetFormat(const CTimeFormat& fmt);
632 
633  /// Get the current time format.
634  ///
635  /// The default format is: "M/D/Y h:m:s".
636  /// @return
637  /// An object describing the time format.
638  /// @sa
639  /// CTimeFormat, SetFormat, AsString
640  static CTimeFormat GetFormat(void);
641 
642  /// Get numerical value of the month by name.
643  ///
644  /// @param month
645  /// Full or abbreviated month name.
646  /// @return
647  /// Numerical value of a given month (1..12).
648  /// @sa
649  /// MonthNumToName, Month
650  static int MonthNameToNum(const string& month);
651 
652  /// Get name of the month by numerical value.
653  ///
654  /// @param month
655  /// Full or abbreviated month name.
656  /// @param format
657  /// Format for returned value (full or abbreviated).
658  /// @return
659  /// Name of the month.
660  /// @sa
661  /// MonthNameToNum, Month
662  static string MonthNumToName(int month, ENameFormat format = eFull);
663 
664  /// Get numerical value of the day of week by name.
665  ///
666  /// @param day
667  /// Full or abbreviated day of week name.
668  /// @return
669  /// Numerical value of a given day of week (0..6).
670  /// @sa
671  /// DayOfWeekNumToName, DayOfWeek
672  static int DayOfWeekNameToNum(const string& day);
673 
674  /// Get name of the day of week by numerical value.
675  ///
676  /// @param day
677  /// Full or abbreviated day of week name.
678  /// @param format
679  /// Format for returned value (full or abbreviated).
680  /// @return
681  /// Name of the day of week.
682  /// @sa
683  /// DayOfWeekNameToNum, DayOfWeek
684  static string DayOfWeekNumToName(int day, ENameFormat format = eFull);
685 
686  /// Transform time to string.
687  ///
688  /// @param format
689  /// Format specifier used to convert time to string.
690  /// If "format" is not defined, then GetFormat() will be used.
691  /// @param out_tz
692  /// Output timezone. This is a difference in seconds between universal
693  /// and local time for some place (for example, for EST5 timezone
694  /// its value is 18000). This parameter works only with local time.
695  /// If the time object contains universal (GMT/UTC/Z) time it is ignored.
696  /// Before doing transformation to string, the time will be converted
697  /// to the output timezone. Timezone can be printed as a string
698  /// 'GMT/UTC/Z[+|-]HHMM' using the format symbol 'z'.
699  /// By default the current timezone is used.
700  /// @sa
701  /// GetFormat, SetFormat
702  string AsString(const CTimeFormat& format = kEmptyStr,
703  TSeconds out_tz = eCurrentTimeZone) const;
704 
705  /// Return time as string using the format returned by GetFormat().
706  operator string(void) const;
707 
708 
709  //
710  // Get various components of time.
711  //
712 
713  /// Get year.
714  ///
715  /// Year = 1900 ..
716  /// AsString() format symbols "Y", "y".
717  int Year(void) const;
718 
719  /// Get month.
720  ///
721  /// Month number = 1..12.
722  /// AsString() format symbols "M", "B", "b".
723  int Month(void) const;
724 
725  /// Get day.
726  ///
727  /// Day of the month = 1..31
728  /// AsString() format symbol "D".
729  int Day(void) const;
730 
731  /// Get hour.
732  ///
733  /// Hours since midnight = 0..23.
734  /// AsString() format symbol "h".
735  int Hour(void) const;
736 
737  /// Get minute.
738  ///
739  /// Minutes after the hour = 0..59
740  /// AsString() format symbol "m".
741  int Minute(void) const;
742 
743  /// Get second.
744  ///
745  /// Seconds after the minute = 0..59
746  /// AsString() format symbol "s".
747  int Second(void) const;
748 
749  /// Get milliseconds.
750  ///
751  /// Milliseconds after the second = 0..999
752  /// AsString() format symbol "l".
753  /// @sa
754  /// NanoSecond
755  long MilliSecond(void) const;
756 
757  /// Get microseconds.
758  ///
759  /// Microseconds after the second = 0..999999
760  /// AsString() format symbol "r".
761  /// @sa
762  /// NanoSecond
763  long MicroSecond(void) const;
764 
765  /// Get nano-seconds.
766  ///
767  /// Nano-seconds after the second = 0..999999999
768  /// AsString() format symbol "S".
769  /// @sa
770  /// MilliSecond, MicroSecond
771  long NanoSecond(void) const;
772 
773 
774  //
775  // Set various components of time.
776  //
777 
778  /// Set year.
779  ///
780  /// Beware that this operation is inherently inconsistent.
781  /// In case of different number of days in the months, the day number
782  /// can change, e.g.:
783  /// - "Feb 29 2000".SetYear(2001) => "Feb 28 2001".
784  /// Because 2001 is not leap year.
785  /// @param year
786  /// Year to set.
787  /// @sa
788  /// Year
789  void SetYear(int year);
790 
791  /// Set month.
792  ///
793  /// Beware that this operation is inherently inconsistent.
794  /// In case of different number of days in the months, the day number
795  /// can change, e.g.:
796  /// - "Dec 31 2000".SetMonth(2) => "Feb 29 2000".
797  /// Therefore e.g. calling SetMonth(1) again that result will be "Jan 28".
798  /// @param month
799  /// Month number to set. Month number = 1..12.
800  /// @sa
801  /// Month
802  void SetMonth(int month);
803 
804  /// Set day.
805  ///
806  /// Beware that this operation is inherently inconsistent.
807  /// In case of number of days in the months, the day number
808  /// can change, e.g.:
809  /// - "Feb 01 2000".SetDay(31) => "Feb 29 2000".
810  /// @param day
811  /// Day to set. Day of the month = 1..31.
812  /// @sa
813  /// Day
814  void SetDay(int day);
815 
816  /// Set hour.
817  ///
818  /// @param hour
819  /// Hours since midnight = 0..23.
820  /// @sa
821  /// Hour
822  void SetHour(int hour);
823 
824  /// Set minute.
825  ///
826  /// @param minute
827  /// Minutes after the hour = 0..59.
828  /// @sa
829  /// Minute
830  void SetMinute(int minute);
831 
832  /// Set second.
833  ///
834  /// @param second
835  /// Seconds after the minute = 0..59.
836  /// @sa
837  /// Second
838  void SetSecond(int second);
839 
840  /// Set milliseconds.
841  ///
842  /// @param millisecond
843  /// Milliseconds after the second = 0..999.
844  /// @sa
845  /// MilliSecond, SetNanoSecond
846  void SetMilliSecond(long millisecond);
847 
848  /// Set microseconds.
849  ///
850  /// @param microsecond
851  /// Microseconds after the second = 0..999999.
852  /// @sa
853  /// MicroSecond, SetNanoSecond
854  void SetMicroSecond(long microsecond);
855 
856  /// Set nanoseconds.
857  ///
858  /// @param nanosecond
859  /// Nanoseconds after the second = 0..999999999.
860  /// @sa
861  /// NanoSecond, SetMilliSecond, SetMicroSecond
862  void SetNanoSecond(long nanosecond);
863 
864  /// Get year's day number.
865  ///
866  /// Year day number = 1..366
867  int YearDayNumber(void) const;
868 
869  /// Get this date's week number within the year.
870  ///
871  /// Calculate the week number in a year of a given date.
872  /// The week can start on any day accordingly given parameter.
873  /// First week always start with 1st January.
874  /// @param week_start
875  /// What day of week is first.
876  /// Default is to use Sunday as first day of week. For Monday-based
877  /// weeks use eMonday as parameter value.
878  /// @return
879  /// Week number = 1..54.
880  int YearWeekNumber(EDayOfWeek first_day_of_week = eSunday) const;
881 
882  /// Get this date's week number in the month.
883  ///
884  /// @return
885  /// Week number in the month = 1..6.
886  /// @sa
887  /// YearWeekNumber
888  int MonthWeekNumber(EDayOfWeek first_day_of_week = eSunday) const;
889 
890  /// Get day of week.
891  ///
892  /// Days since Sunday = 0..6
893  /// AsString() format symbols "W", "w".
894  int DayOfWeek(void) const;
895 
896  /// Get number of days in the month.
897  ///
898  /// Number of days = 28..31
899  int DaysInMonth(void) const;
900 
901  /// Add specified years and adjust for daylight saving time.
902  ///
903  /// It is an exact equivalent of calling AddMonth(years * 12).
904  /// @sa
905  /// AddMonth
906  CTime& AddYear(int years = 1, EDaylight adl = eDaylightDefault);
907 
908  /// Add specified months and adjust for daylight saving time.
909  ///
910  /// Beware that this operation is inherently inconsistent.
911  /// In case of different number of days in the months, the day number
912  /// can change, e.g.:
913  /// - "Dec 31 2000".AddMonth(2) => "Feb 28 2001" ("Feb 29" if leap year).
914  /// Therefore e.g. calling AddMonth(1) 12 times for e.g. "Jul 31" will
915  /// result in "Jul 28" (or "Jul 29") of the next year.
916  /// @param months
917  /// Months to add. Default is 1 month.
918  /// If negative, it will result in a "subtraction" operation.
919  /// @param adl
920  /// Whether to adjust for daylight saving time. Default is to adjust
921  /// for daylight savings time. This parameter is for eLocal time zone
922  /// and where the time zone precision is not eNone.
923  CTime& AddMonth(int months = 1, EDaylight adl = eDaylightDefault);
924 
925  /// Add specified days and adjust for daylight saving time.
926  ///
927  /// @param days
928  /// Days to add. Default is 1 day.
929  /// If negative, it will result in a "subtraction" operation.
930  /// @param adl
931  /// Whether to adjust for daylight saving time. Default is to adjust
932  /// for daylight saving time. This parameter is for eLocal time zone
933  /// and where the time zone precision is not eNone.
934  CTime& AddDay(int days = 1, EDaylight adl = eDaylightDefault);
935 
936  /// Add specified hours and adjust for daylight saving time.
937  ///
938  /// @param hours
939  /// Hours to add. Default is 1 hour.
940  /// If negative, it will result in a "subtraction" operation.
941  /// @param adl
942  /// Whether to adjust for daylight saving time. Default is to adjust
943  /// for daylight saving time. This parameter is for eLocal time zone
944  /// and where the time zone precision is not eNone.
945  CTime& AddHour(int hours = 1, EDaylight adl = eDaylightDefault);
946 
947  /// Add specified minutes and adjust for daylight saving time.
948  ///
949  /// @param minutes
950  /// Minutes to add. Default is 1 minute.
951  /// If negative, it will result in a "subtraction" operation.
952  /// @param adl
953  /// Whether to adjust for daylight saving time. Default is to adjust
954  /// for daylight saving time. This parameter is for eLocal time zone
955  /// and where the time zone precision is not eNone.
956  CTime& AddMinute(int minutes = 1, EDaylight adl = eDaylightDefault);
957 
958  /// Add specified seconds.
959  ///
960  /// @param seconds
961  /// Seconds to add. Default is 1 second.
962  /// If negative, it will result in a "subtraction" operation.
963  CTime& AddSecond(TSeconds seconds = 1, EDaylight adl = eDaylightDefault);
964 
965  /// Add specified nanoseconds.
966  ///
967  /// @param nanoseconds
968  /// Nanoseconds to add. Default is 1 nanosecond.
969  /// If negative, it will result in a "subtraction" operation.
970  CTime& AddNanoSecond(long nanoseconds = 1);
971 
972  /// Add specified time span.
973  ///
974  /// @param timespan
975  /// Object of CTimeSpan class to add.
976  /// If negative, it will result in a "subtraction" operation.
977  CTime& AddTimeSpan(const CTimeSpan& timespan);
978 
979 
980  /// Precision for rounding time.
981  /// @sa Round, Truncate
983  eRound_Day, ///< Round to days
984  eRound_Hour, ///< Round to hours
985  eRound_Minute, ///< Round to minutes
986  eRound_Second, ///< Round to seconds
987  eRound_Millisecond, ///< Round to milliseconds
988  eRound_Microsecond ///< Round to microseconds
989  };
990 
991  /// Round time.
992  ///
993  /// Round stored time to specified precision. All time components with
994  /// precision less that specified will be zero-filled, all other
995  /// components will be adjusted accordingly to rules for rounding
996  /// numbers.
997  /// @param precision
998  /// Rounding precision.
999  /// @param adl
1000  /// Whether to adjust for daylight saving time. Default is to adjust
1001  /// for daylight saving time. This parameter is for eLocal time zone
1002  /// and where the time zone precision is not eNone.
1003  /// @sa ERoundPrecision, Truncate
1004  CTime& Round(ERoundPrecision precision = eRound_Day,
1005  EDaylight adl = eDaylightDefault);
1006 
1007  /// Truncate time.
1008  ///
1009  /// Truncate stored time to specified precision. All time components with
1010  /// precision less that specified will be zero-filled.
1011  /// By default method strips hours, minutes, seconds and nanoseconds.
1012  /// @param precision
1013  /// Truncating precision.
1014  /// @sa ERoundPrecision, Round
1015  CTime& Truncate(ERoundPrecision precision = eRound_Day);
1016 
1017 
1018  //
1019  // Add/subtract time span
1020  //
1021 
1022  // Operator to add time span.
1023  CTime& operator+= (const CTimeSpan& ts);
1024 
1025  /// Operator to subtract time span.
1026  CTime& operator-= (const CTimeSpan& ts);
1027 
1028  // Operator to add time span.
1029  CTime operator+ (const CTimeSpan& ts) const;
1030 
1031  /// Operator to subtract time span.
1032  CTime operator- (const CTimeSpan& ts) const;
1033 
1034  /// Operator to subtract times.
1035  CTimeSpan operator- (const CTime& t) const;
1036 
1037 
1038  //
1039  // Time comparison ('>' means "later", '<' means "earlier")
1040  //
1041 
1042  /// Operator to test equality of time.
1043  bool operator== (const CTime& t) const;
1044 
1045  /// Operator to test in-equality of time.
1046  bool operator!= (const CTime& t) const;
1047 
1048  /// Operator to test if time is later.
1049  bool operator> (const CTime& t) const;
1050 
1051  /// Operator to test if time is earlier.
1052  bool operator< (const CTime& t) const;
1053 
1054  /// Operator to test if time is later or equal.
1055  bool operator>= (const CTime& t) const;
1056 
1057  /// Operator to test if time is earlier or equal.
1058  bool operator<= (const CTime& t) const;
1059 
1060 
1061  //
1062  // Time difference
1063  //
1064 
1065  /// Difference in whole days from specified time.
1066  int DiffWholeDays(const CTime& t) const;
1067 
1068  /// Difference in days from specified time.
1069  double DiffDay(const CTime& t) const;
1070 
1071  /// Difference in hours from specified time.
1072  double DiffHour(const CTime& t) const;
1073 
1074  /// Difference in minutes from specified time.
1075  double DiffMinute(const CTime& t) const;
1076 
1077  /// Difference in seconds from specified time.
1078  TSeconds DiffSecond(const CTime& t) const;
1079 
1080  /// Difference in nanoseconds from specified time.
1081  double DiffNanoSecond(const CTime& t) const;
1082 
1083  /// Difference in nanoseconds from specified time.
1084  CTimeSpan DiffTimeSpan(const CTime& t) const;
1085 
1086 
1087  //
1088  // Checks
1089  //
1090 
1091  /// Is time object empty (date and time)?
1092  bool IsEmpty (void) const;
1093 
1094  /// Is date empty?
1095  bool IsEmptyDate (void) const;
1096 
1097  /// Is time in a leap year?
1098  bool IsLeap (void) const;
1099 
1100  /// Is time valid?
1101  bool IsValid (void) const;
1102 
1103  /// Is time local time?
1104  bool IsLocalTime (void) const;
1105 
1106  /// Is time universal (GMT/UTC/Z)?
1107  bool IsUniversalTime(void) const;
1108  bool IsGmtTime(void) const { return IsUniversalTime(); };
1109 
1110  /// Is DST (daylight savings time) in effect for this time?
1111  /// @note
1112  /// This method use current DST rules on current machine, so be aware
1113  /// to use it against time in the past or future, because such rules
1114  /// can be changed.
1115  bool IsDST(void) const;
1116 
1117  /// Validate if string match time format.
1118  ///
1119  /// @param str
1120  /// String representation of time.
1121  /// @param fmt
1122  /// Format that is used to check time string. Default value of kEmptyStr,
1123  /// implies the format, that was previously setup using SetFormat()
1124  /// method, or default one.
1125  /// @return
1126  /// TRUE if CTime can be initialized from "str" using format "fmt",
1127  /// FALSE otherwise.
1128  /// @sa
1129  /// CTimeFormat
1130  static bool ValidateString(const string& str, const CTimeFormat& fmt = kEmptyStr);
1131 
1132 
1133  //
1134  // Timezone functions
1135  //
1136 
1137  /// Get time zone.
1138  ETimeZone GetTimeZone(void) const;
1139  NCBI_DEPRECATED ETimeZone GetTimeZoneFormat(void) const;
1140 
1141  /// Set time zone.
1142  ETimeZone SetTimeZone(ETimeZone val);
1143  NCBI_DEPRECATED ETimeZone SetTimeZoneFormat(ETimeZone val);
1144 
1145  /// Get time zone precision.
1146  ETimeZonePrecision GetTimeZonePrecision(void) const;
1147 
1148  /// Set time zone precision.
1149  ETimeZonePrecision SetTimeZonePrecision(ETimeZonePrecision val);
1150 
1151  /// Get the time as local time.
1152  CTime GetLocalTime(void) const;
1153 
1154  /// Get the time as universal (GMT/UTC) time.
1155  CTime GetUniversalTime(void) const;
1156  CTime GetGmtTime(void) const { return GetUniversalTime(); }
1157 
1158  /// Convert the time into specified time zone time.
1159  CTime& ToTime(ETimeZone val);
1160 
1161  /// Convert the time into local time.
1162  CTime& ToLocalTime(void);
1163 
1164  /// Convert the time into universal (GMT/UTC) time.
1165  CTime& ToUniversalTime(void);
1166  CTime& ToGmtTime(void) { return ToUniversalTime(); };
1167 
1168  /// Get difference between local timezone for current time object
1169  /// and UTC in seconds.
1170  /// @deprecated Use CTime::TimeZoneOffset() instead.
1171  NCBI_DEPRECATED TSeconds TimeZoneDiff(void) const;
1172 
1173  /// Get difference between local timezone for current time object
1174  /// and UTC in seconds.
1175  TSeconds TimeZoneOffset(void) const;
1176 
1177  /// Get time zone offset string in format [+/-]HHMM.
1178  /// @sa TimeZoneName, TimeZoneOffset
1179  string TimeZoneOffsetStr(void);
1180 
1181  /// Get current time zone name.
1182  ///
1183  /// @return
1184  /// String with time zone name for current time, if supported by OS,
1185  /// or empty string otherwise. This name can be any one of 3-letter
1186  /// abbreviated code or some arbitrary string, depending on OS.
1187  /// @sa
1188  /// TimeZoneOffset, TimeZoneOffsetStr
1189  string TimeZoneName(void);
1190 
1191 private:
1192  /// Defines how to behave on error
1193  enum EErrAction {
1194  eErr_Throw, ///< Throw an exception on error
1195  eErr_NoThrow ///< Return default value on error
1196  };
1197 
1198  /// Helper method to set time value from string "str" using format "fmt".
1199  bool x_Init(const string& str, const CTimeFormat& fmt,
1200  EErrAction err_action = eErr_Throw);
1201 
1202  /// Helper method to set time from 'time_t' -- If "t" not specified,
1203  /// then set to current time.
1204  CTime& x_SetTime(const time_t* t = 0);
1205 
1206  /// Version of x_SetTime() with MT-safe locks
1207  CTime& x_SetTimeMTSafe(const time_t* t = 0);
1208 
1209  /// Helper method to adjust day number to correct value after day
1210  /// manipulations.
1211  void x_AdjustDay(void);
1212 
1213  /// Helper method to adjust the time to correct timezone (across the
1214  /// barrier of winter & summer times) using "from" as a reference point.
1215  ///
1216  /// This does the adjustment only if the time object:
1217  /// - contains local time, and
1218  /// - has TimeZonePrecision != CTime::eNone, and
1219  /// - differs from "from" in the TimeZonePrecision (or larger) part.
1220  CTime& x_AdjustTime(const CTime& from, bool shift_time = true);
1221 
1222  /// Helper method to forcibly adjust timezone using "from" as a
1223  /// reference point.
1224  CTime& x_AdjustTimeImmediately(const CTime& from, bool shift_time = true);
1225 
1226  /// Helper method to check if there is a need adjust time in timezone.
1227  bool x_NeedAdjustTime(void) const;
1228 
1229  /// Helper method to add hour with/without shift time.
1230  /// Parameter "shift_time" access or denied use time shift in
1231  /// process adjust hours.
1232  CTime& x_AddHour(int hours = 1, EDaylight daylight = eDaylightDefault,
1233  bool shift_time = true);
1234 
1235 private:
1236 #if defined(NCBI_COMPILER_WORKSHOP) && defined(__x86_64) && NCBI_COMPILER_VERSION < 590
1237 // Work around some WorkShop versions' incorrect handling of bitfields
1238 // when compiling for x86-64 (at least with optimization enabled) by
1239 // not using them at all. :-/
1240 # define NCBI_TIME_BITFIELD(n)
1241 # define NCBI_TIME_EMPTY_BITFIELD
1242 #else
1243 # define NCBI_TIME_BITFIELD(n) : n
1244 # define NCBI_TIME_EMPTY_BITFIELD unsigned : 0;
1245 #endif
1246  typedef struct {
1247  // Time
1248  unsigned int year NCBI_TIME_BITFIELD(12); // 4 digits
1249  unsigned char month NCBI_TIME_BITFIELD( 4); // 0..12
1250  unsigned char day NCBI_TIME_BITFIELD( 5); // 0..31
1251  unsigned char hour NCBI_TIME_BITFIELD( 5); // 0..23
1252  unsigned char min NCBI_TIME_BITFIELD( 6); // 0..59
1253  unsigned char sec NCBI_TIME_BITFIELD( 6); // 0..61
1254  // Difference between universal and local times in seconds,
1255  // as stored during the last call to x_AdjustTime***().
1256  Int4 adjTimeDiff NCBI_TIME_BITFIELD(18);
1257  // Timezone and precision
1258  ETimeZone tz NCBI_TIME_BITFIELD(3); // local/universal
1259  ETimeZonePrecision tzprec NCBI_TIME_BITFIELD(4); // Time zone precision
1260  NCBI_TIME_EMPTY_BITFIELD // Force alignment
1262  } TData;
1263  TData m_Data; ///< Packed members
1264 
1265  // Friend class
1266  friend class CFastLocalTime;
1267 };
1268 
1269 
1270 /////////////////////////////////////////////////////////////////////////////
1271 ///
1272 /// CCurrentTime --
1273 ///
1274 /// Defines a wrapper for CTime class to represent a current time.
1275 ///
1276 /// Getting current time is one of the most used operation with CTime,
1277 /// this wrapper allow to do it a bit easier and have cleaner code.
1278 /// If necessary, it allow to use any other CTime methods.
1279 ///
1280 /// @sa CTime
1281 
1283 {
1284 public:
1285  /// Constructor.
1286  ///
1287  /// @param tz
1288  /// Whether to use local time (default, CTime::eLocal) or Universal Coordinated Time (CTime::eUTC).
1289  CCurrentTime(ETimeZone tz = eLocal)
1290  : CTime(eCurrent, tz)
1291  {};
1292 
1293  /// Update current time.
1295  {
1296  SetCurrent();
1297  return *this;
1298  };
1299 };
1300 
1301 
1302 /////////////////////////////////////////////////////////////////////////////
1303 ///
1304 /// CTimeSpan
1305 ///
1306 /// Defines a class to represents a relative time span.
1307 /// Time span can be both positive and negative and hold value in range
1308 /// [LONG_MIN - LONG_MAX] seconds (a little more than 68 years in each direction).
1309 ///
1310 /// Throw exception of type CTimeException on errors.
1311 
1313 {
1314 public:
1315  /// Default constructor.
1316  CTimeSpan(void);
1317 
1318  /// Constructor.
1319  ///
1320  /// Construct time span given the number of days, hours, minutes, seconds,
1321  /// nanoseconds parts of a time span value.
1322  /// @param days
1323  /// Day part of time. Note day starts from 1.
1324  /// @param hours
1325  /// Hour part of time.
1326  /// @param minutes
1327  /// Minute part of time.
1328  /// @param seconds
1329  /// Second part of time.
1330  /// @param nanoseconds
1331  /// Nanosecond part of time.
1332  CTimeSpan(long days, long hours, long minutes, long seconds,
1333  long nanoseconds = 0);
1334 
1335  /// Constructor.
1336  ///
1337  /// Construct time span given the number of seconds and nanoseconds.
1338  /// @param seconds
1339  /// Second part of time.
1340  /// @param nanoseconds
1341  /// Nanosecond part of time.
1342  explicit CTimeSpan(long seconds, long nanoseconds = 0);
1343 
1344  /// Constructor.
1345  ///
1346  /// Construct time span from number of seconds.
1347  /// Please, use this constructor as rarely as possible, because after
1348  /// doing some arithmetical operations and conversion with it,
1349  /// the time span can differ at some nanoseconds from expected value.
1350  /// @param seconds
1351  /// Second part of time. The fractional part is used to compute
1352  /// nanoseconds.
1353  explicit CTimeSpan(double seconds);
1354 
1355  /// Explicit conversion constructor for string representation of time span.
1356  ///
1357  /// Construct time span object from string representation of time.
1358  ///
1359  /// @param str
1360  /// String representation of time span in format "fmt".
1361  /// @param fmt
1362  /// Format in which "str" is presented. Default value of kEmptyStr,
1363  /// implies the format set with SetFormat(), or "-G" if SetFormat()
1364  /// has not used before.
1365  /// @sa SetFormat
1366  explicit CTimeSpan(const string& str, const CTimeFormat& fmt = kEmptyStr);
1367 
1368  /// Copy constructor.
1369  CTimeSpan(const CTimeSpan& t);
1370 
1371  /// Assignment operator.
1372  CTimeSpan& operator= (const CTimeSpan& t);
1373 
1374  /// Assignment operator.
1375  CTimeSpan& operator= (const string& str);
1376 
1377  /// Make the time span "empty",
1378  CTimeSpan& Clear(void);
1379 
1380  /// Get sign of time span.
1381  ESign GetSign(void) const;
1382 
1383  /// Set the current time span format.
1384  ///
1385  /// The default format is: "-S.n".
1386  /// @param format
1387  /// An object contains string of letters describing the time
1388  /// format and its type. The format letters have
1389  /// the following meanings:
1390  /// - - = add minus for negative time spans
1391  /// - d = number of whole days
1392  /// - H = total whole number of hours stored in the time span
1393  /// - h = hours, "H" modulo 24 (-23 - 23)
1394  /// - M = total whole number of minutes stored in the time span
1395  /// - m = minutes, "M" modulo 60 (-59 - 59)
1396  /// - S = total whole number of seconds stored in the time span
1397  /// - s = seconds, "S" modulo 60 (-59 - 59)
1398  /// - N = total whole number of nanoseconds stored in the time span
1399  /// - n = nanoseconds (-999999999 - 999999999)
1400  /// - G = total whole number of seconds and part of second as double value
1401  /// ("S.n") with floating number (1-9) of digits after dot.
1402  /// - g = seconds, "S" modulo 60 and part of second as double value
1403  /// ("s.n") with floating number (1-9) of digits after dot.
1404  /// @sa
1405  /// CTimeFormat, GetFormat, AsString
1406  static void SetFormat(const CTimeFormat& format);
1407 
1408  /// Get the current time span format.
1409  ///
1410  /// If SetFormat() has not used before, that default formats are:
1411  /// "-S.n" - to output with AsString();
1412  /// "-G" - to initialize from string.
1413  /// @return
1414  /// An object describing the time format.
1415  /// @sa
1416  /// CTimeFormat, SetFormat, AsString
1417  static CTimeFormat GetFormat(void);
1418 
1419  /// Transform time span to string.
1420  ///
1421  /// @param fmt
1422  /// Format specifier used to convert time span to string.
1423  /// If format is not defined, then GetFormat() will be used.
1424  /// @return
1425  /// A string representation of time span in specified format.
1426  /// @sa
1427  /// CTimeFormat, GetFormat, SetFormat
1428  string AsString(const CTimeFormat& fmt = kEmptyStr) const;
1429 
1430  /// Return span time as string using the format returned by GetFormat().
1431  operator string(void) const;
1432 
1433 
1434  /// AsSmartString() conversion flags.
1435  ///
1436  /// @attention
1437  /// Use one flag in each group only, or CTimeException exception
1438  /// will be thrown. If not specified otherwise default value will be used.
1439  /// @sa AsSmartString
1441  /// @note precision
1442  /// Flags describing how many parts of time span should be
1443  /// returned.
1444  /// - Values from fSS_Year to fSS_Nanosecond apparently
1445  /// describe part of time span which will be last in output string.
1446  /// - Floating precision levels fSS_PrecisionN say that only up to 'N'
1447  /// of most significant parts of time span will be printed.
1448  /// The parts counting begin from first non-zero value.
1449  /// - fSS_Smart is default, it tries to represent time span as close
1450  /// and short as possible, usually using only one or two most
1451  /// significant non-zero parts of the time span.
1452  fSS_Year = (1 << 0), ///< Round to years
1453  fSS_Month = (1 << 1), ///< Round to months
1454  fSS_Day = (1 << 2), ///< Round to days
1455  fSS_Hour = (1 << 3), ///< Round to hours
1456  fSS_Minute = (1 << 4), ///< Round to minutes
1457  fSS_Second = (1 << 5), ///< Round to seconds
1458  fSS_Millisecond = (1 << 6), ///< Round to milliseconds
1459  fSS_Microsecond = (1 << 7), ///< Round to microseconds
1460  fSS_Nanosecond = (1 << 8), ///< Do not round at all (accurate time span)
1461  fSS_Precision1 = (1 << 9), ///< Floating precision level 1
1462  fSS_Precision2 = (1 << 10), ///< Floating precision level 2
1463  fSS_Precision3 = (1 << 11), ///< Floating precision level 3
1464  fSS_Precision4 = (1 << 12), ///< Floating precision level 4
1465  fSS_Precision5 = (1 << 13), ///< Floating precision level 5
1466  fSS_Precision6 = (1 << 14), ///< Floating precision level 6
1467  fSS_Precision7 = (1 << 15), ///< Floating precision level 7
1468  fSS_Smart = (1 << 16), ///< Be as smart as possible (see above)
1469  fSS_PrecisionMask = 0x1FFFF, ///< Mask of precision flags (sum of all above)
1470 
1471  /// @note rounding
1472  /// Rounding flags. By default time span will be truncated at last value
1473  /// specified by precision. If fSS_Round specified, that time span will be
1474  /// arithmetically rounded by precision level.
1475  fSS_Round = (1 << 20),
1476  fSS_Trunc = (1 << 21),
1477 
1478  /// @note zero parts
1479  /// Flags to print or skip zero parts of time span which should be
1480  /// printed but have 0 value. Apply to middle and trailing zero parts
1481  /// of time span only. Leading zeros will be ignored in common case
1482  /// in any mode, they can be printed only if it is impossible
1483  /// to represent time span otherwise.
1484  /// @attention
1485  /// fSS_NoSkipZero is not compatible with fSS_Smart (exception will be thrown).
1486  fSS_NoSkipZero = (1 << 22),
1487  fSS_SkipZero = (1 << 23),
1488 
1489  /// @note naming
1490  /// Specify what kind of names use for output time components,
1491  /// short standard abbreviations for time component like "m",
1492  /// or full "minutes".
1493  fSS_Short = (1 << 24),
1494  fSS_Full = (1 << 25),
1495 
1496  /// Default flags
1497  fSS_Default = 0 // fSS_Smart | fSS_Trunc | fSS_SkipZero | fSS_Full
1498  };
1499  typedef unsigned int TSmartStringFlags; ///< Binary OR of "ESmartStringFlags"
1500 
1501  /// Precision for span "smart" string. Used in AsSmartString() method.
1502  /// @deprecated Use ESmartStringFlags instead
1504  // Named precision levels
1505  eSSP_Year = fSS_Year,
1506  eSSP_Month = fSS_Month,
1507  eSSP_Day = fSS_Day,
1508  eSSP_Hour = fSS_Hour,
1509  eSSP_Minute = fSS_Minute,
1510  eSSP_Second = fSS_Second,
1511  eSSP_Millisecond = fSS_Millisecond,
1512  eSSP_Microsecond = fSS_Microsecond,
1513  eSSP_Nanosecond = fSS_Nanosecond,
1514  eSSP_Precision1 = fSS_Precision1,
1515  eSSP_Precision2 = fSS_Precision2,
1516  eSSP_Precision3 = fSS_Precision3,
1517  eSSP_Precision4 = fSS_Precision4,
1518  eSSP_Precision5 = fSS_Precision5,
1519  eSSP_Precision6 = fSS_Precision6,
1520  eSSP_Precision7 = fSS_Precision7,
1521  eSSP_Smart = fSS_Smart
1522  };
1523 
1524  /// Which format use to output zero time span parts.
1525  /// @deprecated Use ESmartStringFlags instead
1527  eSSZ_NoSkipZero = fSS_NoSkipZero, ///< Print zero valued parts
1528  eSSZ_SkipZero = fSS_SkipZero ///< Skip zero valued parts
1529  };
1530 
1531  /// Transform time span to "smart" string.
1532  ///
1533  /// @deprecated Use AsSmartString(TSmartStringFlags) instead.
1535  string AsSmartString(ESmartStringPrecision precision,
1536  ERound rounding,
1537  ESmartStringZeroMode zero_mode = eSSZ_SkipZero) const;
1538 
1539  /// Transform time span to "smart" string.
1540  ///
1541  /// @param flags
1542  /// How to convert string to value.
1543  /// @return
1544  /// A string representation of time span.
1545  /// It MUST NOT be negative, or an exception will be thrown!
1546  /// @sa
1547  /// AssignFromSmartString, AsString, ESmartStringFlags
1548  /// @note
1549  /// For very big time spans it use the average length of the year
1550  /// in the Gregorian (modern) calendar (365.2425 days)
1551  /// to calculate number of months and years.
1552  string AsSmartString(TSmartStringFlags flags = 0) const;
1553 
1554  /// Assign value to time span object from string representation of time
1555  /// in formats produced by AsSmartString().
1556  ///
1557  /// @param str
1558  /// String representation of time span in the format produced by AsSmartString().
1559  /// All numeric time parts should have letter/word specifiers.
1560  /// The string should represent "positive" timespan, the sign (minus)
1561  /// is not allowed there.
1562  /// @sa
1563  /// AsSmartString
1564  /// @note
1565  /// It use the average length of the year in the Gregorian (modern)
1566  /// calendar (365.2425 days) to convert years and months.
1567  CTimeSpan& AssignFromSmartString(const string& str);
1568 
1569 
1570  //
1571  // Get various components of time span.
1572  //
1573 
1574  /// Get number of complete days.
1575  long GetCompleteDays(void) const;
1576 
1577  /// Get number of complete hours.
1578  long GetCompleteHours(void) const;
1579 
1580  /// Get number of complete minutes.
1581  long GetCompleteMinutes(void) const;
1582 
1583  /// Get number of complete seconds.
1584  long GetCompleteSeconds(void) const;
1585 
1586  /// Get number of nanoseconds.
1587  long GetNanoSecondsAfterSecond(void) const;
1588 
1589  /// Return time span as number of seconds.
1590  ///
1591  /// @return
1592  /// Return representative of time span as type double.
1593  /// The fractional part represents nanoseconds part of time span.
1594  /// The double representation of the time span is aproximate.
1595  double GetAsDouble(void) const;
1596 
1597  /// Return TRUE is an object keep zero time span.
1598  bool IsEmpty(void) const;
1599 
1600  //
1601  // Set time span
1602  //
1603 
1604  /// Set time span in seconds and nanoseconds.
1605  void Set(long seconds, long nanoseconds = 0);
1606 
1607  /// Set time span from number of seconds (fractional value).
1608  void Set(double seconds);
1609 
1610  //
1611  // Arithmetic
1612  //
1613 
1614  // Operator to add time span.
1615  CTimeSpan& operator+= (const CTimeSpan& t);
1616 
1617  // Operator to add time span.
1618  CTimeSpan operator+ (const CTimeSpan& t) const;
1619 
1620  /// Operator to subtract time span.
1621  CTimeSpan& operator-= (const CTimeSpan& t);
1622 
1623  /// Operator to subtract time span.
1624  CTimeSpan operator- (const CTimeSpan& t) const;
1625 
1626  /// Unary operator "-" (minus) to change time span sign.
1627  CTimeSpan operator- (void) const;
1628 
1629  /// Invert time span. Changes time span sign.
1630  void Invert(void);
1631 
1632  //
1633  // Comparison
1634  //
1635 
1636  /// Operator to test equality of time span.
1637  bool operator== (const CTimeSpan& t) const;
1638 
1639  /// Operator to test in-equality of time span.
1640  bool operator!= (const CTimeSpan& t) const;
1641 
1642  /// Operator to test if time span is greater.
1643  bool operator> (const CTimeSpan& t) const;
1644 
1645  /// Operator to test if time span is less.
1646  bool operator< (const CTimeSpan& t) const;
1647 
1648  /// Operator to test if time span is greater or equal.
1649  bool operator>= (const CTimeSpan& t) const;
1650 
1651  /// Operator to test if time span is less or equal.
1652  bool operator<= (const CTimeSpan& t) const;
1653 
1654 private:
1655  /// Get hour.
1656  /// Hours since midnight = -23..23
1657  int x_Hour(void) const;
1658 
1659  /// Get minute.
1660  /// Minutes after the hour = -59..59
1661  int x_Minute(void) const;
1662 
1663  /// Get second.
1664  /// Seconds after the minute = -59..59
1665  int x_Second(void) const;
1666 
1667  /// Helper method to set time value from string "str" using format "fmt".
1668  void x_Init(const string& str, const CTimeFormat& fmt);
1669 
1670  /// Helper method to normalize stored time value.
1671  void x_Normalize(void);
1672 
1673  /// Helpers for AsSmartString()
1674  string x_AsSmartString_Smart_Big(TSmartStringFlags flags) const;
1675  string x_AsSmartString_Smart_Small(TSmartStringFlags flags) const;
1676  string x_AsSmartString_Precision(TSmartStringFlags flags) const;
1677 
1678 private:
1679  long m_Sec; ///< Seconds part of the time span
1680  long m_NanoSec; ///< Nanoseconds after the second
1681 };
1682 
1683 
1684 
1685 /////////////////////////////////////////////////////////////////////////////
1686 ///
1687 /// CTimeout -- Timeout interval
1688 ///
1689 /// @sa CNanoTimeout, STimeout, CConnTimeout, CTimeSpan
1690 /// @note Throw exception of type CTimeException on errors.
1691 
1693 {
1694 public:
1695  /// Type of timeouts.
1696  enum EType {
1697  eFinite, ///< A finite timeout value has been set.
1698  eDefault, ///< Default timeout (to be interpreted by the client code)
1699  eInfinite, ///< Infinite timeout.
1700  eZero ///< Zero timeout, equal to CTimeout(0,0).
1701  };
1702 
1703  /// Create default timeout.
1704  CTimeout(void);
1705 
1706  /// Create timeout of specified type.
1707  CTimeout(EType type);
1708 
1709  /// Initialize timeout from CTimeSpan.
1710  CTimeout(const CTimeSpan& ts);
1711 
1712  /// Initialize timeout in seconds and microseconds.
1713  /// @note
1714  /// Use CNanoTimeout ctor to initialize with (seconds and) nanoseconds
1715  /// @sa CNanoTimeout
1716  CTimeout(unsigned int sec, unsigned int usec);
1717 
1718  /// Initialize timeout from number of seconds (fractional value).
1719  explicit CTimeout(double sec);
1720 
1721  /// Destructor.
1722  ~CTimeout(void) {}
1723 
1724  // Check on special timeout values.
1725  bool IsDefault() const;
1726  bool IsInfinite() const;
1727  bool IsZero() const;
1728  /// Check if timeout holds a numeric value.
1729  bool IsFinite() const;
1730 
1731  //
1732  // Get timeout
1733  //
1734 
1735  /// Get as number of milliseconds.
1736  unsigned long GetAsMilliSeconds(void) const;
1737 
1738  /// Get as number of seconds (fractional value).
1739  double GetAsDouble(void) const;
1740 
1741  /// Convert to CTimeSpan.
1742  CTimeSpan GetAsTimeSpan(void) const;
1743 
1744  /// Get timeout in seconds and microseconds.
1745  void Get(unsigned int *sec, unsigned int *microsec) const;
1746 
1747  /// Get timeout in seconds and nanoseconds.
1748  void GetNano(unsigned int *sec, unsigned int *nanosec) const;
1749 
1750 
1751  //
1752  // Set timeout
1753  //
1754 
1755  /// Set special value.
1756  void Set(EType type);
1757 
1758  /// Set timeout in seconds and microseconds.
1759  void Set(unsigned int sec, unsigned int microsec);
1760 
1761  /// Set timeout in seconds and nanoseconds.
1762  void SetNano(unsigned int sec, unsigned int nanosec);
1763 
1764  /// Set timeout from number of seconds (fractional value).
1765  void Set(double sec);
1766 
1767  /// Set from CTimeSpan.
1768  void Set(const CTimeSpan& ts);
1769 
1770  //
1771  // Comparison.
1772  // eDefault special value cannot be compared with any value.
1773  //
1774 
1775  /// Operator to test equality of timeouts.
1776  bool operator== (const CTimeout& t) const;
1777 
1778  /// Operator to test in-equality of timeouts.
1779  bool operator!= (const CTimeout& t) const;
1780 
1781  /// Operator to test if timeout is greater.
1782  bool operator> (const CTimeout& t) const;
1783 
1784  /// Operator to test if timeout is less.
1785  bool operator< (const CTimeout& t) const;
1786 
1787  /// Operator to test if timeout is greater or equal.
1788  bool operator>= (const CTimeout& t) const;
1789 
1790  /// Operator to test if timeout is less or equal.
1791  bool operator<= (const CTimeout& t) const;
1792 
1793 private:
1794  EType m_Type; ///< Type of timeout.
1795  unsigned int m_Sec; ///< Seconds part of the timeout.
1796  unsigned int m_NanoSec; ///< Nanoseconds part of the timeout.
1797 };
1798 
1799 
1800 
1801 /////////////////////////////////////////////////////////////////////////////
1802 ///
1803 /// CNanoTimeout -- Timeout interval, using nanoseconds
1804 ///
1805 /// @sa CTimeout, STimeout, CConnTimeout, CTimeSpan
1806 /// @note Throw exception of type CTimeException on errors.
1807 
1808 
1810 {
1811 public:
1812  CNanoTimeout(unsigned int seconds, unsigned int nanoseconds)
1813  : CTimeout() {
1814  SetNano(seconds, nanoseconds);
1815  }
1816 };
1817 
1818 
1819 
1820 /////////////////////////////////////////////////////////////////////////////
1821 ///
1822 /// CDeadline
1823 ///
1824 /// Given a relative timeout, compose the absolute time mark
1825 /// by adding the timeout to the current time.
1826 ///
1827 /// @sa CTimeout
1828 
1830 {
1831 public:
1832  /// Type of special deadlines.
1833  enum EType : unsigned {
1834  eInfinite = numeric_limits<unsigned>::max(), ///< Infinite deadline.
1835  eNoWait = 0u, ///< No-wait, expires immediately.
1836  };
1837  /// Initialize deadline of specified type.
1838  CDeadline(EType type = eNoWait);
1839 
1840  /// Initialize deadline using seconds and nanoseconds
1841  /// (adding to the current time)
1842  /// @param seconds
1843  /// Number of seconds to add to the current time
1844  /// @param nanoseconds
1845  /// Number of nanoseconds to add to the current time
1846  CDeadline(unsigned int rel_seconds, unsigned int rel_nanoseconds = 0);
1847 
1848  /// Initialize deadline by adding relative timeout to the current time.
1849  CDeadline(const CTimeout& timeout);
1850 
1851  /// Check if the deadline is infinite.
1852  bool IsInfinite(void) const { return m_Infinite; }
1853 
1854  /// Check if the deadline is expired.
1855  bool IsExpired(void) const
1856  { return !IsInfinite() && GetRemainingTime().IsZero(); }
1857 
1858  /// Get the number of seconds and nanoseconds (since 1/1/1970).
1859  /// Throw an exception if the deadline is infinite.
1860  void GetExpirationTime(time_t* sec, unsigned int* nanosec) const;
1861 
1862  /// Get time left to the expiration.
1863  CNanoTimeout GetRemainingTime(void) const;
1864 
1865  /// Compare two CDeadline values.
1866  bool operator < (const CDeadline& right_hand_operand) const;
1867 
1868 private:
1870 
1871  void x_SetNowPlus(unsigned int seconds, unsigned int nanoseconds);
1872 
1873  time_t m_Seconds;
1874  unsigned int m_Nanoseconds;
1876 };
1877 
1878 
1879 /// @deprecated Use CDeadline instead
1881 
1882 
1883 
1884 /////////////////////////////////////////////////////////////////////////////
1885 ///
1886 /// CFastLocalTime --
1887 ///
1888 /// Define a class for quick and dirty getting a local time.
1889 ///
1890 /// Getting local time may trigger request to a time server daemon,
1891 /// thus potentially causing a relatively significant delay,
1892 /// so we 'll need a caching local timer.
1893 
1895 {
1896 public:
1897  /// Constructor.
1898  /// It should not try to get local time from OS more often than once
1899  /// an hour. Default: check once, 5 seconds after each hour.
1900  CFastLocalTime(unsigned int sec_after_hour = 5);
1901 
1902  /// Get local time
1903  CTime GetLocalTime(void);
1904 
1905  /// Get difference in seconds between UTC and current local time
1906  /// (daylight information included)
1907  int GetLocalTimezone(void);
1908 
1909  /// Do unscheduled check
1910  void Tuneup(void);
1911 
1912 private:
1913  /// Internal version of Tuneup()
1914  bool x_Tuneup(time_t timer, long nanosec);
1915 
1916 private:
1917  unsigned int m_SecAfterHour; ///< Time interval in seconds after hour
1918  ///< in which we should avoid to do Tuneup().
1919  CTime m_LocalTime; ///< Current local time
1920  CTime m_TunedTime; ///< Last tuned time (changed by Tuneup())
1921 
1922  time_t m_LastTuneupTime; ///< Last Tuneup() time
1923  time_t m_LastSysTime; ///< Last system time
1924  int m_Timezone; ///< Cached timezone adjustment for local time
1925  int m_Daylight; ///< Cached system daylight information
1926  void* volatile m_IsTuneup;///< (bool) Tuneup() in progress (MT)
1927 };
1928 
1929 
1930 /////////////////////////////////////////////////////////////////////////////
1931 ///
1932 /// CStopWatch --
1933 ///
1934 /// Define a stop watch class to measure elapsed time.
1935 
1937 {
1938 public:
1939  /// Defines how to create new timer.
1940  enum EStart {
1941  eStart, ///< Start timer immediately after creating.
1942  eStop ///< Do not start timer, just create it.
1943  };
1944 
1945  /// Constructor.
1946  /// NB. By default ctor doesn't start timer, it merely creates it.
1947  CStopWatch(EStart state = eStop);
1948 
1949  /// Constructor.
1950  /// Start timer if argument is true.
1951  /// @deprecated Use CStopWatch(EStat) constructor instead.
1952  NCBI_DEPRECATED_CTOR(CStopWatch(bool start));
1953 
1954  /// Start the timer.
1955  /// Do nothing if already started.
1956  void Start(void);
1957 
1958  /// Return time elapsed since first Start() or last Restart() call
1959  /// (in seconds).
1960  /// Result is 0.0 if Start() or Restart() wasn't previously called.
1961  double Elapsed(void) const;
1962 
1963  /// Suspend the timer.
1964  /// Next Start() call continue to count time accured before.
1965  void Stop(void);
1966 
1967  /// Return time elapsed since first Start() or last Restart() call
1968  /// (in seconds). Start new timer after that.
1969  /// Result is 0.0 if Start() or Restart() wasn't previously called.
1970  double Restart(void);
1971 
1972  /// Stop (if running) and reset the timer.
1973  void Reset(void);
1974 
1975  /// Check state of stopwatch.
1976  /// @return
1977  /// TRUE if stopwatch is "running", FALSE otherwise.
1978  /// @sa
1979  /// Start, Stop
1980  bool IsRunning(void) const;
1981 
1982  /// Set the current stopwatch time format.
1983  ///
1984  /// The default format is: "S.n".
1985  /// @param fmt
1986  /// Format specifier used to convert time span to string.
1987  /// If format is not defined, then GetFormat() will be used.
1988  /// Uses the same time format as CTimeSpan class.
1989  /// @sa
1990  /// CTimeFormat, CTimeSpan::SetFormat, AsString
1991  static void SetFormat(const CTimeFormat& fmt);
1992 
1993  /// Get the current stopwatch time format.
1994  ///
1995  /// The default format is: "S.n".
1996  /// @return
1997  /// An object describing the time format.
1998  /// The letters having the same means that for CTimeSpan.
1999  /// @sa
2000  /// CTimeFormat, CTimeSpan::GetFormat, AsString
2001  static CTimeFormat GetFormat(void);
2002 
2003  /// Transform stopwatch time to string.
2004  ///
2005  /// According to used OS, the double representation can provide much
2006  /// finer grained time control. The string representation is limited
2007  /// by nanoseconds.
2008  /// @param fmt
2009  /// If format is not defined, then GetFormat() will be used.
2010  /// Format specifier used to convert value returned by Elapsed()
2011  /// to string.
2012  /// @sa
2013  /// CTimeSpan::AsString, CTimeFormat, Elapsed, GetFormat, SetFormat
2014  string AsString(const CTimeFormat& fmt = kEmptyStr) const;
2015 
2016  /// Return stopwatch time as string using the format returned
2017  /// by GetFormat().
2018  operator string(void) const;
2019 
2020  /// Transform elapsed time to "smart" string.
2021  ///
2022  /// For more details see CTimeSpan::AsSmartString().
2023  /// @param precision
2024  /// Enum value describing how many parts of time span should be
2025  /// returned.
2026  /// @param rounding
2027  /// Rounding mode.
2028  /// @param zero_mode
2029  /// Mode to print or skip zero parts of time span.
2030  /// @return
2031  /// A string representation of elapsed time span.
2032  /// @sa
2033  /// CTimeSpan::AsSmartString, AsString, Elapsed
2034  /// @deprecated Use AsSmartString(TSmartStringFlags) instead.
2036  string AsSmartString(
2038  ERound rounding,
2040  const;
2041 
2042  /// Transform elapsed time to "smart" string.
2043  ///
2044  /// For more details see CTimeSpan::AsSmartString().
2045  /// @param flags
2046  /// How to convert string to value.
2047  /// @return
2048  /// A string representation of elapsed time span.
2049  /// @sa
2050  /// CTimeSpan::AsSmartString, AsString, Elapsed
2051  string AsSmartString(CTimeSpan::TSmartStringFlags flags = 0) const;
2052 
2053 protected:
2054  /// Get current time mark.
2055  static double GetTimeMark();
2056 
2057 private:
2058  double m_Start; ///< Start time value.
2059  double m_Total; ///< Accumulated elapsed time.
2060  EStart m_State; ///< Stopwatch state (started/stopped)
2061 };
2062 
2063 
2064 
2065 /////////////////////////////////////////////////////////////////////////////
2066 ///
2067 /// CTimeException --
2068 ///
2069 /// Define exceptions generated by Time API.
2070 ///
2071 /// CTimeException inherits its basic functionality from CCoreException
2072 /// and defines additional error codes.
2073 
2075 {
2076 public:
2077  /// Error types that CTime can generate.
2078  enum EErrCode {
2079  eArgument, ///< Bad function argument.
2080  eConvert, ///< Error converting value from one format to another.
2081  eInvalid, ///< Invalid time value.
2082  eFormat ///< Incorrect format.
2083  };
2084 
2085  /// Translate from the error code value to its string representation.
2086  virtual const char* GetErrCodeString(void) const override;
2087 
2088  // Standard exception boilerplate code.
2090 };
2091 
2092 
2093 /* @} */
2094 
2095 
2096 
2097 //=============================================================================
2098 //
2099 // Extern
2100 //
2101 //=============================================================================
2102 
2103 /// Quick and dirty getter of local time.
2104 /// Use global object of CFastLocalTime class to obtain time.
2105 /// See CFastLocalTime for details.
2107 extern CTime GetFastLocalTime(void);
2108 
2110 extern void TuneupFastLocalTime(void);
2111 
2112 
2113 //=============================================================================
2114 //
2115 // Inline
2116 //
2117 //=============================================================================
2118 
2119 // Add (subtract if negative) to the time (see CTime::AddXXX)
2120 
2121 inline
2122 CTime AddYear(const CTime& t, int years = 1)
2123 {
2124  CTime tmp(t);
2125  return tmp.AddYear(years);
2126 }
2127 
2128 inline
2129 CTime AddMonth(const CTime& t, int months = 1)
2130 {
2131  CTime tmp(t);
2132  return tmp.AddMonth(months);
2133 }
2134 
2135 inline
2136 CTime AddDay(const CTime& t, int days = 1)
2137 {
2138  CTime tmp(t);
2139  return tmp.AddDay(days);
2140 }
2141 
2142 inline
2143 CTime AddHour(const CTime& t, int hours = 1)
2144 {
2145  CTime tmp(t);
2146  return tmp.AddHour(hours);
2147 }
2148 
2149 inline
2150 CTime AddMinute(const CTime& t, int minutes = 1)
2151 {
2152  CTime tmp(t);
2153  return tmp.AddMinute(minutes);
2154 }
2155 
2156 inline
2157 CTime AddSecond(const CTime& t, long seconds = 1)
2158 {
2159  CTime tmp(t);
2160  return tmp.AddSecond(seconds);
2161 }
2162 
2163 inline
2164 CTime AddNanoSecond (const CTime& t, long nanoseconds = 1)
2165 {
2166  CTime tmp(t);
2167  return tmp.AddNanoSecond(nanoseconds);
2168 }
2169 
2170 // Add/subtract CTimeSpan (see CTime::operator +/-)
2171 inline
2172 CTime operator+ (const CTimeSpan& ts, const CTime& t)
2173 {
2174  CTime tmp(t);
2175  tmp.AddTimeSpan(ts);
2176  return tmp;
2177 }
2178 
2179 #ifdef CurrentTime // from <X11/X.h>, perhaps
2180 # undef CurrentTime
2181 #endif
2182 // Get current time (in local or universal format)
2183 inline
2187  )
2188 {
2189  return CTime(CTime::eCurrent, tz, tzp);
2190 }
2191 
2192 // Truncate the time to days (see CTime::Truncate)
2193 inline
2195 {
2196  CTime tmp(t);
2197  return tmp.Truncate();
2198 }
2199 
2200 /// Dumps the current stopwatch time to an output stream.
2201 /// The time will be printed out using format specified
2202 /// by CStopWatch::GetFormat().
2203 inline
2204 ostream& operator<< (ostream& os, const CStopWatch& sw)
2205 {
2206  return os << sw.AsString();
2207 }
2208 
2209 /// Dumps the current CTime time to an output stream.
2210 /// The time will be printed out using format
2211 /// returned by CTime::GetFormat().
2212 inline
2213 ostream& operator<< (ostream& os, const CTime& t)
2214 {
2215  return os << t.AsString();
2216 }
2217 
2218 
2219 //=============================================================================
2220 //
2221 // Inline class methods
2222 //
2223 //=============================================================================
2224 
2225 //
2226 // CTimeFormat
2227 //
2228 
2229 inline
2230 void CTimeFormat::SetFormat(const char* fmt, TFlags flags)
2231 {
2232  SetFormat(string(fmt), flags);
2233 }
2234 
2235 inline
2236 const string& CTimeFormat::GetString(void) const
2237 {
2238  return m_Str;
2239 }
2240 
2241 inline
2243 {
2244  return m_Flags;
2245 }
2246 
2247 inline
2248 bool CTimeFormat::IsEmpty(void) const
2249 {
2250  return m_Str.empty();
2251 }
2252 
2253 inline
2254 CTimeFormat::operator string(void) const
2255 {
2256  return m_Str;
2257 }
2258 
2259 
2260 //
2261 // CTime
2262 //
2263 
2264 inline
2265 int CTime::Year(void) const { return m_Data.year; }
2266 
2267 inline
2268 int CTime::Month(void) const { return m_Data.month; }
2269 
2270 inline
2271 int CTime::Day(void) const { return m_Data.day; }
2272 
2273 inline
2274 int CTime::Hour(void) const { return m_Data.hour; }
2275 
2276 inline
2277 int CTime::Minute(void) const { return m_Data.min; }
2278 
2279 inline
2280 int CTime::Second(void) const { return m_Data.sec; }
2281 
2282 inline
2283 long CTime::MilliSecond(void) const { return (long)m_Data.nanosec/1000000; }
2284 
2285 inline
2286 long CTime::MicroSecond(void) const { return (long)m_Data.nanosec/1000; }
2287 
2288 inline
2289 long CTime::NanoSecond(void) const { return (long)m_Data.nanosec; }
2290 
2291 inline
2293 {
2294  return AddMonth(years * 12, adl);
2295 }
2296 
2297 inline
2298 CTime& CTime::SetTimeT(const time_t t) { return x_SetTimeMTSafe(&t); }
2299 
2300 inline
2302 
2303 inline
2304 CTime& CTime::operator+= (const CTimeSpan& ts) { return AddTimeSpan(ts); }
2305 
2306 inline
2307 CTime& CTime::operator-= (const CTimeSpan& ts) { return AddTimeSpan(-ts); }
2308 
2309 inline
2311 {
2312  CTime tmp(*this);
2313  tmp.AddTimeSpan(ts);
2314  return tmp;
2315 }
2316 
2317 inline
2319 {
2320  CTime tmp(*this);
2321  tmp.AddTimeSpan(-ts);
2322  return tmp;
2323 }
2324 
2325 inline
2327 {
2328  return DiffTimeSpan(t);
2329 }
2330 
2331 inline
2332 CTime::operator string(void) const { return AsString(); }
2333 
2334 
2335 inline
2336 CTime& CTime::operator= (const string& str)
2337 {
2338  x_Init(str, GetFormat());
2339  return *this;
2340 }
2341 
2342 inline
2344 {
2345  if ( &t == this ) {
2346  return *this;
2347  }
2348  m_Data = t.m_Data;
2349  return *this;
2350 }
2351 
2352 inline
2353 bool CTime::operator!= (const CTime& t) const
2354 {
2355  return !(*this == t);
2356 }
2357 
2358 inline
2359 bool CTime::operator>= (const CTime& t) const
2360 {
2361  return !(*this < t);
2362 }
2363 
2364 inline
2365 bool CTime::operator<= (const CTime& t) const
2366 {
2367  return !(*this > t);
2368 }
2369 
2370 inline
2371 CTime& CTime::AddHour(int hours, EDaylight use_daylight)
2372 {
2373  return x_AddHour(hours, use_daylight, true);
2374 }
2375 
2376 inline
2377 bool CTime::IsEmpty() const
2378 {
2379  return
2380  !Day() && !Month() && !Year() &&
2381  !Hour() && !Minute() && !Second() && !NanoSecond();
2382 }
2383 
2384 inline
2386 {
2387  // We check year value only, because all time object date fields
2388  // can be zeros only at one time.
2389  return !Year();
2390 }
2391 
2392 inline
2393 double CTime::DiffDay(const CTime& t) const
2394 {
2395  return (double)DiffSecond(t) / 60.0 / 60.0 / 24.0;
2396 }
2397 
2398 inline
2399 double CTime::DiffHour(const CTime& t) const
2400 {
2401  return (double)DiffSecond(t) / 60.0 / 60.0;
2402 }
2403 
2404 inline
2405 double CTime::DiffMinute(const CTime& t) const
2406 {
2407  return (double)DiffSecond(t) / 60.0;
2408 }
2409 
2410 inline
2411 double CTime::DiffNanoSecond(const CTime& t) const
2412 {
2413  long dNanoSec = NanoSecond() - t.NanoSecond();
2414  return double(DiffSecond(t)) * double(kNanoSecondsPerSecond) + double(dNanoSec);
2415 }
2416 
2417 inline
2418 bool CTime::IsLocalTime(void) const { return m_Data.tz == eLocal; }
2419 
2420 inline
2421 bool CTime::IsUniversalTime(void) const { return m_Data.tz == eGmt; }
2422 
2423 inline
2425 {
2426  return m_Data.tz;
2427 }
2428 
2429 inline
2431 {
2432  return GetTimeZone();
2433 }
2434 
2435 inline
2437 {
2438  return m_Data.tzprec;
2439 }
2440 
2441 inline
2443 {
2444  ETimeZone tmp = m_Data.tz;
2445  m_Data.tz = val;
2446  return tmp;
2447 }
2448 
2449 inline
2451 {
2452  return SetTimeZone(val);
2453 }
2454 
2455 inline
2457 {
2459  m_Data.tzprec = val;
2460  return tmp;
2461 }
2462 
2463 inline
2465 {
2466  ToTime(eLocal);
2467  return *this;
2468 }
2469 
2470 inline
2472 {
2473  ToTime(eUTC);
2474  return *this;
2475 }
2476 
2477 // @deprecated
2478 inline
2480 {
2481  return TimeZoneOffset();
2482 }
2483 
2484 inline
2485 bool CTime::x_NeedAdjustTime(void) const
2486 {
2487  return GetTimeZone() == eLocal && GetTimeZonePrecision() != eNone;
2488 }
2489 
2490 
2491 //
2492 // CTimeSpan
2493 //
2494 
2495 inline
2497 {
2498  Clear();
2499  return;
2500 }
2501 
2502 inline
2503 CTimeSpan::CTimeSpan(long seconds, long nanoseconds)
2504 {
2505  Set(seconds, nanoseconds);
2506 }
2507 
2508 inline
2509 CTimeSpan::CTimeSpan(double seconds)
2510 {
2511  Set(seconds);
2512 }
2513 
2514 inline
2516 {
2517  m_Sec = t.m_Sec;
2518  m_NanoSec = t.m_NanoSec;
2519 }
2520 
2521 inline
2523  m_Sec = 0;
2524  m_NanoSec = 0;
2525  return *this;
2526 }
2527 
2528 inline
2530 {
2531  if ((m_Sec < 0) || (m_NanoSec < 0)) {
2532  return eNegative;
2533  }
2534  if (!m_Sec && !m_NanoSec) {
2535  return eZero;
2536  }
2537  return ePositive;
2538 }
2539 
2540 inline
2541 int CTimeSpan::x_Hour(void) const { return int((m_Sec / 3600L) % 24); }
2542 
2543 inline
2544 int CTimeSpan::x_Minute(void) const { return int((m_Sec / 60L) % 60); }
2545 
2546 inline
2547 int CTimeSpan::x_Second(void) const { return int(m_Sec % 60L); }
2548 
2549 inline
2550 long CTimeSpan::GetCompleteDays(void) const { return m_Sec / 86400L; }
2551 
2552 inline
2553 long CTimeSpan::GetCompleteHours(void) const { return m_Sec / 3600L; }
2554 
2555 inline
2556 long CTimeSpan::GetCompleteMinutes(void) const { return m_Sec / 60L; }
2557 
2558 inline
2559 long CTimeSpan::GetCompleteSeconds(void) const { return m_Sec; }
2560 
2561 inline
2563 
2564 inline
2565 double CTimeSpan::GetAsDouble(void) const
2566 {
2567  return double(m_Sec) + double(m_NanoSec) / double(kNanoSecondsPerSecond);
2568 }
2569 
2570 inline
2571 void CTimeSpan::Set(long seconds, long nanoseconds)
2572 {
2573  m_Sec = seconds + nanoseconds/kNanoSecondsPerSecond;
2574  m_NanoSec = nanoseconds % kNanoSecondsPerSecond;
2575  x_Normalize();
2576 }
2577 
2578 inline
2579 bool CTimeSpan::IsEmpty(void) const
2580 {
2581  return m_Sec == 0 && m_NanoSec == 0;
2582 }
2583 
2584 inline
2586 {
2587  m_Sec = t.m_Sec;
2588  m_NanoSec = t.m_NanoSec;
2589  return *this;
2590 }
2591 
2592 inline
2593 CTimeSpan::operator string(void) const { return AsString(); }
2594 
2595 inline
2597 {
2598  m_Sec += t.m_Sec;
2599  m_NanoSec += t.m_NanoSec;
2600  x_Normalize();
2601  return *this;
2602 }
2603 
2604 inline
2606 {
2607  CTimeSpan tnew(0, 0, 0, m_Sec + t.m_Sec, m_NanoSec + t.m_NanoSec);
2608  return tnew;
2609 }
2610 
2611 inline
2613 {
2614  m_Sec -= t.m_Sec;
2615  m_NanoSec -= t.m_NanoSec;
2616  x_Normalize();
2617  return *this;
2618 }
2619 
2620 inline
2622 {
2623  CTimeSpan tnew(0, 0, 0, m_Sec - t.m_Sec, m_NanoSec - t.m_NanoSec);
2624  return tnew;
2625 }
2626 
2627 inline
2629 {
2630  CTimeSpan t;
2631  t.m_Sec = -m_Sec;
2632  t.m_NanoSec = -m_NanoSec;
2633  return t;
2634 }
2635 
2636 inline
2638 {
2639  m_Sec = -m_Sec;
2640  m_NanoSec = -m_NanoSec;
2641 }
2642 
2643 inline
2645 {
2646  return m_Sec == t.m_Sec && m_NanoSec == t.m_NanoSec;
2647 }
2648 
2649 inline
2651 {
2652  return !(*this == t);
2653 }
2654 
2655 inline
2657 {
2658  if (m_Sec == t.m_Sec) {
2659  return m_NanoSec > t.m_NanoSec;
2660  }
2661  return m_Sec > t.m_Sec;
2662 }
2663 
2664 
2665 inline
2667 {
2668  if (m_Sec == t.m_Sec) {
2669  return m_NanoSec < t.m_NanoSec;
2670  }
2671  return m_Sec < t.m_Sec;
2672 }
2673 
2674 inline
2676 {
2677  return !(*this < t);
2678 }
2679 
2680 inline
2682 {
2683  return !(*this > t);
2684 }
2685 
2686 // @deprecated
2687 inline
2690  ERound rounding,
2691  ESmartStringZeroMode zero_mode) const
2692 {
2694  flags |= (rounding == eRound) ?
2696  flags |= (zero_mode == CTimeSpan::eSSZ_NoSkipZero) ?
2698  return AsSmartString(flags);
2699 }
2700 
2701 
2702 
2703 //
2704 // CTimeout
2705 //
2706 
2707 inline
2709 
2710 inline
2712 
2713 inline
2714 CTimeout::CTimeout(const CTimeSpan& ts) { Set(ts); }
2715 
2716 inline
2717 CTimeout::CTimeout(unsigned int sec, unsigned int usec) { Set(sec, usec); }
2718 
2719 inline
2720 CTimeout::CTimeout(double sec) { Set(sec); }
2721 
2722 inline
2724 {
2725  return m_Type == eDefault;
2726 }
2727 
2728 inline
2730 {
2731  return m_Type == eInfinite;
2732 }
2733 
2734 inline
2736 {
2737  return m_Type == eFinite;
2738 }
2739 
2740 inline
2742 {
2743  return !(*this == t);
2744 }
2745 
2746 
2747 
2748 //
2749 // CStopWatch
2750 //
2751 
2752 inline
2754 {
2755  m_Total = 0;
2756  m_Start = 0;
2757  m_State = eStop;
2758  if ( state == eStart ) {
2759  Start();
2760  }
2761 }
2762 
2763 inline
2765 {
2766  if ( m_State == eStart ) {
2767  return;
2768  }
2769  m_Start = GetTimeMark();
2770  m_State = eStart;
2771 }
2772 
2773 
2774 inline
2775 double CStopWatch::Elapsed(void) const
2776 {
2777  double total = m_Total;
2778  if ( m_State == eStop ) {
2779  return total;
2780  }
2781  // Workaround for -0 (negative zero) values,
2782  // that can occur at subtraction of very close doubles.
2783  double mark = GetTimeMark() - m_Start;
2784  if (mark > 0.0) {
2785  total += mark;
2786  }
2787  return total;
2788 }
2789 
2790 
2791 inline
2793 {
2794  if ( m_State == eStop ) {
2795  return;
2796  }
2797  m_State = eStop;
2798 
2799  double mark = GetTimeMark() - m_Start;
2800  if (mark > 0.0) {
2801  m_Total += mark;
2802  }
2803 }
2804 
2805 
2806 inline
2808 {
2809  m_State = eStop;
2810  m_Total = 0;
2811  m_Start = 0;
2812 }
2813 
2814 
2815 inline
2817 {
2818  double total = m_Total;
2819  double current = GetTimeMark();
2820  if ( m_State == eStart ) {
2821  // Workaround for -0 (negative zero) values,
2822  // that can occur at subtraction of very close doubles.
2823  double mark = current - m_Start;
2824  if ( mark > 0.0 ) {
2825  total += mark;
2826  }
2827  }
2828  m_Total = 0;
2829  m_Start = current;
2830  m_State = eStart;
2831  return total;
2832 }
2833 
2834 inline
2835 bool CStopWatch::IsRunning(void) const
2836 {
2837  return m_State == eStart;
2838 }
2839 
2840 
2841 inline
2842 CStopWatch::operator string(void) const
2843 {
2844  return AsString();
2845 }
2846 
2847 
2848 // @deprecated
2849 inline
2852  ERound rounding,
2854  const
2855 {
2857  flags |= (rounding == eRound) ?
2859  flags |= (zero_mode == CTimeSpan::eSSZ_NoSkipZero) ?
2861  return CTimeSpan(Elapsed()).AsSmartString(flags);
2862 }
2863 
2864 
2865 inline
2867 {
2868  return CTimeSpan(Elapsed()).AsSmartString(flags);
2869 }
2870 
2871 
2873 
2874 #endif /* CORELIB__NCBITIME__HPP */
bool operator!=(const _Ht_iterator< _Val, _Nonconst_traits< _Val >, _Key, _HF, _ExK, _EqK, _All > &__x, const _Ht_iterator< _Val, _Const_traits< _Val >, _Key, _HF, _ExK, _EqK, _All > &__y)
Definition: _hashtable.h:173
@ eEmpty
no filtering at all.
CCoreException –.
Definition: ncbiexpt.hpp:1476
CCurrentTime –.
Definition: ncbitime.hpp:1283
CDeadline.
Definition: ncbitime.hpp:1830
CFastLocalTime –.
Definition: ncbitime.hpp:1895
CNanoTimeout – Timeout interval, using nanoseconds.
Definition: ncbitime.hpp:1810
CStopWatch –.
Definition: ncbitime.hpp:1937
CTimeException –.
Definition: ncbitime.hpp:2075
CTimeFormat –.
Definition: ncbitime.hpp:131
CTimeSpan.
Definition: ncbitime.hpp:1313
CTime –.
Definition: ncbitime.hpp:296
CTimeout – Timeout interval.
Definition: ncbitime.hpp:1693
Include a standard set of the NCBI C++ Toolkit most basic headers.
static uch flags
bool operator<(const CEquivRange &A, const CEquivRange &B)
bool operator==(const CEquivRange &A, const CEquivRange &B)
const char * months[]
Definition: ftaerr.cpp:118
static char precision
Definition: genparams.c:28
static const char * str(char *buf, int n)
Definition: stats.c:84
static char tmp[3200]
Definition: utf8.c:42
#define NCBI_DEPRECATED_CTOR(decl)
Macro used to mark a constructor as deprecated.
Definition: ncbimisc.hpp:1209
ERound
Whether to truncate/round a value.
Definition: ncbimisc.hpp:136
ESign
Signedness of a value.
Definition: ncbimisc.hpp:120
@ eRound
Value must be rounded.
Definition: ncbimisc.hpp:138
@ eNegative
Value is negative.
Definition: ncbimisc.hpp:121
@ ePositive
Value is positive.
Definition: ncbimisc.hpp:123
@ eZero
Value is zero.
Definition: ncbimisc.hpp:122
string
Definition: cgiapp.hpp:687
EErrCode
Error types that an application can generate.
Definition: ncbiexpt.hpp:884
CVect2< T > operator-(const CVect2< T > &v)
Definition: globals.hpp:207
CExpression operator>=(CREATED, time_point)
CExpression operator<=(time_point, CREATED)
bool IsValid(const CSeq_point &pt, CScope *scope)
Checks that point >= 0 and point < length of Bioseq.
#define NCBI_DEPRECATED
int32_t Int4
4-byte (32-bit) signed integer
Definition: ncbitype.h:102
uint16_t Uint2
2-byte (16-bit) unsigned integer
Definition: ncbitype.h:101
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define kEmptyStr
Definition: ncbistr.hpp:123
Int8 TSeconds
Number of seconds.
Definition: ncbitime.hpp:77
ETimeZone GetTimeZoneFormat(void) const
Definition: ncbitime.hpp:2430
unsigned int TFlags
Binary OR of "EFlags".
Definition: ncbitime.hpp:185
unsigned char min
Definition: ncbitime.hpp:1252
bool x_Init(const string &str, const CTimeFormat &fmt, EErrAction err_action=eErr_Throw)
Helper method to set time value from string "str" using format "fmt".
Definition: ncbitime.cpp:507
double m_Total
Accumulated elapsed time.
Definition: ncbitime.hpp:2059
int Minute(void) const
Get minute.
Definition: ncbitime.hpp:2277
ESmartStringZeroMode
Which format use to output zero time span parts.
Definition: ncbitime.hpp:1526
CTime & operator-=(const CTimeSpan &ts)
Operator to subtract time span.
Definition: ncbitime.hpp:2307
int x_Second(void) const
Get second.
Definition: ncbitime.hpp:2547
double DiffHour(const CTime &t) const
Difference in hours from specified time.
Definition: ncbitime.hpp:2399
ETimeZonePrecision GetTimeZonePrecision(void) const
Get time zone precision.
Definition: ncbitime.hpp:2436
CTime & ToLocalTime(void)
Convert the time into local time.
Definition: ncbitime.hpp:2464
CDeadline CAbsTimeout
Definition: ncbitime.hpp:1880
CTimeSpan operator+(const CTimeSpan &t) const
Definition: ncbitime.hpp:2605
TSeconds TimeZoneOffset(void) const
Get difference between local timezone for current time object and UTC in seconds.
Definition: ncbitime.cpp:2218
bool IsRunning(void) const
Check state of stopwatch.
Definition: ncbitime.hpp:2835
EInitMode
Which initial value to use for time.
Definition: ncbitime.hpp:299
unsigned int TSmartStringFlags
Binary OR of "ESmartStringFlags".
Definition: ncbitime.hpp:1499
double Restart(void)
Return time elapsed since first Start() or last Restart() call (in seconds).
Definition: ncbitime.hpp:2816
CTimeSpan & operator=(const CTimeSpan &t)
Assignment operator.
Definition: ncbitime.hpp:2585
EDayOfWeek
Day of week names.
Definition: ncbitime.hpp:339
Int4 days
days from 1/1/1900
Definition: ncbitime.hpp:115
ETimeZone SetTimeZone(ETimeZone val)
Set time zone.
Definition: ncbitime.hpp:2442
CTime & operator=(const CTime &t)
Assignment operator.
Definition: ncbitime.hpp:2343
CTime & AddTimeSpan(const CTimeSpan &timespan)
Add specified time span.
Definition: ncbitime.cpp:1912
double Elapsed(void) const
Return time elapsed since first Start() or last Restart() call (in seconds).
Definition: ncbitime.hpp:2775
unsigned char month
Definition: ncbitime.hpp:1249
bool IsEmpty(void) const
Return TRUE is an object keep zero time span.
Definition: ncbitime.hpp:2579
bool IsGmtTime(void) const
Definition: ncbitime.hpp:1108
unsigned char sec
Definition: ncbitime.hpp:1253
bool operator==(const CTimeSpan &t) const
Operator to test equality of time span.
Definition: ncbitime.hpp:2644
CTime operator-(const CTimeSpan &ts) const
Operator to subtract time span.
Definition: ncbitime.hpp:2318
CTime operator+(const CTimeSpan &ts) const
Definition: ncbitime.hpp:2310
EErrAction
Defines how to behave on error.
Definition: ncbitime.hpp:1193
CTime & x_AddHour(int hours=1, EDaylight daylight=eDaylightDefault, bool shift_time=true)
Helper method to add hour with/without shift time.
Definition: ncbitime.cpp:1820
TData m_Data
Packed members.
Definition: ncbitime.hpp:1263
bool IsUniversalTime(void) const
Is time universal (GMT/UTC/Z)?
Definition: ncbitime.hpp:2421
ETimeZone
Which initial value to use for timezone.
Definition: ncbitime.hpp:305
void SetFormat(const char *fmt, TFlags flags=fDefault)
Set the current time format.
Definition: ncbitime.hpp:2230
CCurrentTime(ETimeZone tz=eLocal)
Constructor.
Definition: ncbitime.hpp:1289
CTimeSpan & operator+=(const CTimeSpan &t)
Definition: ncbitime.hpp:2596
#define NCBI_TIME_EMPTY_BITFIELD
Definition: ncbitime.hpp:1244
long GetCompleteMinutes(void) const
Get number of complete minutes.
Definition: ncbitime.hpp:2556
~CTimeout(void)
Destructor.
Definition: ncbitime.hpp:1722
void x_Normalize(void)
Helper method to normalize stored time value.
Definition: ncbitime.cpp:2644
unsigned char hour
Definition: ncbitime.hpp:1251
long GetCompleteDays(void) const
Get number of complete days.
Definition: ncbitime.hpp:2550
ETimeZone GetTimeZone(void) const
Get time zone.
Definition: ncbitime.hpp:2424
int m_Timezone
Cached timezone adjustment for local time.
Definition: ncbitime.hpp:1924
bool x_NeedAdjustTime(void) const
Helper method to check if there is a need adjust time in timezone.
Definition: ncbitime.hpp:2485
long GetNanoSecondsAfterSecond(void) const
Get number of nanoseconds.
Definition: ncbitime.hpp:2562
bool operator<=(const CTimeSpan &t) const
Operator to test if time span is less or equal.
Definition: ncbitime.hpp:2681
void Set(long seconds, long nanoseconds=0)
Set time span in seconds and nanoseconds.
Definition: ncbitime.hpp:2571
bool operator<(const CTimeSpan &t) const
Operator to test if time span is less.
Definition: ncbitime.hpp:2666
EDaylight
Whether to adjust for daylight saving time.
Definition: ncbitime.hpp:367
unsigned int year
Definition: ncbitime.hpp:1248
ETimeZonePrecision SetTimeZonePrecision(ETimeZonePrecision val)
Set time zone precision.
Definition: ncbitime.hpp:2456
CTime m_TunedTime
Last tuned time (changed by Tuneup())
Definition: ncbitime.hpp:1920
EType
Type of timeouts.
Definition: ncbitime.hpp:1696
CTime & AddMonth(int months=1, EDaylight adl=eDaylightDefault)
Add specified months and adjust for daylight saving time.
Definition: ncbitime.cpp:1757
CTime & operator+=(const CTimeSpan &ts)
Definition: ncbitime.hpp:2304
CTime Truncate(const CTime &t)
Definition: ncbitime.hpp:2194
long NanoSecond(void) const
Get nano-seconds.
Definition: ncbitime.hpp:2289
unsigned int m_SecAfterHour
Time interval in seconds after hour.
Definition: ncbitime.hpp:1917
long MicroSecond(void) const
Get microseconds.
Definition: ncbitime.hpp:2286
bool IsExpired(void) const
Check if the deadline is expired.
Definition: ncbitime.hpp:1855
int Year(void) const
Get year.
Definition: ncbitime.hpp:2265
void Stop(void)
Suspend the timer.
Definition: ncbitime.hpp:2792
CCurrentTime & Update(void)
Update current time.
Definition: ncbitime.hpp:1294
long MilliSecond(void) const
Get milliseconds.
Definition: ncbitime.hpp:2283
CTime AddYear(const CTime &t, int years=1)
Definition: ncbitime.hpp:2122
const long kMilliSecondsPerSecond
Number milliseconds in one second.
Definition: ncbitime.hpp:96
double GetAsDouble(void) const
Return time span as number of seconds.
Definition: ncbitime.hpp:2565
CTime & ToTime(ETimeZone val)
Convert the time into specified time zone time.
Definition: ncbitime.cpp:2074
bool IsInfinite() const
Definition: ncbitime.hpp:2729
CTime AddDay(const CTime &t, int days=1)
Definition: ncbitime.hpp:2136
time_t m_LastSysTime
Last system time.
Definition: ncbitime.hpp:1923
bool IsEmpty(void) const
Is time object empty (date and time)?
Definition: ncbitime.hpp:2377
TFlags m_Flags
Format flags.
Definition: ncbitime.hpp:274
CStopWatch(EStart state=eStop)
Constructor.
Definition: ncbitime.hpp:2753
CTime & ToUniversalTime(void)
Convert the time into universal (GMT/UTC) time.
Definition: ncbitime.hpp:2471
CTime & AddYear(int years=1, EDaylight adl=eDaylightDefault)
Add specified years and adjust for daylight saving time.
Definition: ncbitime.hpp:2292
ESign GetSign(void) const
Get sign of time span.
Definition: ncbitime.hpp:2529
bool operator<=(const CTime &t) const
Operator to test if time is earlier or equal.
Definition: ncbitime.hpp:2365
ETimeZone SetTimeZoneFormat(ETimeZone val)
Definition: ncbitime.hpp:2450
void Invert(void)
Invert time span. Changes time span sign.
Definition: ncbitime.hpp:2637
CTime & SetCurrent(void)
Make the time current in the presently active time zone.
Definition: ncbitime.hpp:2301
CTimeSpan & operator-=(const CTimeSpan &t)
Operator to subtract time span.
Definition: ncbitime.hpp:2612
CTime CurrentTime(CTime::ETimeZone tz=CTime::eLocal, CTime::ETimeZonePrecision tzp=CTime::eTZPrecisionDefault)
Definition: ncbitime.hpp:2184
unsigned int m_Nanoseconds
Definition: ncbitime.hpp:1874
EPredefined
Predefined formats.
Definition: ncbitime.hpp:190
struct TDBTimeU * TDBTimeUPtr
ETimeZonePrecision
What time zone precision to use for adjusting daylight saving time.
Definition: ncbitime.hpp:357
string AsSmartString(CTimeSpan::ESmartStringPrecision precision, ERound rounding, CTimeSpan::ESmartStringZeroMode zero_mode=CTimeSpan::eSSZ_SkipZero) const
Transform elapsed time to "smart" string.
Definition: ncbitime.hpp:2850
CTimeout(void)
Create default timeout.
Definition: ncbitime.hpp:2708
string AsSmartString(ESmartStringPrecision precision, ERound rounding, ESmartStringZeroMode zero_mode=eSSZ_SkipZero) const
Transform time span to "smart" string.
Definition: ncbitime.hpp:2688
EStart
Defines how to create new timer.
Definition: ncbitime.hpp:1940
struct TDBTimeI * TDBTimeIPtr
const TSeconds kAverageSecondsPerMonth
Definition: ncbitime.hpp:102
CTimeSpan DiffTimeSpan(const CTime &t) const
Difference in nanoseconds from specified time.
Definition: ncbitime.cpp:2305
ostream & operator<<(ostream &os, const CStopWatch &sw)
Dumps the current stopwatch time to an output stream.
Definition: ncbitime.hpp:2204
bool operator>(const CTimeSpan &t) const
Operator to test if time span is greater.
Definition: ncbitime.hpp:2656
unsigned int m_Sec
Seconds part of the timeout.
Definition: ncbitime.hpp:1795
EMonth
Month names.
Definition: ncbitime.hpp:323
CTimeSpan(void)
Default constructor.
Definition: ncbitime.hpp:2496
ETimeZonePrecision tzprec
Definition: ncbitime.hpp:1259
int Day(void) const
Get day.
Definition: ncbitime.hpp:2271
static double GetTimeMark()
Get current time mark.
Definition: ncbitime.cpp:4095
unsigned char day
Definition: ncbitime.hpp:1250
TSeconds DiffSecond(const CTime &t) const
Difference in seconds from specified time.
Definition: ncbitime.cpp:2282
const double kAverageDaysPerYear
The average length of the year in the Gregorian (modern) calendar (in days)
Definition: ncbitime.hpp:99
ESmartStringPrecision
Precision for span "smart" string.
Definition: ncbitime.hpp:1503
unsigned int m_NanoSec
Nanoseconds part of the timeout.
Definition: ncbitime.hpp:1796
int x_Hour(void) const
Get hour.
Definition: ncbitime.hpp:2541
bool m_Infinite
Definition: ncbitime.hpp:1875
Uint2 days
Days from 1/1/1900.
Definition: ncbitime.hpp:109
CTime AddHour(const CTime &t, int hours=1)
Definition: ncbitime.hpp:2143
const string & GetString(void) const
Get format string.
Definition: ncbitime.hpp:2236
CTimeSpan operator-(void) const
Unary operator "-" (minus) to change time span sign.
Definition: ncbitime.hpp:2628
void Start(void)
Start the timer.
Definition: ncbitime.hpp:2764
static CTimeFormat GetFormat(void)
Get the current time format.
Definition: ncbitime.cpp:1277
CTime & ToGmtTime(void)
Definition: ncbitime.hpp:1166
bool operator>=(const CTime &t) const
Operator to test if time is later or equal.
Definition: ncbitime.hpp:2359
bool IsEmpty(void) const
Check that format string is empty.
Definition: ncbitime.hpp:2248
long m_NanoSec
Nanoseconds after the second.
Definition: ncbitime.hpp:1680
bool IsDefault() const
Definition: ncbitime.hpp:2723
NCBI_EXCEPTION_DEFAULT(CTimeException, CCoreException)
Uint2 time
Minutes from the beginning of current day.
Definition: ncbitime.hpp:110
Int4 time
x/300 seconds from the beginning of current day
Definition: ncbitime.hpp:116
TSeconds TimeZoneDiff(void) const
Get difference between local timezone for current time object and UTC in seconds.
Definition: ncbitime.hpp:2479
ESmartStringFlags
AsSmartString() conversion flags.
Definition: ncbitime.hpp:1440
CTime operator+(const CTimeSpan &ts, const CTime &t)
Definition: ncbitime.hpp:2172
CTime m_LocalTime
Current local time.
Definition: ncbitime.hpp:1919
string AsString(const CTimeFormat &fmt=kEmptyStr) const
Transform stopwatch time to string.
Definition: ncbitime.cpp:4149
void Set(EType type)
Set special value.
Definition: ncbitime.cpp:3577
int m_Daylight
Cached system daylight information.
Definition: ncbitime.hpp:1925
CTime GetFastLocalTime(void)
Quick and dirty getter of local time.
Definition: ncbitime.cpp:4167
double DiffNanoSecond(const CTime &t) const
Difference in nanoseconds from specified time.
Definition: ncbitime.hpp:2411
int x_Minute(void) const
Get minute.
Definition: ncbitime.hpp:2544
ERoundPrecision
Precision for rounding time.
Definition: ncbitime.hpp:982
double DiffDay(const CTime &t) const
Difference in days from specified time.
Definition: ncbitime.hpp:2393
CTime AddMinute(const CTime &t, int minutes=1)
Definition: ncbitime.hpp:2150
CTime & SetTimeT(const time_t t)
Set time using time_t time value.
Definition: ncbitime.hpp:2298
double DiffMinute(const CTime &t) const
Difference in minutes from specified time.
Definition: ncbitime.hpp:2405
CNanoTimeout(unsigned int seconds, unsigned int nanoseconds)
Definition: ncbitime.hpp:1812
bool operator!=(const CTimeout &t) const
Operator to test in-equality of timeouts.
Definition: ncbitime.hpp:2741
int Hour(void) const
Get hour.
Definition: ncbitime.hpp:2274
bool IsInfinite(void) const
Check if the deadline is infinite.
Definition: ncbitime.hpp:1852
CTime & x_SetTimeMTSafe(const time_t *t=0)
Version of x_SetTime() with MT-safe locks.
Definition: ncbitime.cpp:1663
bool IsFinite() const
Check if timeout holds a numeric value.
Definition: ncbitime.hpp:2735
void TuneupFastLocalTime(void)
Definition: ncbitime.cpp:4173
CTime GetGmtTime(void) const
Definition: ncbitime.hpp:1156
double m_Start
Start time value.
Definition: ncbitime.hpp:2058
CTimeSpan & Clear(void)
Make the time span "empty",.
Definition: ncbitime.hpp:2522
void Reset(void)
Stop (if running) and reset the timer.
Definition: ncbitime.hpp:2807
string m_Str
String format.
Definition: ncbitime.hpp:273
EFlags
Flags.
Definition: ncbitime.hpp:139
CDeadline(CTimeout::EType)
bool operator>=(const CTimeSpan &t) const
Operator to test if time span is greater or equal.
Definition: ncbitime.hpp:2675
CTime AddNanoSecond(const CTime &t, long nanoseconds=1)
Definition: ncbitime.hpp:2164
EType
Type of special deadlines.
Definition: ncbitime.hpp:1833
bool IsLocalTime(void) const
Is time local time?
Definition: ncbitime.hpp:2418
const long kMicroSecondsPerSecond
Number of microseconds in one second.
Definition: ncbitime.hpp:91
TFlags GetFlags(void) const
Get format flags.
Definition: ncbitime.hpp:2242
long GetCompleteSeconds(void) const
Get number of complete seconds.
Definition: ncbitime.hpp:2559
time_t m_Seconds
Definition: ncbitime.hpp:1873
EStart m_State
Stopwatch state (started/stopped)
Definition: ncbitime.hpp:2060
CTime & AddHour(int hours=1, EDaylight adl=eDaylightDefault)
Add specified hours and adjust for daylight saving time.
Definition: ncbitime.hpp:2371
CTime AddMonth(const CTime &t, int months=1)
Definition: ncbitime.hpp:2129
const TSeconds kAverageSecondsPerYear
The average length of the year in the Gregorian (modern) calendar (in seconds)
Definition: ncbitime.hpp:101
int Second(void) const
Get second.
Definition: ncbitime.hpp:2280
int Month(void) const
Get month.
Definition: ncbitime.hpp:2268
long GetCompleteHours(void) const
Get number of complete hours.
Definition: ncbitime.hpp:2553
bool operator!=(const CTime &t) const
Operator to test in-equality of time.
Definition: ncbitime.hpp:2353
void *volatile m_IsTuneup
(bool) Tuneup() in progress (MT)
Definition: ncbitime.hpp:1926
const long kNanoSecondsPerSecond
Number of nanoseconds in one second.
Definition: ncbitime.hpp:86
EType m_Type
Type of timeout.
Definition: ncbitime.hpp:1794
CTime AddSecond(const CTime &t, long seconds=1)
Definition: ncbitime.hpp:2157
bool operator!=(const CTimeSpan &t) const
Operator to test in-equality of time span.
Definition: ncbitime.hpp:2650
ENameFormat
Which format use to get name of month or week of day.
Definition: ncbitime.hpp:317
time_t m_LastTuneupTime
Last Tuneup() time.
Definition: ncbitime.hpp:1922
ETimeZone tz
Definition: ncbitime.hpp:1258
long m_Sec
Seconds part of the time span.
Definition: ncbitime.hpp:1679
#define NCBI_TIME_BITFIELD(n)
Definition: ncbitime.hpp:1243
bool IsEmptyDate(void) const
Is date empty?
Definition: ncbitime.hpp:2385
@ eSSZ_SkipZero
Skip zero valued parts.
Definition: ncbitime.hpp:1528
@ eSSZ_NoSkipZero
Print zero valued parts.
Definition: ncbitime.hpp:1527
@ eCurrent
Use current time. See also CCurrentTime.
Definition: ncbitime.hpp:300
@ eWednesday
Definition: ncbitime.hpp:343
@ eThursday
Definition: ncbitime.hpp:344
@ eFriday
Definition: ncbitime.hpp:345
@ eTuesday
Definition: ncbitime.hpp:342
@ eMonday
Definition: ncbitime.hpp:341
@ eErr_Throw
Throw an exception on error.
Definition: ncbitime.hpp:1194
@ eUTC
UTC (Universal Coordinated Time)
Definition: ncbitime.hpp:307
@ eGmt
GMT (Greenwich Mean Time)
Definition: ncbitime.hpp:308
@ eLocal
Local time.
Definition: ncbitime.hpp:306
@ eConvert
Error converting value from one format to another.
Definition: ncbitime.hpp:2080
@ eInvalid
Invalid time value.
Definition: ncbitime.hpp:2081
@ eArgument
Bad function argument.
Definition: ncbitime.hpp:2079
@ eAdjustDaylight
Adjust for daylight saving time.
Definition: ncbitime.hpp:369
@ eIgnoreDaylight
Ignore daylight saving time.
Definition: ncbitime.hpp:368
@ eDefault
Default timeout (to be interpreted by the client code)
Definition: ncbitime.hpp:1698
@ eInfinite
Infinite timeout.
Definition: ncbitime.hpp:1699
@ eFinite
A finite timeout value has been set.
Definition: ncbitime.hpp:1697
@ eNone
Daylight saving not to affect time manipulations.
Definition: ncbitime.hpp:358
@ eMinute
Check condition - new minute.
Definition: ncbitime.hpp:359
@ eMonth
Check condition - new month.
Definition: ncbitime.hpp:362
@ eDay
Check condition - new day.
Definition: ncbitime.hpp:361
@ eTZPrecisionDefault
Definition: ncbitime.hpp:363
@ eHour
Check condition - new hour.
Definition: ncbitime.hpp:360
@ eStart
Start timer immediately after creating.
Definition: ncbitime.hpp:1941
@ eStop
Do not start timer, just create it.
Definition: ncbitime.hpp:1942
@ eJuly
Definition: ncbitime.hpp:330
@ eOctober
Definition: ncbitime.hpp:333
@ eFebruary
Definition: ncbitime.hpp:325
@ eSeptember
Definition: ncbitime.hpp:332
@ eMarch
Definition: ncbitime.hpp:326
@ eApril
Definition: ncbitime.hpp:327
@ eMay
Definition: ncbitime.hpp:328
@ eJune
Definition: ncbitime.hpp:329
@ eAugust
Definition: ncbitime.hpp:331
@ eNovember
Definition: ncbitime.hpp:334
@ fSS_NoSkipZero
Definition: ncbitime.hpp:1486
@ eRound_Minute
Round to minutes.
Definition: ncbitime.hpp:985
@ eRound_Day
Round to days.
Definition: ncbitime.hpp:983
@ eRound_Hour
Round to hours.
Definition: ncbitime.hpp:984
@ eRound_Millisecond
Round to milliseconds.
Definition: ncbitime.hpp:987
@ eRound_Second
Round to seconds.
Definition: ncbitime.hpp:986
@ eFull
Use full name.
Definition: ncbitime.hpp:318
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
unsigned int
A callback function used to compare two keys in a database.
Definition: types.hpp:1210
static CStopWatch sw
CNcbiMatrix< T > & operator+=(CNcbiMatrix< T > &, const CNcbiMatrix< U > &)
global addition: matrix += matrix
Definition: matrix.hpp:570
CNcbiMatrix< T > & operator-=(CNcbiMatrix< T > &, const CNcbiMatrix< U > &)
global subtraction: matrix -= matrix
Definition: matrix.hpp:622
const TYPE & Get(const CNamedParameterList *param)
mdb_mode_t mode
Definition: lmdb++.h:38
EIPRangeType t
Definition: ncbi_localip.c:101
T max(T x_, T y_)
T min(T x_, T y_)
static Format format
Definition: njn_ioutil.cpp:53
ESerialDataFormat GetFormat(const string &name)
Database format for time where day and time is signed 32 bit.
Definition: ncbitime.hpp:114
Database format for time where day and time is unsigned 16 bit.
Definition: ncbitime.hpp:108
Definition: type.c:6
static int Round(double Num)
Definition: su_pssm.cpp:88
bool operator>(const typename tree< T, tree_node_allocator >::iterator_base &one, const typename tree< T, tree_node_allocator >::iterator_base &two)
Definition: tree_msvc7.hpp:426
#define const
Definition: zconf.h:232
Modified on Sun May 19 04:41:10 2024 by modify_doxy.py rev. 669887