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}
  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{See also}
  58
  59 \helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
  60 \helpref{wxDateTime}{wxdatetime}
  61
  62
  63 \latexignore{\rtfignore{\wxheading{Members}}}
  64
  65 % wxDateSpan ctor
  66 \membersection{wxDateSpan::wxDateSpan}\label{wxdatespanwxdatespan}
  67
  68 \func{}{wxDateSpan}{\param{int }{years = $0$}, \param{int }{months = $0$}, \param{int }{weeks = $0$}, \param{int }{days = $0$}}
  69
  70 Constructs the date span object for the given number of years, months, weeks
  71 and days. Note that the weeks and days add together if both are given.
  72
  73 % wxDateSpan::Add
  74 \membersection{wxDateSpan::Add}\label{wxdatespanadd}
  75
  76 \constfunc{wxDateSpan}{Add}{\param{const wxDateSpan\& }{other}}
  77
  78 \func{wxDateSpan\&}{Add}{\param{const wxDateSpan\& }{other}}
  79
  80 \func{wxDateSpan\&}{operator$+=$}{\param{const wxDateSpan\& }{other}}
  81
  82 Returns the sum of two date spans. The first version returns a new object, the
  83 second and third ones modify this object in place.
  84
  85 % wxDateSpan::Day
  86 \membersection{wxDateSpan::Day}\label{wxdatespanday}
  87
  88 \func{static wxDateSpan}{Day}{\void}
  89
  90 Returns a date span object corresponding to one day.
  91
  92 \wxheading{See also}
  93
  94 \helpref{Days}{wxdatespandays}
  95
  96 % wxDateSpan::Days
  97 \membersection{wxDateSpan::Days}\label{wxdatespandays}
  98
  99 \func{static wxDateSpan}{Days}{\param{int }{days}}
 100
 101 Returns a date span object corresponding to the given number of days.
 102
 103 \wxheading{See also}
 104
 105 \helpref{Day}{wxdatespanday}
 106
 107 % wxDateSpan::GetDays
 108 \membersection{wxDateSpan::GetDays}\label{wxdatespangetdays}
 109
 110 \constfunc{int}{GetDays}{\void}
 111
 112 Returns the number of days (only, that it not counting the weeks component!)
 113 in this date span.
 114
 115 \wxheading{See also}
 116
 117 \helpref{GetTotalDays}{wxdatespangettotaldays}
 118
 119 % wxDateSpan::GetMonths
 120 \membersection{wxDateSpan::GetMonths}\label{wxdatespangetmonths}
 121
 122 \constfunc{int}{GetMonths}{\void}
 123
 124 Returns the number of the months (not counting the years) in this date span.
 125
 126 % wxDateSpan::GetTotalDays
 127 \membersection{wxDateSpan::GetTotalDays}\label{wxdatespangettotaldays}
 128
 129 \constfunc{int}{GetTotalDays}{\void}
 130
 131 Returns the combined number of days in this date span, counting both weeks and
 132 days. It still doesn't take neither months nor years into the account.
 133
 134 \wxheading{See also}
 135
 136 \helpref{GetWeeks}{wxdatespangetweeks}, \helpref{GetDays}{wxdatespangetdays}
 137
 138 % wxDateSpan::GetWeeks
 139 \membersection{wxDateSpan::GetWeeks}\label{wxdatespangetweeks}
 140
 141 \constfunc{int}{GetWeeks}{\void}
 142
 143 Returns the number of weeks in this date span.
 144
 145 \wxheading{See also}
 146
 147 \helpref{GetTotalDays}{wxdatespangettotaldays}
 148
 149 % wxDateSpan::GetYears
 150 \membersection{wxDateSpan::GetYears}\label{wxdatespangetyears}
 151
 152 \constfunc{int}{GetYears}{\void}
 153
 154 Returns the number of years in this date span.
 155
 156 % wxDateSpan::Month
 157 \membersection{wxDateSpan::Month}\label{wxdatespanmonth}
 158
 159 \func{static wxDateSpan}{Month}{\void}
 160
 161 Returns a date span object corresponding to one month.
 162
 163 \wxheading{See also}
 164
 165 \helpref{Months}{wxdatespanmonths}
 166
 167 % wxDateSpan::Months
 168 \membersection{wxDateSpan::Months}\label{wxdatespanmonths}
 169
 170 \func{static wxDateSpan}{Months}{\param{int }{mon}}
 171
 172 Returns a date span object corresponding to the given number of months.
 173
 174 \wxheading{See also}
 175
 176 \helpref{Month}{wxdatespanmonth}
 177
 178 % wxDateSpan::Multiply
 179 \membersection{wxDateSpan::Multiply}\label{wxdatespanmultiply}
 180
 181 \constfunc{wxDateSpan}{Multiply}{\param{int }{factor}}
 182
 183 \func{wxDateSpan\&}{Multiply}{\param{int }{factor}}
 184
 185 \func{wxDateSpan\&}{operator$*=$}{\param{int }{factor}}
 186
 187 Returns the product of the date span by the specified {\it factor}. The
 188 product is computed by multiplying each of the components by the factor.
 189
 190 The first version returns a new object, the second and third ones modify this
 191 object in place.
 192
 193 % wxDateSpan::Negate
 194 \membersection{wxDateSpan::Negate}\label{wxdatespannegate}
 195
 196 \constfunc{wxDateSpan}{Negate}{\void}
 197
 198 Returns the date span with the opposite sign.
 199
 200 \wxheading{See also}
 201
 202 \helpref{Neg}{wxdatespanneg}
 203
 204 % wxDateSpan::Neg
 205 \membersection{wxDateSpan::Neg}\label{wxdatespanneg}
 206
 207 \func{wxDateSpan\&}{Neg}{\void}
 208
 209 \func{wxDateSpan\&}{operator$-$}{\void}
 210
 211 Changes the sign of this date span.
 212
 213 \wxheading{See also}
 214
 215 \helpref{Negate}{wxdatespannegate}
 216
 217 % wxDateSpan::SetDays
 218 \membersection{wxDateSpan::SetDays}\label{wxdatespansetdays}
 219
 220 \func{wxDateSpan\&}{SetDays}{\param{int }{n}}
 221
 222 Sets the number of days (without modifying any other components) in this date
 223 span.
 224
 225 % wxDateSpan::SetYears
 226 \membersection{wxDateSpan::SetYears}\label{wxdatespansetyears}
 227
 228 \func{wxDateSpan\&}{SetYears}{\param{int }{n}}
 229
 230 Sets the number of years (without modifying any other components) in this date
 231 span.
 232
 233 % wxDateSpan::SetMonths
 234 \membersection{wxDateSpan::SetMonths}\label{wxdatespansetmonths}
 235
 236 \func{wxDateSpan\&}{SetMonths}{\param{int }{n}}
 237
 238 Sets the number of months (without modifying any other components) in this
 239 date span.
 240
 241 % wxDateSpan::SetWeeks
 242 \membersection{wxDateSpan::SetWeeks}\label{wxdatespansetweeks}
 243
 244 \func{wxDateSpan\&}{SetWeeks}{\param{int }{n}}
 245
 246 Sets the number of weeks (without modifying any other components) in this date
 247 span.
 248
 249 % wxDateSpan::Subtract
 250 \membersection{wxDateSpan::Subtract}\label{wxdatespansubtract}
 251
 252 \constfunc{wxDateSpan}{Subtract}{\param{const wxDateSpan\& }{other}}
 253
 254 \func{wxDateSpan\&}{Subtract}{\param{const wxDateSpan\& }{other}}
 255
 256 \func{wxDateSpan\&}{operator$+=$}{\param{const wxDateSpan\& }{other}}
 257
 258 Returns the difference of two date spans. The first version returns a new
 259 object, the second and third ones modify this object in place.
 260
 261 % wxDateSpan::Week
 262 \membersection{wxDateSpan::Week}\label{wxdatespanweek}
 263
 264 \func{static wxDateSpan}{Week}{\void}
 265
 266 Returns a date span object corresponding to one week.
 267
 268 \wxheading{See also}
 269
 270 \helpref{Weeks}{wxdatespanweeks}
 271
 272 % wxDateSpan::Weeks
 273 \membersection{wxDateSpan::Weeks}\label{wxdatespanweeks}
 274
 275 \func{static wxDateSpan}{Weeks}{\param{int }{weeks}}
 276
 277 Returns a date span object corresponding to the given number of weeks.
 278
 279 \wxheading{See also}
 280
 281 \helpref{Week}{wxdatespanweek}
 282
 283 % wxDateSpan::Year
 284 \membersection{wxDateSpan::Year}\label{wxdatespanyear}
 285
 286 \func{static wxDateSpan}{Year}{\void}
 287
 288 Returns a date span object corresponding to one year.
 289
 290 \wxheading{See also}
 291
 292 \helpref{Years}{wxdatespanyears}
 293
 294 % wxDateSpan::Years
 295 \membersection{wxDateSpan::Years}\label{wxdatespanyears}
 296
 297 \func{static wxDateSpan}{Years}{\param{int }{years}}
 298
 299 Returns a date span object corresponding to the given number of years.
 300
 301 \wxheading{See also}
 302
 303 \helpref{Year}{wxdatespanyear}
 304
 305 % wxDateSpan::operator==
 306 \membersection{wxDateSpan::operator$==$}\label{wxdatespanoperatorequal}
 307
 308 \constfunc{bool}{operator$==$}{\param{wxDateSpan\&}{ other}}
 309
 310 Returns {\tt true} if this date span is equal to the other one. Two date spans
 311 are considered equal if and only if they have the same number of years and
 312 months and the same total number of days (counting both days and weeks).
 313
 314 % wxDateSpan::operator!=
 315 \membersection{wxDateSpan::operator$!=$}\label{wxdatespanoperatornotequal}
 316
 317 \constfunc{bool}{operator$!=$}{\param{wxDateSpan\&}{ other}}
 318
 319 Returns {\tt true} if this date span is different from the other one.
 320
 321 \wxheading{See also}
 322
 323 \helpref{operator==}{wxdatespanoperatorequal}