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