PTLib  Version 2.10.10
ptime.h
Go to the documentation of this file.
1 /*
2  * ptime.h
3  *
4  * Time and date class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
25  * All Rights Reserved.
26  *
27  * Contributor(s): ______________________________________.
28  *
29  * $Revision: 26282 $
30  * $Author: rjongbloed $
31  * $Date: 2011-08-08 02:09:32 -0500 (Mon, 08 Aug 2011) $
32  */
33 
34 #ifndef PTLIB_TIME_H
35 #define PTLIB_TIME_H
36 
37 #ifdef P_USE_PRAGMA
38 #pragma interface
39 #endif
40 
41 
43 // System time and date class
44 
45 class PTimeInterval;
46 
47 
53 class PTime : public PObject
54 {
55  PCLASSINFO(PTime, PObject);
56 
57  public:
63  enum {
65  UTC = 0,
67  GMT = UTC,
69  Local = 9999
70  };
71 
76 
81  time_t tsecs,
82  long usecs = 0
83  ) { theTime = tsecs; microseconds = usecs; }
84 
101  PTime(
102  const PString & str
103  );
104 
108  PTime(
109  int second,
110  int minute,
111  int hour,
112  int day,
113  int month,
114  int year,
115  int tz = Local
116  );
118 
127  PObject * Clone() const;
128 
135  virtual Comparison Compare(
136  const PObject & obj
137  ) const;
138 
142  virtual void PrintOn(
143  ostream & strm
144  ) const;
145 
162  virtual void ReadFrom(
163  istream & strm
164  );
166 
175  PBoolean IsValid() const;
176 
183  PInt64 GetTimestamp() const;
184 
187  void SetCurrentTime();
188 
191  void SetTimestamp(
192  time_t seconds,
193  long usecs = 0
194  );
195 
202  time_t GetTimeInSeconds() const;
203 
209  long GetMicrosecond() const;
210 
216  int GetSecond() const;
217 
223  int GetMinute() const;
224 
230  int GetHour() const;
231 
237  int GetDay() const;
238 
240  enum Months {
241  January = 1,
253  };
254 
260  Months GetMonth() const;
261 
267  int GetYear() const;
268 
270  enum Weekdays {
278  };
279 
285  Weekdays GetDayOfWeek() const;
286 
292  int GetDayOfYear() const;
293 
299  PBoolean IsPast() const;
300 
306  PBoolean IsFuture() const;
308 
316  static PBoolean IsDaylightSavings();
317 
322  };
323 
325  static int GetTimeZone();
334  static int GetTimeZone(
335  TimeZoneType type
336  );
337 
343  static PString GetTimeZoneString(
344  TimeZoneType type = StandardTime
345  );
347 
356  const PTimeInterval & time
357  ) const;
358 
364  PTime & operator+=(
365  const PTimeInterval & time
366  );
367 
374  const PTime & time
375  ) const;
376 
383  const PTimeInterval & time
384  ) const;
385 
391  PTime & operator-=(
392  const PTimeInterval & time
393  );
395 
398  enum TimeFormat {
427  };
428 
431  TimeFormat formatCode = RFC1123,
432  int zone = Local
433  ) const;
434 
437  const PString & formatStr,
438  int zone = Local
439  ) const;
440  /* Convert the time to a string using the format code or string as a
441  formatting template. The special characters in the formatting string
442  are:
443  <table border=0>
444  <tr><td>h <td>hour without leading zero
445  <tr><td>hh <td>hour with leading zero
446  <tr><td>m <td>minute without leading zero
447  <tr><td>mm <td>minute with leading zero
448  <tr><td>s <td>second without leading zero
449  <tr><td>ss <td>second with leading zero
450  <tr><td>u <td>tenths of second
451  <tr><td>uu <td>hundedths of second with leading zero
452  <tr><td>uuu <td>millisecond with leading zeros
453  <tr><td>uuuu <td>microsecond with leading zeros
454  <tr><td>a <td>the am/pm string
455  <tr><td>w/ww/www <td>abbreviated day of week name
456  <tr><td>wwww <td>full day of week name
457  <tr><td>d <td>day of month without leading zero
458  <tr><td>dd <td>day of month with leading zero
459  <tr><td>M <td>month of year without leading zero
460  <tr><td>MM <td>month of year with leading zero
461  <tr><td>MMM <td>month of year as abbreviated text
462  <tr><td>MMMM <td>month of year as full text
463  <tr><td>y/yy <td>year without century
464  <tr><td>yyy/yyyy <td>year with century
465  <tr><td>z <td>the time zone description ('GMT' for UTC)
466  <tr><td>Z <td>the time zone description ('Z' for UTC)
467  <tr><td>ZZ <td>the time zone description (':' separates hour/minute)
468  </table>
469 
470  All other characters are copied to the output string unchanged.
471 
472  Note if there is an 'a' character in the string, the hour will be in 12
473  hour format, otherwise in 24 hour format.
474 
475  @return empty string if time is invalid.
476  */
478  const char * formatPtr,
479  int zone = Local
480  ) const;
481 
498  bool Parse(
499  const PString & str
500  );
502 
510  static PString GetTimeSeparator();
511 
517  static PBoolean GetTimeAMPM();
518 
524  static PString GetTimeAM();
525 
531  static PString GetTimePM();
532 
534  enum NameType {
537  };
538 
544  static PString GetDayName(
545  Weekdays dayOfWeek,
546  NameType type = FullName
547  );
548 
554  static PString GetDateSeparator();
555 
561  static PString GetMonthName(
562  Months month,
563  NameType type = FullName
564  );
565 
567  enum DateOrder {
571  };
572 
578  static DateOrder GetDateOrder();
580 
581  static struct tm * os_localtime(const time_t * clock, struct tm * t);
582  static struct tm * os_gmtime(const time_t * clock, struct tm * t);
583  /*
584  Threadsafe version of localtime library call.
585  We could make these calls non-static if we could put the struct tm inside the
586  instance. But these calls are usually made with const objects so that's not possible,
587  and we would require per-thread storage otherwise. Sigh...
588  */
589 
590  protected:
591  // Member variables
593  time_t theTime;
595 
596 
597 // Include platform dependent part of class
598 #ifdef _WIN32
599 #include "msos/ptlib/ptime.h"
600 #else
601 #include "unix/ptlib/ptime.h"
602 #endif
603 };
604 
605 
606 #endif // PTLIB_TIME_H
607 
608 
609 // End Of File ///////////////////////////////////////////////////////////////
Definition: ptime.h:248
PInt64 GetTimestamp() const
Get the total microseconds since the epoch.
Time without seconds.
Definition: ptime.h:423
PString AsString(TimeFormat formatCode=RFC1123, int zone=Local) const
Convert the time to a string representation.
int GetHour() const
Get the hour of the time.
static struct tm * os_gmtime(const time_t *clock, struct tm *t)
Definition: ptime.h:242
Definition: ptime.h:426
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
int GetMinute() const
Get the minute of the time.
static PBoolean GetTimeAMPM()
Get the internationalised time format: AM/PM or 24 hour.
Date is ordered year then day month then day.
Definition: ptime.h:570
Date is ordered day then month then year.
Definition: ptime.h:569
Definition: ptime.h:273
NameType
Flag for returning language dependent string names.
Definition: ptime.h:534
This class defines an absolute time and date.
Definition: ptime.h:53
Date is ordered month then day then year.
Definition: ptime.h:568
time_t GetTimeInSeconds() const
Get the total seconds since the epoch.
Definition: ptime.h:536
DateOrder
Possible orders for date components.
Definition: ptime.h:567
Date with abbreviated month names and time without seconds.
Definition: ptime.h:415
Definition: ptime.h:277
Internet standard format. (eg. Wed, 09 Feb 2011 11:25:58 +01:00)
Definition: ptime.h:401
static PString GetDayName(Weekdays dayOfWeek, NameType type=FullName)
Get the internationalised day of week day name (0=Sun etc).
Definition: ptime.h:321
Date with weekday, full month names and time with seconds.
Definition: ptime.h:409
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
static PString GetTimeAM()
Get the internationalised time AM string.
static DateOrder GetDateOrder()
Return the internationalised date order.
PTime & operator+=(const PTimeInterval &time)
Add the interval to the time changing the instance.
Definition: ptime.h:244
static struct tm * os_localtime(const time_t *clock, struct tm *t)
TimeZoneType
Flag for time zone adjustment on daylight savings.
Definition: ptime.h:319
Months
Month codes.
Definition: ptime.h:240
static int GetTimeZone()
Get the time zone offset in minutes.
Definition: ptime.h:252
TimeFormat
Standard time formats for string representations of a time and date.
Definition: ptime.h:399
PTime(time_t tsecs, long usecs=0)
Create a time object instance.
Definition: ptime.h:80
BOOL PBoolean
Definition: object.h:102
Weekdays
Days of the week.
Definition: ptime.h:270
Definition: ptime.h:275
Universal Coordinated Time.
Definition: ptime.h:65
Date with weekday, full month names and no time.
Definition: ptime.h:411
PTime & operator-=(const PTimeInterval &time)
Subtract the interval from the time changing the instance.
PTime()
Create a time object instance.
Definition: ptime.h:75
int GetYear() const
Get the year of the date.
Time with seconds.
Definition: ptime.h:413
Short form ISO standard format. (eg. 20110209T111108Z)
Definition: ptime.h:405
Date with numeric month and no time.
Definition: ptime.h:421
long microseconds
Definition: ptime.h:594
Months GetMonth() const
Get the month of the date.
Date with abbreviated month names and no time.
Definition: ptime.h:417
Definition: ptime.h:249
bool Parse(const PString &str)
Parse a string representation of time.
Definition: ptime.h:272
The character string class.
Definition: pstring.h:108
Another Internet standard format. (eg. 2011-02-09T11:14:41ZZ)
Definition: ptime.h:403
virtual Comparison Compare(const PObject &obj) const
Determine the relative rank of the specified times.
Definition: ptime.h:243
Local Time.
Definition: ptime.h:69
Definition: ptime.h:247
PTimeInterval operator-(const PTime &time) const
Calculate the difference between two times to get a time interval.
Weekdays GetDayOfWeek() const
Get the day of the week of the date.
Definition: ptime.h:251
Date with numeric month name and time without seconds.
Definition: ptime.h:419
Definition: ptime.h:320
virtual void PrintOn(ostream &strm) const
Output the time to the stream.
PTime operator+(const PTimeInterval &time) const
Add the interval to the time to yield a new time.
Definition: ptime.h:274
Definition: ptime.h:535
Definition: ptime.h:245
PBoolean IsPast() const
Determine if the time is in the past or in the future.
virtual void ReadFrom(istream &strm)
Input the time from the specified stream.
Greenwich Mean Time, effectively UTC.
Definition: ptime.h:67
Definition: ptime.h:276
static PBoolean IsDaylightSavings()
Get flag indicating daylight savings is current.
Epoch format (e.g. 1234476388.123456)
Definition: ptime.h:425
int GetDay() const
Get the day of the month of the date.
Definition: ptime.h:241
static PString GetTimeSeparator()
Get the internationalised time separator.
static PString GetDateSeparator()
Get the internationalised date separator.
Definition: ptime.h:246
int GetSecond() const
Get the second of the time.
void SetTimestamp(time_t seconds, long usecs=0)
Set the time in seconds and microseconds.
Definition: ptime.h:271
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
long GetMicrosecond() const
Get the microsecond part of the time.
Definition: ptime.h:250
int GetDayOfYear() const
Get the day in the year of the date.
PBoolean IsFuture() const
Determine if the time is in the past or in the future.
time_t theTime
Number of seconds since 1 January 1970.
Definition: ptime.h:593
Long form ISO standard format. (eg. 2011-02-09 T 11:13:06 Z)
Definition: ptime.h:407
static PString GetMonthName(Months month, NameType type=FullName)
Get the internationalised month name string (1=Jan etc).
PBoolean IsValid() const
Determine if the timestamp is valid.
static PString GetTimeZoneString(TimeZoneType type=StandardTime)
Get the text identifier for the local time zone .
void SetCurrentTime()
Set the the objects time with the current time in the current time zone.
static PString GetTimePM()
Get the internationalised time PM string.
PObject * Clone() const
Create a copy of the time on the heap.