another batch of topic overviews reviewing
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52014 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
@@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: datetime
|
||||
// Name: datetime.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@@ -8,100 +8,64 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page datetime_overview Date and time classes overview
|
||||
@page overview_datetime Date and time classes overview
|
||||
|
||||
Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
|
||||
#Introduction
|
||||
@ref alldatetimeclasses_overview
|
||||
@ref datetimecharacteristics_overview
|
||||
@ref dateandtimespansdifference_overview
|
||||
@ref tdatearithm_overview
|
||||
@ref tdatetimezones_overview
|
||||
#Daylight saving time (DST)
|
||||
@ref tdateholidays_overview
|
||||
#Compatibility
|
||||
|
||||
@li @ref overview_datetime_introduction
|
||||
@li @ref overview_datetime_classes
|
||||
@li @ref overview_datetime_characteristics
|
||||
@li @ref overview_datetime_timespandiff
|
||||
@li @ref overview_datetime_arithmetics
|
||||
@li @ref overview_datetime_timezones
|
||||
@li @ref overview_datetime_dst
|
||||
@li @ref overview_datetime_holidays
|
||||
@li @ref overview_datetime_compat
|
||||
|
||||
|
||||
@section introductiontowxdatetime Introduction
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_datetime_introduction Introduction
|
||||
|
||||
wxWidgets provides a set of powerful classes to work with dates and times. Some
|
||||
of the supported features of #wxDateTime class are:
|
||||
|
||||
@li Wide range: the range of supported dates goes from about 4714 B.C. to
|
||||
some 480 million years in the future.
|
||||
|
||||
@li Precision: not using floating point calculations anywhere ensures that
|
||||
the date calculations don't suffer from rounding errors.
|
||||
|
||||
@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 Efficiency: objects of wxDateTime are small (8 bytes) and working with
|
||||
them is fast
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_classes All date/time classes at a glance
|
||||
|
||||
There are 3 main classes declared in @c wx/datetime.h: except #wxDateTime itself
|
||||
which represents an absolute moment in time, there are also two classes -
|
||||
#wxTimeSpan and #wxDateSpan - which represent the intervals of time.
|
||||
|
||||
|
||||
Wide range
|
||||
|
||||
|
||||
|
||||
|
||||
The range of supported dates goes from about 4714 B.C. to
|
||||
some 480 million years in the future.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Precision
|
||||
|
||||
|
||||
|
||||
|
||||
Not using floating point calculations anywhere ensures that
|
||||
the date calculations don't suffer from rounding errors.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Efficiency
|
||||
|
||||
|
||||
|
||||
|
||||
Objects of wxDateTime are small (8 bytes) and working with
|
||||
them is fast
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@section alldatetimeclasses All date/time classes at a glance
|
||||
|
||||
There are 3 main classes declared in @c wx/datetime.h: except
|
||||
#wxDateTime itself which represents an absolute
|
||||
moment in time, there are also two classes -
|
||||
#wxTimeSpan and #wxDateSpan - which
|
||||
represent the intervals of time.
|
||||
There are also helper classes which are used together with wxDateTime:
|
||||
#wxDateTimeHolidayAuthority which is used
|
||||
to determine whether a given date is a holiday or not and
|
||||
#wxDateTimeWorkDays which is a derivation of this
|
||||
#wxDateTimeHolidayAuthority which is used to determine whether a given date
|
||||
is a holiday or not and #wxDateTimeWorkDays 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.
|
||||
|
||||
Finally, in other parts of this manual you may find mentions of wxDate and
|
||||
wxTime classes. @ref tdatecompatibility_overview are obsolete and
|
||||
wxTime classes. @ref overview_datetime_compat are obsolete and
|
||||
superseded by wxDateTime.
|
||||
|
||||
@section wxdatetimecharacteristics wxDateTime characteristics
|
||||
|
||||
|
||||
@section overview_datetime_characteristics wxDateTime characteristics
|
||||
|
||||
#wxDateTime stores the time as a signed number of
|
||||
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
|
||||
@@ -109,15 +73,17 @@
|
||||
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.
|
||||
|
||||
The size of wxDateTime 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).
|
||||
|
||||
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.
|
||||
year/month/day components. See more about #timezones below.
|
||||
|
||||
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
|
||||
@@ -125,20 +91,25 @@
|
||||
as well and support for other calendars (Maya, Hebrew, Chinese...) is not
|
||||
ruled out.
|
||||
|
||||
@section dateandtimespansdifference Difference between wxDateSpan and wxTimeSpan
|
||||
|
||||
|
||||
@section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
|
||||
|
||||
While there is only one logical way to represent an absolute moment in the
|
||||
time (and hence only one wxDateTime class), there are at least two methods to
|
||||
describe a time interval.
|
||||
|
||||
First, there is the direct and self-explaining way implemented by
|
||||
#wxTimeSpan: it is just a difference in milliseconds
|
||||
between two moments in time. Adding or subtracting such an interval to
|
||||
wxDateTime is always well-defined and is a fast operation.
|
||||
|
||||
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 wxTimeSpan 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).
|
||||
|
||||
This is why there is another class for representing such intervals called
|
||||
#wxDateSpan. It handles these sort of operations in the
|
||||
most natural way possible, but note that manipulating with intervals of
|
||||
@@ -148,82 +119,47 @@
|
||||
still might be surprised to notice that now subtracting back the same
|
||||
interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
|
||||
with!
|
||||
|
||||
So, unless you plan to implement some kind of natural language parsing in the
|
||||
program, you should probably use wxTimeSpan instead of wxDateSpan (which is
|
||||
also more efficient). However, wxDateSpan may be very useful in situations
|
||||
when you do need to understand what 'in a month' means (of course, it is
|
||||
just @c wxDateTime::Now() + wxDateSpan::Month()).
|
||||
|
||||
@section tdatearithm Date arithmetics
|
||||
|
||||
|
||||
@section overview_datetime_arithmetics Date arithmetics
|
||||
|
||||
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.
|
||||
|
||||
Here is what can be done:
|
||||
|
||||
@li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime
|
||||
resulting in a new wxDateTime object and also 2 objects of the same span class
|
||||
can be added together giving another object of the same class.
|
||||
|
||||
@li @b Subtraction: the same types of operations as above are
|
||||
allowed and, additionally, a difference between two wxDateTime objects can be
|
||||
taken and this will yield wxTimeSpan.
|
||||
|
||||
@li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
|
||||
multiplied by an integer number resulting in an object of the same type.
|
||||
|
||||
|
||||
|
||||
@b Addition
|
||||
|
||||
|
||||
|
||||
|
||||
a wxTimeSpan or wxDateSpan can be added to wxDateTime
|
||||
resulting in a new wxDateTime object and also 2 objects of the same span class
|
||||
can be added together giving another object of the same class.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@b Subtraction
|
||||
|
||||
|
||||
|
||||
|
||||
the same types of operations as above are
|
||||
allowed and, additionally, a difference between two wxDateTime objects can be
|
||||
taken and this will yield wxTimeSpan.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@b Multiplication
|
||||
|
||||
|
||||
|
||||
|
||||
a wxTimeSpan or wxDateSpan object can be
|
||||
multiplied by an integer number resulting in an object of the same type.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@b Unary minus
|
||||
|
||||
|
||||
|
||||
|
||||
a wxTimeSpan or wxDateSpan object may finally be
|
||||
negated giving an interval of the same magnitude but of opposite time
|
||||
direction.
|
||||
|
||||
|
||||
|
||||
|
||||
@li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
|
||||
negated giving an interval of the same magnitude but of opposite time
|
||||
direction.
|
||||
|
||||
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.
|
||||
|
||||
@section tdatetimezones Time zone considerations
|
||||
|
||||
|
||||
@section overview_datetime_timezones Time zone considerations
|
||||
|
||||
Although the time is always stored internally in GMT, you will usually work in
|
||||
the local time zone. Because of this, all wxDateTime constructors and setters
|
||||
@@ -234,28 +170,31 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
In this (rare) case, you are still limited to the local time zone when
|
||||
constructing wxDateTime objects, i.e. there is no way to construct a
|
||||
wxDateTime corresponding to the given date in, say, Pacific Standard Time.
|
||||
To do it, you will need to call #ToTimezone or
|
||||
#MakeTimezone methods to adjust the date for
|
||||
the target time zone. There are also special versions of these functions
|
||||
#ToUTC and #MakeUTC for
|
||||
the most common case - when the date should be constructed in UTC.
|
||||
To do it, you will need to call #ToTimezone or #MakeTimezone methods to adjust
|
||||
the date for the target time zone. There are also special versions of these functions
|
||||
#ToUTC and #MakeUTC for the most common case - when the date should be constructed in UTC.
|
||||
|
||||
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.
|
||||
|
||||
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 @ref datetime_overview and
|
||||
usually you will just use one of the @ref overview_datetime and
|
||||
let the conversion constructor do the job.
|
||||
|
||||
I.e. you would just write
|
||||
|
||||
@code
|
||||
@@ -265,33 +204,39 @@
|
||||
@endcode
|
||||
|
||||
|
||||
@section tdatedst Daylight saving time (DST)
|
||||
|
||||
@section overview_datetime_dst Daylight saving time (DST)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
The time zone handling #methods use these functions
|
||||
too, so they are subject to the same limitations.
|
||||
|
||||
@section tdateholidays wxDateTime and Holidays
|
||||
|
||||
|
||||
@section overview_datetime_holidays wxDateTime and Holidays
|
||||
|
||||
TODO.
|
||||
|
||||
@section tdatecompatibility Compatibility
|
||||
|
||||
|
||||
@section overview_datetime_compat Compatibility
|
||||
|
||||
The old classes for date/time manipulations ported from wxWidgets version 1.xx
|
||||
are still included but are reimplemented in terms of wxDateTime. However, using
|
||||
them is strongly discouraged because they have a few quirks/bugs and were not
|
||||
'Y2K' compatible.
|
||||
|
||||
*/
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user