docs/latex/wx/timespan.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:     wxWidgets license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxTimeSpan}}\label{wxtimespan}
  13
  14 wxTimeSpan class represents a time interval.
  15
  16 \wxheading{Derived from}
  17
  18 No base class
  19
  20 \wxheading{Include files}
  21
  22 <wx/datetime.h>
  23
  24 \wxheading{See also}
  25
  26 \helpref{Date classes overview}{wxdatetimeoverview},\rtfsp
  27 \helpref{wxDateTime}{wxdatetime}
  28
  29 \latexignore{\rtfignore{\wxheading{Function groups}}}
  30
  31 \membersection{Static functions}
  32
  33 \helpref{Seconds}{wxtimespanseconds}\\
  34 \helpref{Second}{wxtimespansecond}\\
  35 \helpref{Minutes}{wxtimespanminutes}\\
  36 \helpref{Minute}{wxtimespanminute}\\
  37 \helpref{Hours}{wxtimespanhours}\\
  38 \helpref{Hour}{wxtimespanhour}\\
  39 \helpref{Days}{wxtimespandays}\\
  40 \helpref{Day}{wxtimespanday}\\
  41 \helpref{Weeks}{wxtimespanweeks}\\
  42 \helpref{Week}{wxtimespanweek}
  43
  44 \membersection{Constructors}
  45
  46 \helpref{wxTimeSpan}{wxtimespanctor}
  47
  48 \membersection{Accessors}
  49
  50 \helpref{GetSeconds}{wxtimespangetseconds}\\
  51 \helpref{GetMinutes}{wxtimespangetminutes}\\
  52 \helpref{GetHours}{wxtimespangethours}\\
  53 \helpref{GetDays}{wxtimespangetdays}\\
  54 \helpref{GetWeeks}{wxtimespangetweeks}\\
  55 \helpref{GetValue}{wxtimespangetvalue}
  56
  57 \membersection{Operations}
  58
  59 \helpref{Add}{wxtimespanadd}\\
  60 \helpref{Substract}{wxtimespansubstract}\\
  61 \helpref{Multiply}{wxtimespanmultiply}\\
  62 \helpref{Negate}{wxtimespannegate}\\
  63 \helpref{Neg}{wxtimespanneg}\\
  64 \helpref{Abs}{wxtimespanabs}
  65
  66 \membersection{Tests}
  67
  68 \helpref{IsNull}{wxtimespanisnull}\\
  69 \helpref{IsPositive}{wxtimespanispositive}\\
  70 \helpref{IsNegative}{wxtimespanisnegative}\\
  71 \helpref{IsEqualTo}{wxtimespanisequalto}\\
  72 \helpref{IsLongerThan}{wxtimespanislongerthan}\\
  73 \helpref{IsShorterThan}{wxtimespanisshorterthan}
  74
  75 \membersection{Formatting time spans}
  76
  77 \helpref{Format}{wxtimespanformat}
  78
  79 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  80 % Start of member function part                                               %
  81 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  82
  83 \helponly{\insertatlevel{2}{
  84     \wxheading{Members}
  85 }}
  86
  87 \membersection{wxTimeSpan::Abs}\label{wxtimespanabs}
  88
  89 \constfunc{wxTimeSpan}{Abs}{\void}
  90
  91 Returns the absolute value of the timespan: does not modify the
  92 object.
  93
  94 \membersection{wxTimeSpan::Add}\label{wxtimespanadd}
  95
  96 \constfunc{wxTimeSpan}{Add}{\param{const wxTimeSpan\& }{diff}}
  97
  98 \func{wxTimeSpan\&}{Add}{\param{const wxTimeSpan\& }{diff}}
  99
 100 \func{wxTimeSpan\&}{operator$+=$}{\param{const wxTimeSpan\&}{diff}}
 101
 102 Returns the sum of two timespans.
 103
 104 \membersection{wxTimeSpan::Days}\label{wxtimespandays}
 105
 106 \func{static wxTimespan}{Days}{\param{long }{days}}
 107
 108 Returns the timespan for the given number of days.
 109
 110 \membersection{wxTimeSpan::Day}\label{wxtimespanday}
 111
 112 \func{static wxTimespan}{Day}{\void}
 113
 114 Returns the timespan for one day.
 115
 116 \membersection{wxTimeSpan::Format}\label{wxtimespanformat}
 117
 118 \func{wxString}{Format}{\param{const wxChar * }{format = "\%H:\%M:\%S"}}
 119
 120 Returns the string containing the formatted representation of the time span.
 121 The following format specifiers are allowed after \%:
 122
 123 \twocolwidtha{5cm}%
 124 \begin{twocollist}\itemsep=0pt
 125 \twocolitem{H}{number of {\bf H}ours}
 126 \twocolitem{M}{number of {\bf M}inutes}
 127 \twocolitem{S}{number of {\bf S}econds}
 128 \twocolitem{l}{number of mi{\bf l}liseconds}
 129 \twocolitem{D}{number of {\bf D}ays}
 130 \twocolitem{E}{number of w{\bf E}eks}
 131 \twocolitem{\%}{the percent character}
 132 \end{twocollist}
 133
 134 Note that, for example, the number of hours in the description above is not
 135 well defined: it can be either the total number of hours (for example, for a
 136 time span of $50$ hours this would be $50$) or just the hour part of the time
 137 span, which would be $2$ in this case as $50$ hours is equal to $2$ days and
 138 $2$ hours.
 139
 140 wxTimeSpan resolves this ambiguity in the following way: if there had been,
 141 indeed, the {\tt \%D} format specified preceding the {\tt \%H}, then it is
 142 interpreted as $2$. Otherwise, it is $50$.
 143
 144 The same applies to all other format specifiers: if they follow a specifier of
 145 larger unit, only the rest part is taken, otherwise the full value is used.
 146
 147 \membersection{wxTimeSpan::GetDays}\label{wxtimespangetdays}
 148
 149 \constfunc{int}{GetDays}{\void}
 150
 151 Returns the difference in number of days.
 152
 153 \membersection{wxTimeSpan::GetHours}\label{wxtimespangethours}
 154
 155 \constfunc{int}{GetHours}{\void}
 156
 157 Returns the difference in number of hours.
 158
 159 \membersection{wxTimeSpan::GetMilliseconds}\label{wxtimespangetmilliseconds}
 160
 161 \constfunc{wxLongLong}{GetMilliseconds}{\void}
 162
 163 Returns the difference in number of milliseconds.
 164
 165 \membersection{wxTimeSpan::GetMinutes}\label{wxtimespangetminutes}
 166
 167 \constfunc{int}{GetMinutes}{\void}
 168
 169 Returns the difference in number of minutes.
 170
 171 \membersection{wxTimeSpan::GetSeconds}\label{wxtimespangetseconds}
 172
 173 \constfunc{wxLongLong}{GetSeconds}{\void}
 174
 175 Returns the difference in number of seconds.
 176
 177 \membersection{wxTimeSpan::GetValue}\label{wxtimespangetvalue}
 178
 179 \constfunc{wxLongLong}{GetValue}{\void}
 180
 181 Returns the internal representation of timespan.
 182
 183 \membersection{wxTimeSpan::GetWeeks}\label{wxtimespangetweeks}
 184
 185 \constfunc{int}{GetWeeks}{\void}
 186
 187 Returns the difference in number of weeks.
 188
 189 \membersection{wxTimeSpan::Hours}\label{wxtimespanhours}
 190
 191 \func{static wxTimespan}{Hours}{\param{long }{hours}}
 192
 193 Returns the timespan for the given number of hours.
 194
 195 \membersection{wxTimeSpan::Hour}\label{wxtimespanhour}
 196
 197 \func{static wxTimespan}{Hour}{\void}
 198
 199 Returns the timespan for one hour.
 200
 201 \membersection{wxTimeSpan::IsEqualTo}\label{wxtimespanisequalto}
 202
 203 \constfunc{bool}{IsEqualTo}{\param{const wxTimeSpan\& }{ts}}
 204
 205 Returns {\tt true} if two timespans are equal.
 206
 207 \membersection{wxTimeSpan::IsLongerThan}\label{wxtimespanislongerthan}
 208
 209 \constfunc{bool}{IsLongerThan}{\param{const wxTimeSpan\& }{ts}}
 210
 211 Compares two timespans: works with the absolute values, i.e. -2
 212 hours is longer than 1 hour. Also, it will return {\tt false} if
 213 the timespans are equal in absolute value.
 214
 215 \membersection{wxTimeSpan::IsNegative}\label{wxtimespanisnegative}
 216
 217 \constfunc{bool}{IsNegative}{\void}
 218
 219 Returns {\tt true} if the timespan is negative.
 220
 221 \membersection{wxTimeSpan::IsNull}\label{wxtimespanisnull}
 222
 223 \constfunc{bool}{IsNull}{\void}
 224
 225 Returns {\tt true} if the timespan is empty.
 226
 227 \membersection{wxTimeSpan::IsPositive}\label{wxtimespanispositive}
 228
 229 \constfunc{bool}{IsPositive}{\void}
 230
 231 Returns {\tt true} if the timespan is positive.
 232
 233 \membersection{wxTimeSpan::IsShorterThan}\label{wxtimespanisshorterthan}
 234
 235 \constfunc{bool}{IsShorterThan}{\param{const wxTimeSpan\& }{ts}}
 236
 237 Compares two timespans: works with the absolute values, i.e. 1
 238 hour is shorter than -2 hours. Also, it will return {\tt false} if
 239 the timespans are equal in absolute value.
 240
 241 \membersection{wxTimeSpan::Minutes}\label{wxtimespanminutes}
 242
 243 \func{static wxTimespan}{Minutes}{\param{long }{min}}
 244
 245 Returns the timespan for the given number of minutes.
 246
 247 \membersection{wxTimeSpan::Minute}\label{wxtimespanminute}
 248
 249 \func{static wxTimespan}{Minute}{\void}
 250
 251 Returns the timespan for one minute.
 252
 253 \membersection{wxTimeSpan::Multiply}\label{wxtimespanmultiply}
 254
 255 \constfunc{wxTimeSpan}{Multiply}{\param{int }{n}}
 256
 257 \func{wxTimeSpan\&}{Multiply}{\param{int }{n}}
 258
 259 \func{wxTimeSpan\&}{operator$*=$}{\param{int }{n}}
 260
 261 Multiplies timespan by a scalar.
 262
 263 \membersection{wxTimeSpan::Negate}\label{wxtimespannegate}
 264
 265 \constfunc{wxTimeSpan}{Negate}{\void}
 266
 267 Returns timespan with inversed sign.
 268
 269 \membersection{wxTimeSpan::Neg}\label{wxtimespanneg}
 270
 271 \func{wxTimeSpan\&}{Neg}{\void}
 272
 273 \func{wxTimeSpan\&}{operator$-$}{\void}
 274
 275 Negate the value of the timespan.
 276
 277 \membersection{wxTimeSpan::Seconds}\label{wxtimespanseconds}
 278
 279 \func{static wxTimespan}{Seconds}{\param{long }{sec}}
 280
 281 Returns the timespan for the given number of seconds.
 282
 283 \membersection{wxTimeSpan::Second}\label{wxtimespansecond}
 284
 285 \func{static wxTimespan}{Second}{\void}
 286
 287 Returns the timespan for one second.
 288
 289 \membersection{wxTimeSpan::Substract}\label{wxtimespansubstract}
 290
 291 \constfunc{wxTimeSpan}{Substract}{\param{const wxTimeSpan\&}{diff}}
 292
 293 \func{wxTimeSpan\&}{Substract}{\param{const wxTimeSpan\& }{diff}}
 294
 295 \func{wxTimeSpan\&}{operator$-=$}{\param{const wxTimeSpan\&}{diff}}
 296
 297 Returns the difference of two timespans.
 298
 299 \membersection{wxTimeSpan::Weeks}\label{wxtimespanweeks}
 300
 301 \func{static wxTimespan}{Weeks}{\param{long }{weeks}}
 302
 303 Returns the timespan for the given number of weeks.
 304
 305 \membersection{wxTimeSpan::Week}\label{wxtimespanweek}
 306
 307 \func{static wxTimespan}{Week}{\void}
 308
 309 Returns the timespan for one week.
 310
 311 \membersection{wxTimeSpan::wxTimeSpan}\label{wxtimespanctor}
 312
 313 \func{}{wxTimeSpan}{\void}
 314
 315 Default constructor, constructs a zero timespan.
 316
 317 \func{}{wxTimeSpan}{\param{long }{hours}, \param{long }{min}, \param{long }{sec}, \param{long }{msec}}
 318
 319 Constructs timespan from separate values for each component, with the date
 320 set to 0. Hours are not restricted to 0..24 range, neither are
 321 minutes, seconds or milliseconds.
 322