docs/latex/wx/datespan.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        datespan.tex
   3 %% Purpose:     wxDateSpan documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     04.04.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDateSpan}}\label{wxdatespan}
  13
  14 This class is a "logical time span" and is useful for implementing program
  15 logic for such things as "add one month to the date" which, in general,
  16 doesn't mean to add $60*60*24*31$ seconds to it, but to take the same date
  17 the next month (to understand that this is indeed different consider adding
  18 one month to Feb, 15 -- we want to get Mar, 15, of course).
  19
  20 When adding a month to the date, all lesser components (days, hours, ...)
  21 won't be changed unless the resulting date would be invalid: for example,
  22 Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31.
  23
  24 Because of this feature, adding and subtracting back again the same
  25 wxDateSpan will {\bf not}, in general give back the original date: Feb 28 - 1
  26 month will be Jan 28, not Jan 31!
  27
  28 wxDateSpan objects can be either positive or negative. They may be
  29 multiplied by scalars which multiply all deltas by the scalar: i.e.
  30 $2*(1 \hbox{ month and } 1 \hbox{ day})$ is $2$ months and $2$ days. They can
  31 be added together and with \helpref{wxDateTime}{wxdatetime} or
  32 \helpref{wxTimeSpan}{wxtimespan}, but the type of result is different for each
  33 case.
  34
  35 Beware about weeks: if you specify both weeks and days, the total number of
  36 days added will be $7*\hbox{weeks} + \hbox{days}$! See also GetTotalDays()
  37 function.
  38
  39 Equality operators are defined for wxDateSpans. Two datespans are equal if
  40 and only if they both give the same target date when added to {\bf every}\rtfsp
  41 source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30),
  42 because they don't give the same date when added to 1 Feb. But
  43 wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2)
  44
  45 Finally, notice that for adding hours, minutes and so on you don't need this
  46 class at all: \helpref{wxTimeSpan}{wxtimespan} will do the job because there
  47 are no subtleties associated with those (we don't support leap seconds).
  48
  49 \wxheading{Derived from}
  50
  51 No base class
  52
  53 \wxheading{Include files}
  54
  55 <wx/datetime.h>
  56
  57 \wxheading{Library}
  58
  59 \helpref{wxBase}{librarieslist}
  60
  61 \wxheading{See also}
  62
  63 \helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
  64 \helpref{wxDateTime}{wxdatetime}
  65
  66
  67 \latexignore{\rtfignore{\wxheading{Members}}}
  68
  69 % wxDateSpan ctor
  70 \membersection{wxDateSpan::wxDateSpan}\label{wxdatespanwxdatespan}
  71
  72 \func{}{wxDateSpan}{\param{int }{years = $0$}, \param{int }{months = $0$}, \param{int }{weeks = $0$}, \param{int }{days = $0$}}
  73
  74 Constructs the date span object for the given number of years, months, weeks
  75 and days. Note that the weeks and days add together if both are given.
  76
  77 % wxDateSpan::Add
  78 \membersection{wxDateSpan::Add}\label{wxdatespanadd}
  79
  80 \constfunc{wxDateSpan}{Add}{\param{const wxDateSpan\& }{other}}
  81
  82 \func{wxDateSpan\&}{Add}{\param{const wxDateSpan\& }{other}}
  83
  84 \func{wxDateSpan\&}{operator$+=$}{\param{const wxDateSpan\& }{other}}
  85
  86 Returns the sum of two date spans. The first version returns a new object, the
  87 second and third ones modify this object in place.
  88
  89 % wxDateSpan::Day
  90 \membersection{wxDateSpan::Day}\label{wxdatespanday}
  91
  92 \func{static wxDateSpan}{Day}{\void}
  93
  94 Returns a date span object corresponding to one day.
  95
  96 \wxheading{See also}
  97
  98 \helpref{Days}{wxdatespandays}
  99
 100 % wxDateSpan::Days
 101 \membersection{wxDateSpan::Days}\label{wxdatespandays}
 102
 103 \func{static wxDateSpan}{Days}{\param{int }{days}}
 104
 105 Returns a date span object corresponding to the given number of days.
 106
 107 \wxheading{See also}
 108
 109 \helpref{Day}{wxdatespanday}
 110
 111 % wxDateSpan::GetDays
 112 \membersection{wxDateSpan::GetDays}\label{wxdatespangetdays}
 113
 114 \constfunc{int}{GetDays}{\void}
 115
 116 Returns the number of days (only, that it not counting the weeks component!)
 117 in this date span.
 118
 119 \wxheading{See also}
 120
 121 \helpref{GetTotalDays}{wxdatespangettotaldays}
 122
 123 % wxDateSpan::GetMonths
 124 \membersection{wxDateSpan::GetMonths}\label{wxdatespangetmonths}
 125
 126 \constfunc{int}{GetMonths}{\void}
 127
 128 Returns the number of the months (not counting the years) in this date span.
 129
 130 % wxDateSpan::GetTotalDays
 131 \membersection{wxDateSpan::GetTotalDays}\label{wxdatespangettotaldays}
 132
 133 \constfunc{int}{GetTotalDays}{\void}
 134
 135 Returns the combined number of days in this date span, counting both weeks and
 136 days. It still doesn't take neither months nor years into the account.
 137
 138 \wxheading{See also}
 139
 140 \helpref{GetWeeks}{wxdatespangetweeks}, \helpref{GetDays}{wxdatespangetdays}
 141
 142 % wxDateSpan::GetWeeks
 143 \membersection{wxDateSpan::GetWeeks}\label{wxdatespangetweeks}
 144
 145 \constfunc{int}{GetWeeks}{\void}
 146
 147 Returns the number of weeks in this date span.
 148
 149 \wxheading{See also}
 150
 151 \helpref{GetTotalDays}{wxdatespangettotaldays}
 152
 153 % wxDateSpan::GetYears
 154 \membersection{wxDateSpan::GetYears}\label{wxdatespangetyears}
 155
 156 \constfunc{int}{GetYears}{\void}
 157
 158 Returns the number of years in this date span.
 159
 160 % wxDateSpan::Month
 161 \membersection{wxDateSpan::Month}\label{wxdatespanmonth}
 162
 163 \func{static wxDateSpan}{Month}{\void}
 164
 165 Returns a date span object corresponding to one month.
 166
 167 \wxheading{See also}
 168
 169 \helpref{Months}{wxdatespanmonths}
 170
 171 % wxDateSpan::Months
 172 \membersection{wxDateSpan::Months}\label{wxdatespanmonths}
 173
 174 \func{static wxDateSpan}{Months}{\param{int }{mon}}
 175
 176 Returns a date span object corresponding to the given number of months.
 177
 178 \wxheading{See also}
 179
 180 \helpref{Month}{wxdatespanmonth}
 181
 182 % wxDateSpan::Multiply
 183 \membersection{wxDateSpan::Multiply}\label{wxdatespanmultiply}
 184
 185 \constfunc{wxDateSpan}{Multiply}{\param{int }{factor}}
 186
 187 \func{wxDateSpan\&}{Multiply}{\param{int }{factor}}
 188
 189 \func{wxDateSpan\&}{operator$*=$}{\param{int }{factor}}
 190
 191 Returns the product of the date span by the specified {\it factor}. The
 192 product is computed by multiplying each of the components by the factor.
 193
 194 The first version returns a new object, the second and third ones modify this
 195 object in place.
 196
 197 % wxDateSpan::Negate
 198 \membersection{wxDateSpan::Negate}\label{wxdatespannegate}
 199
 200 \constfunc{wxDateSpan}{Negate}{\void}
 201
 202 Returns the date span with the opposite sign.
 203
 204 \wxheading{See also}
 205
 206 \helpref{Neg}{wxdatespanneg}
 207
 208 % wxDateSpan::Neg
 209 \membersection{wxDateSpan::Neg}\label{wxdatespanneg}
 210
 211 \func{wxDateSpan\&}{Neg}{\void}
 212
 213 \func{wxDateSpan\&}{operator$-$}{\void}
 214
 215 Changes the sign of this date span.
 216
 217 \wxheading{See also}
 218
 219 \helpref{Negate}{wxdatespannegate}
 220
 221 % wxDateSpan::SetDays
 222 \membersection{wxDateSpan::SetDays}\label{wxdatespansetdays}
 223
 224 \func{wxDateSpan\&}{SetDays}{\param{int }{n}}
 225
 226 Sets the number of days (without modifying any other components) in this date
 227 span.
 228
 229 % wxDateSpan::SetYears
 230 \membersection{wxDateSpan::SetYears}\label{wxdatespansetyears}
 231
 232 \func{wxDateSpan\&}{SetYears}{\param{int }{n}}
 233
 234 Sets the number of years (without modifying any other components) in this date
 235 span.
 236
 237 % wxDateSpan::SetMonths
 238 \membersection{wxDateSpan::SetMonths}\label{wxdatespansetmonths}
 239
 240 \func{wxDateSpan\&}{SetMonths}{\param{int }{n}}
 241
 242 Sets the number of months (without modifying any other components) in this
 243 date span.
 244
 245 % wxDateSpan::SetWeeks
 246 \membersection{wxDateSpan::SetWeeks}\label{wxdatespansetweeks}
 247
 248 \func{wxDateSpan\&}{SetWeeks}{\param{int }{n}}
 249
 250 Sets the number of weeks (without modifying any other components) in this date
 251 span.
 252
 253 % wxDateSpan::Subtract
 254 \membersection{wxDateSpan::Subtract}\label{wxdatespansubtract}
 255
 256 \constfunc{wxDateSpan}{Subtract}{\param{const wxDateSpan\& }{other}}
 257
 258 \func{wxDateSpan\&}{Subtract}{\param{const wxDateSpan\& }{other}}
 259
 260 \func{wxDateSpan\&}{operator$+=$}{\param{const wxDateSpan\& }{other}}
 261
 262 Returns the difference of two date spans. The first version returns a new
 263 object, the second and third ones modify this object in place.
 264
 265 % wxDateSpan::Week
 266 \membersection{wxDateSpan::Week}\label{wxdatespanweek}
 267
 268 \func{static wxDateSpan}{Week}{\void}
 269
 270 Returns a date span object corresponding to one week.
 271
 272 \wxheading{See also}
 273
 274 \helpref{Weeks}{wxdatespanweeks}
 275
 276 % wxDateSpan::Weeks
 277 \membersection{wxDateSpan::Weeks}\label{wxdatespanweeks}
 278
 279 \func{static wxDateSpan}{Weeks}{\param{int }{weeks}}
 280
 281 Returns a date span object corresponding to the given number of weeks.
 282
 283 \wxheading{See also}
 284
 285 \helpref{Week}{wxdatespanweek}
 286
 287 % wxDateSpan::Year
 288 \membersection{wxDateSpan::Year}\label{wxdatespanyear}
 289
 290 \func{static wxDateSpan}{Year}{\void}
 291
 292 Returns a date span object corresponding to one year.
 293
 294 \wxheading{See also}
 295
 296 \helpref{Years}{wxdatespanyears}
 297
 298 % wxDateSpan::Years
 299 \membersection{wxDateSpan::Years}\label{wxdatespanyears}
 300
 301 \func{static wxDateSpan}{Years}{\param{int }{years}}
 302
 303 Returns a date span object corresponding to the given number of years.
 304
 305 \wxheading{See also}
 306
 307 \helpref{Year}{wxdatespanyear}
 308
 309 % wxDateSpan::operator==
 310 \membersection{wxDateSpan::operator$==$}\label{wxdatespanoperatorequal}
 311
 312 \constfunc{bool}{operator$==$}{\param{wxDateSpan\&}{ other}}
 313
 314 Returns {\tt true} if this date span is equal to the other one. Two date spans
 315 are considered equal if and only if they have the same number of years and
 316 months and the same total number of days (counting both days and weeks).
 317
 318 % wxDateSpan::operator!=
 319 \membersection{wxDateSpan::operator$!=$}\label{wxdatespanoperatornotequal}
 320
 321 \constfunc{bool}{operator$!=$}{\param{wxDateSpan\&}{ other}}
 322
 323 Returns {\tt true} if this date span is different from the other one.
 324
 325 \wxheading{See also}
 326
 327 \helpref{operator==}{wxdatespanoperatorequal}
 328