docs/latex/wx/datetime.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        datetime.tex
   3 %% Purpose:     wxDateTime documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     07.03.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% Licence:     wxWindows licence
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDateTime}}\label{wxdatetime}
  13
  14 wxDateTime class represents an absolute moment in the time.
  15
  16 \wxheading{Types}
  17
  18 The type {\tt wxDateTime\_t} is typedefed as {\tt unsigned short} and is used
  19 to contain the number of years, hours, minutes, seconds and milliseconds.
  20
  21 \wxheading{Constants}
  22
  23 Global constant {\tt wxDefaultDateTime} and synonym for it {\tt
  24 wxInvalidDateTime} are defined. This constant will be different from any valid
  25 wxDateTime object.
  26
  27 All the following constants are defined inside wxDateTime class (i.e., to refer to
  28 them you should prepend their names with {\tt wxDateTime::}).
  29
  30 Time zone symbolic names:\label{wxdatetimetimezones}
  31
  32 \begin{verbatim}
  33     enum TZ
  34     {
  35         // the time in the current time zone
  36         Local,
  37
  38         // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
  39         // consequent numbers, so writing something like `GMT0 + offset' is
  40         // safe if abs(offset) <= 12
  41
  42         // underscore stands for minus
  43         GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
  44         GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
  45         GMT0,
  46         GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
  47         GMT7, GMT8, GMT9, GMT10, GMT11, GMT12,
  48         // Note that GMT12 and GMT_12 are not the same: there is a difference
  49         // of exactly one day between them
  50
  51         // some symbolic names for TZ
  52
  53         // Europe
  54         WET = GMT0,                         // Western Europe Time
  55         WEST = GMT1,                        // Western Europe Summer Time
  56         CET = GMT1,                         // Central Europe Time
  57         CEST = GMT2,                        // Central Europe Summer Time
  58         EET = GMT2,                         // Eastern Europe Time
  59         EEST = GMT3,                        // Eastern Europe Summer Time
  60         MSK = GMT3,                         // Moscow Time
  61         MSD = GMT4,                         // Moscow Summer Time
  62
  63         // US and Canada
  64         AST = GMT_4,                        // Atlantic Standard Time
  65         ADT = GMT_3,                        // Atlantic Daylight Time
  66         EST = GMT_5,                        // Eastern Standard Time
  67         EDT = GMT_4,                        // Eastern Daylight Saving Time
  68         CST = GMT_6,                        // Central Standard Time
  69         CDT = GMT_5,                        // Central Daylight Saving Time
  70         MST = GMT_7,                        // Mountain Standard Time
  71         MDT = GMT_6,                        // Mountain Daylight Saving Time
  72         PST = GMT_8,                        // Pacific Standard Time
  73         PDT = GMT_7,                        // Pacific Daylight Saving Time
  74         HST = GMT_10,                       // Hawaiian Standard Time
  75         AKST = GMT_9,                       // Alaska Standard Time
  76         AKDT = GMT_8,                       // Alaska Daylight Saving Time
  77
  78         // Australia
  79
  80         A_WST = GMT8,                       // Western Standard Time
  81         A_CST = GMT12 + 1,                  // Central Standard Time (+9.5)
  82         A_EST = GMT10,                      // Eastern Standard Time
  83         A_ESST = GMT11,                     // Eastern Summer Time
  84
  85         // Universal Coordinated Time = the new and politically correct name
  86         // for GMT
  87         UTC = GMT0
  88     };
  89 \end{verbatim}
  90
  91 Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
  92 Inv\_Month for an invalid.month value are the values of {\tt wxDateTime::Month}
  93 enum.
  94
  95 Likely, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv\_WeekDay are the values in
  96 {\tt wxDateTime::WeekDay} enum.
  97
  98 Finally, Inv\_Year is defined to be an invalid value for year parameter.
  99
 100 \wxheading{Derived from}
 101
 102 No base class
 103
 104 \wxheading{Include files}
 105
 106 <wx/datetime.h>
 107
 108 \wxheading{See also}
 109
 110 \helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
 111 \helpref{wxTimeSpan}{wxtimespan},\rtfsp
 112 \helpref{wxDateSpan}{wxdatespan},\rtfsp
 113 \helpref{wxCalendarCtrl}{wxcalendarctrl}
 114
 115 \latexignore{\rtfignore{\wxheading{Function groups}}}
 116
 117 \membersection{Static functions}
 118
 119 For convinience, all static functions are collected here. These functions
 120 either set or return the static variables of wxDateSpan (the country), return
 121 the current moment, year, month or number of days in it, or do some general
 122 calendar-related actions.
 123
 124 \helpref{SetCountry}{wxdatetimesetcountry}\\
 125 \helpref{GetCountry}{wxdatetimegetcountry}\\
 126 \helpref{IsWestEuropeanCountry}{wxdatetimeiswesteuropeancountry}\\
 127 \helpref{GetCurrentYear}{wxdatetimegetcurrentyear}\\
 128 \helpref{ConvertYearToBC}{wxdatetimeconvertyeartobc}\\
 129 \helpref{GetCurrentMonth}{wxdatetimegetcurrentmonth}\\
 130 \helpref{IsLeapYear}{wxdatetimeisleapyear}\\
 131 \helpref{GetCentury}{wxdatetimegetcentury}\\
 132 \helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
 133 \helpref{GetNumberOfDays}{wxdatetimegetnumberofdays}\\
 134 \helpref{GetMonthName}{wxdatetimegetmonthname}\\
 135 \helpref{GetWeekDayName}{wxdatetimegetweekdayname}\\
 136 \helpref{GetAmPmStrings}{wxdatetimegetampmstrings}\\
 137 \helpref{IsDSTApplicable}{wxdatetimeisdstapplicable}\\
 138 \helpref{GetBeginDST}{wxdatetimegetbegindst}\\
 139 \helpref{GetEndDST}{wxdatetimegetenddst}\\
 140 \helpref{Now}{wxdatetimenow}\\
 141 \helpref{Today}{wxdatetimetoday}
 142
 143 \membersection{Constructors, assignment operators and setters}
 144
 145 \membersection{Accessors}
 146
 147 \membersection{Date comparison}
 148
 149 \membersection{Date arithmetics}
 150
 151 \membersection{Parsing and formatting dates}
 152
 153 \membersection{Calendar calculations}
 154
 155 \membersection{Astronomical/historical functions}
 156
 157 \membersection{Time zone support}
 158
 159 \helponly{\insertatlevel{2}{
 160
 161 \wxheading{Members}
 162
 163 }}
 164
 165 \membersection{wxDateTime::ConvertYearToBC}{wxdatetimeconvertyeartobc}
 166
 167 \func{static int}{ConvertYearToBC}(int year);
 168
 169 Converts the year in absolute notation (i.e. a number which can be negative,
 170 positive or zero) to the year in BC/AD notation. For the positive years,
 171 nothing is done, but the year 0 is year 1 BC and so for other years there is a
 172 difference of 1.
 173
 174 This function should be used like this:
 175
 176 \begin{verbatim}
 177     wxDateTime dt(...);
 178     int y = dt.GetYear();
 179     printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC");
 180 \end{verbatim}
 181
 182 \membersection{wxDateTime::GetAmPmStrings}{wxdatetimegetampmstrings}
 183
 184 \func{static void}{GetAmPmStrings}{\param{wxString *}{am}, \param{wxString *}{pm}}
 185
 186 \membersection{wxDateTime::GetBeginDST}{wxdatetimegetbegindst}
 187
 188 \func{static wxDateTime}{GetBeginDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
 189
 190 \membersection{wxDateTime::GetCountry}{wxdatetimegetcountry}
 191
 192 \func{static Country}{GetCountry}{\void}
 193
 194 \membersection{wxDateTime::GetCurrentYear}{wxdatetimegetcurrentyear}
 195
 196 \func{static int}{GetCurrentYear}{\param{Calendar }{cal = Gregorian}}
 197
 198 \membersection{wxDateTime::GetCurrentMonth}{wxdatetimegetcurrentmonth}
 199
 200 \func{static Month}{GetCurrentMonth}{\param{Calendar }{cal = Gregorian}}
 201
 202 \membersection{wxDateTime::GetCentury}{wxdatetimegetcentury}
 203
 204 \func{static int}{GetCentury}{\param{int }{year = Inv\_Year}}
 205
 206 \membersection{wxDateTime::GetEndDST}{wxdatetimegetenddst}
 207
 208 \func{static wxDateTime}{GetEndDST}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
 209
 210 \membersection{wxDateTime::GetMonthName}{wxdatetimegetmonthname}
 211
 212 \func{static wxString}{GetMonthName}{\param{Month }{month}, \param{NameFlags }{flags = Name\_Full}}
 213
 214 \membersection{wxDateTime::GetNumberOfDays}{wxdatetimegetnumberofdays}
 215
 216 \func{static wxDateTime\_t}{GetNumberOfDays}{\param{int }{year}, \param{Calendar }{cal = Gregorian}}
 217
 218 \membersection{wxDateTime::GetNumberOfDays}{wxdatetimegetnumberofdays}
 219
 220 \func{static wxDateTime\_t}{GetNumberOfDays}{\param{Month }{month}, \param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}
 221
 222 \membersection{wxDateTime::GetWeekDayName}{wxdatetimegetweekdayname}
 223
 224 \func{static wxString}{GetWeekDayName}{\param{WeekDay }{weekday}, \param{NameFlags }{flags = Name\_Full}}
 225
 226 \membersection{wxDateTime::IsLeapYear}{wxdatetimeisleapyear}
 227
 228 \func{static bool}{IsLeapYear}{\param{int }{year = Inv\_Year}, \param{Calendar }{cal = Gregorian}}
 229
 230 \membersection{wxDateTime::IsWestEuropeanCountry}{wxdatetimeiswesteuropeancountry}
 231
 232 \func{static bool}{IsWestEuropeanCountry}{\param{Country }{country = Country\_Default}}
 233
 234 \membersection{wxDateTime::IsDSTApplicable}{wxdatetimeisdstapplicable}
 235
 236 \func{static bool}{IsDSTApplicable}{\param{int }{year = Inv\_Year}, \param{Country }{country = Country\_Default}}
 237
 238 \membersection{wxDateTime::Now}{wxdatetimenow}
 239
 240 \func{static wxDateTime}{Now}{\void}
 241
 242 \membersection{wxDateTime::SetCountry}{wxdatetimesetcountry}
 243
 244 \func{static void}{SetCountry}{\param{Country }{country}}
 245
 246 \membersection{wxDateTime::Today}{wxdatetimetoday}
 247
 248 \func{static wxDateTime}{Today}{\void}
 249