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: datespan.tex 39409 2006-05-28 23:56:51Z VZ $ 8%% Copyright: (c) Vadim Zeitlin 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxDateSpan}}\label{wxdatespan} 13 14This class is a "logical time span" and is useful for implementing program 15logic for such things as "add one month to the date" which, in general, 16doesn't mean to add $60*60*24*31$ seconds to it, but to take the same date 17the next month (to understand that this is indeed different consider adding 18one month to Feb, 15 -- we want to get Mar, 15, of course). 19 20When adding a month to the date, all lesser components (days, hours, ...) 21won't be changed unless the resulting date would be invalid: for example, 22Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31. 23 24Because of this feature, adding and subtracting back again the same 25wxDateSpan will {\bf not}, in general give back the original date: Feb 28 - 1 26month will be Jan 28, not Jan 31! 27 28wxDateSpan objects can be either positive or negative. They may be 29multiplied 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 31be added together and with \helpref{wxDateTime}{wxdatetime} or 32\helpref{wxTimeSpan}{wxtimespan}, but the type of result is different for each 33case. 34 35Beware about weeks: if you specify both weeks and days, the total number of 36days added will be $7*\hbox{weeks} + \hbox{days}$! See also GetTotalDays() 37function. 38 39Equality operators are defined for wxDateSpans. Two datespans are equal if 40and only if they both give the same target date when added to {\bf every}\rtfsp 41source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30), 42because they don't give the same date when added to 1 Feb. But 43wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2) 44 45Finally, notice that for adding hours, minutes and so on you don't need this 46class at all: \helpref{wxTimeSpan}{wxtimespan} will do the job because there 47are no subtleties associated with those (we don't support leap seconds). 48 49\wxheading{Derived from} 50 51No 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 70Constructs the date span object for the given number of years, months, weeks 71and 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 82Returns the sum of two date spans. The first version returns a new object, the 83second 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 90Returns 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 101Returns 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 112Returns the number of days (only, that it not counting the weeks component!) 113in 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 124Returns 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 131Returns the combined number of days in this date span, counting both weeks and 132days. 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 143Returns 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 154Returns 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 161Returns 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 172Returns 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 187Returns the product of the date span by the specified {\it factor}. The 188product is computed by multiplying each of the components by the factor. 189 190The first version returns a new object, the second and third ones modify this 191object in place. 192 193% wxDateSpan::Negate 194\membersection{wxDateSpan::Negate}\label{wxdatespannegate} 195 196\constfunc{wxDateSpan}{Negate}{\void} 197 198Returns 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 211Changes 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 222Sets the number of days (without modifying any other components) in this date 223span. 224 225% wxDateSpan::SetYears 226\membersection{wxDateSpan::SetYears}\label{wxdatespansetyears} 227 228\func{wxDateSpan\&}{SetYears}{\param{int }{n}} 229 230Sets the number of years (without modifying any other components) in this date 231span. 232 233% wxDateSpan::SetMonths 234\membersection{wxDateSpan::SetMonths}\label{wxdatespansetmonths} 235 236\func{wxDateSpan\&}{SetMonths}{\param{int }{n}} 237 238Sets the number of months (without modifying any other components) in this 239date span. 240 241% wxDateSpan::SetWeeks 242\membersection{wxDateSpan::SetWeeks}\label{wxdatespansetweeks} 243 244\func{wxDateSpan\&}{SetWeeks}{\param{int }{n}} 245 246Sets the number of weeks (without modifying any other components) in this date 247span. 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 258Returns the difference of two date spans. The first version returns a new 259object, 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 266Returns 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 277Returns 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 288Returns 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 299Returns 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 310Returns {\tt true} if this date span is equal to the other one. Two date spans 311are considered equal if and only if they have the same number of years and 312months 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 319Returns {\tt true} if this date span is different from the other one. 320 321\wxheading{See also} 322 323\helpref{operator==}{wxdatespanoperatorequal} 324 325