X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/36c9828f702fb504b07968703bcd82f04196070a..346662b87a28fed132459db393cdd99132d1c5ca:/docs/doxygen/overviews/datetime.h diff --git a/docs/doxygen/overviews/datetime.h b/docs/doxygen/overviews/datetime.h index 756abb77fc..55de8ffca0 100644 --- a/docs/doxygen/overviews/datetime.h +++ b/docs/doxygen/overviews/datetime.h @@ -1,297 +1,244 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: datetime +// Name: datetime.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** - @page datetime_overview Date and time classes overview +@page overview_datetime Date and Time - 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 +Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl +@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 - wxWidgets provides a set of powerful classes to work with dates and times. Some - of the supported features of #wxDateTime class are: +
+@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. - Wide range +@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 - The range of supported dates goes from about 4714 B.C. to - some 480 million years in the future. +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 +class for which (only) Saturdays and Sundays are the holidays. See more about +these classes in the discussion of the holidays (see @ref overview_datetime_holidays). +Finally, in other parts of this manual you may find mentions of wxDate and +wxTime classes. @ref overview_datetime_compat are obsolete and +superseded by wxDateTime. - Precision +@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 - +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. +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 +(see @ref overview_datetime_timezones). - Not using floating point calculations anywhere ensures that - the date calculations don't suffer from rounding errors. +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. +@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. - Many features +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 +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 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()). - 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. +@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: - Efficiency +@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. +@li Unary minus: a wxTimeSpan or wxDateSpan object may finally be + negated giving an interval of the same magnitude but of opposite time + direction. - Objects of wxDateTime are small (8 bytes) and working with - them is fast +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 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 +which take the broken down date assume that these values are for the local +time zone. Thus, @c wxDateTime(1, wxDateTime::Jan, 1970) will not +correspond to the wxDateTime 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. +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. - @section alldatetimeclasses All date/time classes at a glance +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 wxDateTime::ToTimezone or wxDateTime::MakeTimezone +methods to adjust the date for the target time zone. There are also special +versions of these functions wxDateTime::ToUTC and wxDateTime::MakeUTC for +the most common case - when the date should be constructed in UTC. - 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 - 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 - superseded by wxDateTime. +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. - @section wxdatetimecharacteristics wxDateTime characteristics +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 overview_datetime and +let the conversion constructor do the job. - #wxDateTime 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. - 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. - 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. +I.e. you would just write - @section dateandtimespansdifference Difference between wxDateSpan and wxTimeSpan +@code +wxDateTime dt(...whatever...); +printf("The time is %s in local time zone", dt.FormatTime().c_str()); +printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str()); +@endcode - 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 - 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 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 - 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: +@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 (see @ref overview_datetime_timezones) use +these functions too, so they are subject to the same limitations. - @b Addition +@section overview_datetime_holidays wxDateTime and Holidays +@todo WRITE THIS DOC PARAGRAPH. - 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. +@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. - - - - @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. - - - - - - 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 - - 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 - which take the broken down date assume that these values are for the local - time zone. Thus, @c wxDateTime(1, wxDateTime::Jan, 1970) will not - correspond to the wxDateTime 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. - 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. - 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 - let the conversion constructor do the job. - I.e. you would just write - - @code - wxDateTime dt(...whatever...); - printf("The time is %s in local time zone", dt.FormatTime().c_str()); - printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str()); - @endcode - - - @section tdatedst 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 - - TODO. - - @section tdatecompatibility 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. - - */ - +*/