1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: Date and Time</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Date and Time </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_datetime_characteristics">wxDateTime Characteristics</a></li>
<li class="level1"><a href="#overview_datetime_timespandiff">wxDateSpan and wxTimeSpan</a></li>
<li class="level1"><a href="#overview_datetime_arithmetics">Date Arithmetics</a></li>
<li class="level1"><a href="#overview_datetime_timezones">Time Zone Considerations</a></li>
<li class="level1"><a href="#overview_datetime_dst">Daylight Saving Time (DST)</a></li>
<li class="level1"><a href="#overview_datetime_holidays">wxDateTime and Holidays</a></li>
<li class="level1"><a href="#overview_datetime_compat">Compatibility</a></li>
</ul>
</div>
<div class="textblock"><p>wxWidgets provides a set of powerful classes to work with dates and times.</p>
<p>Some of the supported features of <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> class are:</p>
<ul>
<li>Wide range: the range of supported dates goes from about 4714 B.C. to some 480 million years in the future. </li>
<li>Precision: not using floating point calculations anywhere ensures that the date calculations don't suffer from rounding errors. </li>
<li>Many features: not only all usual calculations with dates are supported, but also more exotic week and year day calculations, work day testing, standard astronomical functions, conversion to and from strings in either strict or free format. </li>
<li>Efficiency: objects of <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> are small (8 bytes) and working with them is fast</li>
</ul>
<p>There are 3 main classes declared in <code><a class="el" href="interface_2wx_2datetime_8h.html">wx/datetime.h</a></code>: except <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> itself which represents an absolute moment in time, there are also two classes - <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> and <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> - which represent the intervals of time.</p>
<p>There are also helper classes which are used together with <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a>: <a class="el" href="classwx_date_time_holiday_authority.html">wxDateTimeHolidayAuthority</a> which is used to determine whether a given date is a holiday or not and <a class="el" href="classwx_date_time_work_days.html">wxDateTimeWorkDays</a> which is a derivation of this class for which (only) Saturdays and Sundays are the holidays. See more about these classes in the discussion of the holidays (see <a class="el" href="overview_datetime.html#overview_datetime_holidays">wxDateTime and Holidays</a>).</p>
<p>Finally, in other parts of this manual you may find mentions of wxDate and wxTime classes. <a class="el" href="overview_datetime.html#overview_datetime_compat">Compatibility</a> are obsolete and superseded by <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a>.</p>
<h1><a class="anchor" id="overview_datetime_characteristics"></a>
wxDateTime Characteristics</h1>
<p><a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> stores the time as a signed number of milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - however this is not visible to the class users (in particular, dates prior to the Epoch are handled just as well (or as bad) as the dates after it). But it does mean that the best resolution which can be achieved with this class is 1 millisecond.</p>
<p>The size of <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> object is 8 bytes because it is represented as a 64 bit integer. The resulting range of supported dates is thus approximatively 580 million years, but due to the current limitations in the Gregorian calendar support, only dates from Nov 24, 4714BC are supported (this is subject to change if there is sufficient interest in doing it).</p>
<p>Finally, the internal representation is time zone independent (always in GMT) and the time zones only come into play when a date is broken into year/month/day components. See more about timezones below (see <a class="el" href="overview_datetime.html#overview_datetime_timezones">Time Zone Considerations</a>).</p>
<p>Currently, the only supported calendar is Gregorian one (which is used even for the dates prior to the historic introduction of this calendar which was first done on Oct 15, 1582 but is, generally speaking, country, and even region, dependent). Future versions will probably have Julian calendar support as well and support for other calendars (Maya, Hebrew, Chinese...) is not ruled out.</p>
<h1><a class="anchor" id="overview_datetime_timespandiff"></a>
wxDateSpan and wxTimeSpan</h1>
<p>While there is only one logical way to represent an absolute moment in the time (and hence only one <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> class), there are at least two methods to describe a time interval.</p>
<p>First, there is the direct and self-explaining way implemented by <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a>: it is just a difference in milliseconds between two moments in time. Adding or subtracting such an interval to <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> is always well-defined and is a fast operation.</p>
<p>But in the daily life other, calendar-dependent time interval specifications are used. For example, 'one month later' is commonly used. However, it is clear that this is not the same as <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> of 60*60*24*31 seconds because 'one month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether the year is leap or not).</p>
<p>This is why there is another class for representing such intervals called <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a>. It handles these sort of operations in the most natural way possible, but note that manipulating with intervals of this kind is not always well-defined. Consider, for example, Jan 31 + '1 month': this will give Feb 28 (or 29), i.e. the last day of February and not the non-existent Feb 31. Of course, this is what is usually wanted, but you still might be surprised to notice that now subtracting back the same interval from Feb 28 will result in Jan 28 and <b>not</b> Jan 31 we started with!</p>
<p>So, unless you plan to implement some kind of natural language parsing in the program, you should probably use <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> instead of <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> (which is also more efficient). However, <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> may be very useful in situations when you do need to understand what 'in a month' means (of course, it is just <code><a class="el" href="classwx_date_time.html#a6e6c37a0414bb4831e2cc03b37f498a2" title="Returns the object corresponding to the current time.">wxDateTime::Now()</a></code> + <a class="el" href="classwx_date_span.html#a14e488e59083c754acfd96adf5a291d9" title="Returns a date span object corresponding to one month.">wxDateSpan::Month()</a>).</p>
<h1><a class="anchor" id="overview_datetime_arithmetics"></a>
Date Arithmetics</h1>
<p>Many different operations may be performed with the dates, however not all of them make sense. For example, multiplying a date by a number is an invalid operation, even though multiplying either of the time span classes by a number is perfectly valid.</p>
<p>Here is what can be done:</p>
<ul>
<li><b>Addition:</b> a <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> or <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> can be added to <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> resulting in a new <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> object and also 2 objects of the same span class can be added together giving another object of the same class. </li>
<li><b>Subtraction:</b> the same types of operations as above are allowed and, additionally, a difference between two <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> objects can be taken and this will yield <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a>. </li>
<li><b>Multiplication:</b> a <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> or <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> object can be multiplied by an integer number resulting in an object of the same type. </li>
<li><b>Unary minus</b>: a <a class="el" href="classwx_time_span.html" title="wxTimeSpan class represents a time interval.">wxTimeSpan</a> or <a class="el" href="classwx_date_span.html" title="This class is a "logical time span" and is useful for implementing program logic for such things as...">wxDateSpan</a> object may finally be negated giving an interval of the same magnitude but of opposite time direction.</li>
</ul>
<p>For all these operations there are corresponding global (overloaded) operators and also member functions which are synonyms for them: Add(), Subtract() and Multiply(). Unary minus as well as composite assignment operations (like +=) are only implemented as members and Neg() is the synonym for unary minus.</p>
<h1><a class="anchor" id="overview_datetime_timezones"></a>
Time Zone Considerations</h1>
<p>Although the time is always stored internally in GMT, you will usually work in the local time zone. Because of this, all <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> constructors and setters which take the broken down date assume that these values are for the local time zone. Thus, <code>wxDateTime(1, wxDateTime::Jan, 1970)</code> will not correspond to the <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> Epoch unless you happen to live in the UK. All methods returning the date components (year, month, day, hour, minute, second...) will also return the correct values for the local time zone by default, so, generally, doing the natural things will lead to natural and correct results.</p>
<p>If you only want to do this, you may safely skip the rest of this section. However, if you want to work with different time zones, you should read it to the end.</p>
<p>In this (rare) case, you are still limited to the local time zone when constructing <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> objects, i.e. there is no way to construct a <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> corresponding to the given date in, say, Pacific Standard Time. To do it, you will need to call <a class="el" href="classwx_date_time.html#a254dff0f6fb8861216941dcc3d4fdc15" title="Transform the date to the given time zone.">wxDateTime::ToTimezone</a> or <a class="el" href="classwx_date_time.html#ad6ce9eb1fb237eda8013695ebd531af1" title="Modifies the object in place to represent the date in another time zone.">wxDateTime::MakeTimezone</a> methods to adjust the date for the target time zone. There are also special versions of these functions <a class="el" href="classwx_date_time.html#a4bddd303b09cc47c7251b01ca49dc04c" title="This is the same as calling ToTimezone() with the argument GMT0.">wxDateTime::ToUTC</a> and <a class="el" href="classwx_date_time.html#aa7e62cebf49c1c6b765e70ec19caedc0" title="This is the same as calling MakeTimezone() with the argument GMT0.">wxDateTime::MakeUTC</a> for the most common case - when the date should be constructed in UTC.</p>
<p>You also can just retrieve the value for some time zone without converting the object to it first. For this you may pass TimeZone argument to any of the methods which are affected by the time zone (all methods getting date components and the date formatting ones, for example). In particular, the Format() family of methods accepts a TimeZone parameter and this allows to simply print time in any time zone.</p>
<p>To see how to do it, the last issue to address is how to construct a TimeZone object which must be passed to all these methods. First of all, you may construct it manually by specifying the time zone offset in seconds from GMT, but usually you will just use one of the <a class="el" href="overview_datetime.html">Date and Time</a> and let the conversion constructor do the job.</p>
<p>I.e. you would just write</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a> dt(...whatever...);</div>
<div class="line">printf(<span class="stringliteral">"The time is %s in local time zone"</span>, dt.FormatTime().c_str());</div>
<div class="line">printf(<span class="stringliteral">"The time is %s in GMT"</span>, dt.FormatTime(wxDateTime::GMT).c_str());</div>
</div><!-- fragment --><h1><a class="anchor" id="overview_datetime_dst"></a>
Daylight Saving Time (DST)</h1>
<p>DST (a.k.a. 'summer time') handling is always a delicate task which is better left to the operating system which is supposed to be configured by the administrator to behave correctly. Unfortunately, when doing calculations with date outside of the range supported by the standard library, we are forced to deal with these issues ourselves.</p>
<p>Several functions are provided to calculate the beginning and end of DST in the given year and to determine whether it is in effect at the given moment or not, but they should not be considered as absolutely correct because, first of all, they only work more or less correctly for only a handful of countries (any information about other ones appreciated!) and even for them the rules may perfectly well change in the future.</p>
<p>The time zone handling methods (see <a class="el" href="overview_datetime.html#overview_datetime_timezones">Time Zone Considerations</a>) use these functions too, so they are subject to the same limitations.</p>
<h1><a class="anchor" id="overview_datetime_holidays"></a>
wxDateTime and Holidays</h1>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000003">Todo:</a></b></dt><dd>WRITE THIS DOC PARAGRAPH.</dd></dl>
<h1><a class="anchor" id="overview_datetime_compat"></a>
Compatibility</h1>
<p>The old classes for date/time manipulations ported from wxWidgets version 1.xx are still included but are reimplemented in terms of <a class="el" href="classwx_date_time.html" title="wxDateTime class represents an absolute moment in time.">wxDateTime</a>. However, using them is strongly discouraged because they have a few quirks/bugs and were not 'Y2K' compatible. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
