include/ptlib/timeint.h

   1 /*
   2  * timeint.h
   3  *
   4  * Millisecond resolution time interval class (uses 64 bit integers).
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.30  2004/04/18 04:33:36  rjongbloed
  31  * Changed all operators that return BOOL to return standard type bool. This is primarily
  32  *   for improved compatibility with std STL usage removing many warnings.
  33  *
  34  * Revision 1.29  2003/09/17 05:41:59  csoutheren
  35  * Removed recursive includes
  36  *
  37  * Revision 1.28  2003/09/17 01:18:02  csoutheren
  38  * Removed recursive include file system and removed all references
  39  * to deprecated coooperative threading support
  40  *
  41  * Revision 1.27  2002/09/16 01:08:59  robertj
  42  * Added #define so can select if #pragma interface/implementation is used on
  43  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  44  *
  45  * Revision 1.26  2002/05/28 13:05:26  robertj
  46  * Fixed PTimer::SetInterval so it restarts timer as per operator=()
  47  *
  48  * Revision 1.25  2001/10/16 07:44:06  robertj
  49  * Added AsString() function to PTimeInterval.
  50  *
  51  * Revision 1.24  2001/07/10 02:55:16  robertj
  52  * Added unary minus operator
  53  *
  54  * Revision 1.23  2001/05/22 12:49:32  robertj
  55  * Did some seriously wierd rewrite of platform headers to eliminate the
  56  *   stupid GNU compiler warning about braces not matching.
  57  *
  58  * Revision 1.22  2000/10/05 23:36:26  robertj
  59  * Fixed compiler ambiguities in PTimeInterval constructor.
  60  *
  61  * Revision 1.21  2000/03/06 04:09:23  robertj
  62  * Added constructor to do PString conversion to PTimeInterval
  63  *
  64  * Revision 1.20  1999/07/06 04:46:00  robertj
  65  * Fixed being able to case an unsigned to a PTimeInterval.
  66  * Improved resolution of PTimer::Tick() to be millisecond accurate.
  67  *
  68  * Revision 1.19  1999/03/09 02:59:51  robertj
  69  * Changed comments to doc++ compatible documentation.
  70  *
  71  * Revision 1.18  1999/02/16 08:11:17  robertj
  72  * MSVC 6.0 compatibility changes.
  73  *
  74  * Revision 1.17  1998/09/23 06:21:43  robertj
  75  * Added open source copyright license.
  76  *
  77  * Revision 1.16  1998/01/26 00:49:53  robertj
  78  * Added multiply and divide operators to PTimeInterval.
  79  *
  80  * Revision 1.15  1996/05/15 10:19:29  robertj
  81  * Changed millisecond access functions to get 64 bit integer.
  82  *
  83  * Revision 1.14  1996/05/09 12:22:09  robertj
  84  * Resolved C++ problems with 64 bit PTimeInterval for Mac platform.
  85  *
  86  * Revision 1.13  1996/03/17 05:52:02  robertj
  87  * Changed PTimeInterval to 64 bit integer.
  88  *
  89  * Revision 1.12  1995/03/14 12:42:50  robertj
  90  * Updated documentation to use HTML codes.
  91  *
  92  * Revision 1.11  1995/01/18  09:01:32  robertj
  93  * Documentation.
  94  *
  95  * Revision 1.10  1995/01/09  12:29:41  robertj
  96  * Removed unnecesary return value from I/O functions.
  97  *
  98  * Revision 1.9  1994/08/23  11:32:52  robertj
  99  * Oops
 100  *
 101  * Revision 1.8  1994/08/22  00:46:48  robertj
 102  * Added pragma fro GNU C++ compiler.
 103  *
 104  * Revision 1.7  1994/07/02  03:03:49  robertj
 105  * Timer redesign consequences and ability to compare a time interval against
 106  * ordinary integer milliseconds.
 107  *
 108  * Revision 1.6  1994/06/25  11:55:15  robertj
 109  * Unix version synchronisation.
 110  *
 111  * Revision 1.5  1994/01/03  04:42:23  robertj
 112  * Mass changes to common container classes and interactors etc etc etc.
 113  *
 114  * Revision 1.4  1993/08/31  03:38:02  robertj
 115  * Added copy constructor and assignement oeprator due to G++ strangeness.
 116  *
 117  * Revision 1.3  1993/08/27  18:17:47  robertj
 118  * Added function to set the interval of a PTieInterval object.
 119  * Used a common type for number of milliseconds.
 120  *
 121  * Revision 1.2  1993/07/14  12:49:16  robertj
 122  * Fixed RCS keywords.
 123  *
 124  */
 125
 126 #ifndef _PTIMEINTERVAL
 127 #define _PTIMEINTERVAL
 128
 129 #ifdef P_USE_PRAGMA
 130 #pragma interface
 131 #endif
 132
 133
 134 ///////////////////////////////////////////////////////////////////////////////
 135 // Difference between two system times
 136
 137 /** This class defines an arbitrary time interval to millisecond accuracy. The
 138    interval can be both positive and negative.
 139
 140    A long int is used to store the time interval so it is limited to LONG_MAX
 141    (found in the standard C header file limits.h) milliseconds. This is
 142    approximately 596 hours for 32 bit integers.
 143
 144    There is a constant, #PMaxTimeInterval# which defines the
 145    maximum number of milliseconds that a time interval may be.
 146  */
 147 class PTimeInterval : public PObject
 148 {
 149   PCLASSINFO(PTimeInterval, PObject);
 150
 151   public:
 152   /**@name Construction */
 153   //@{
 154     /** Create a new time interval object. The time interval, in milliseconds,
 155        is the sum of all of the parameters. For example all of the following
 156        are equivalent:
 157 \begin{verbatim}
 158               PTimeInterval(120000)
 159               PTimeInterval(60000, 60)
 160               PTimeInterval(60000, 0, 1)
 161               PTimeInterval(0, 60, 1)
 162               PTimeInterval(0, 0, 2)
 163 \end{verbatim}
 164      */
 165     PTimeInterval(
 166       PInt64 millisecs = 0   /// Number of milliseconds for interval.
 167     );
 168     PTimeInterval(
 169       long millisecs,       /// Number of milliseconds for interval.
 170       long seconds,         /// Number of seconds for interval.
 171       long minutes = 0,     /// Number of minutes for interval.
 172       long hours = 0,       /// Number of hours for interval.
 173       int days = 0          /// Number of days for interval.
 174     );
 175     PTimeInterval(
 176       const PString & str   /// String representation of time interval.
 177     );
 178   //@}
 179
 180   /**@name Overrides from class PObject */
 181   //@{
 182     /** Create a new copy of the time interval. It is the responsibility of the
 183        called to delete the object.
 184
 185        @return
 186        new time interval on heap.
 187      */
 188     PObject * Clone() const;
 189
 190     /** Rank the two time intervals. This ranks the intervals as you would
 191        expect for two integers.
 192
 193        @return
 194        #EqualTo#, #LessThan# or #GreaterThan#
 195        depending on their relative rank.
 196      */
 197     virtual Comparison Compare(
 198       const PObject & obj   /// Time interval to compare against.
 199     ) const;
 200
 201     /** Output the time interval to the I/O stream. This outputs the number of
 202        milliseconds as a signed decimal integer number.
 203      */
 204     virtual void PrintOn(
 205       ostream & strm    /// I/O stream to output the time interval.
 206     ) const;
 207
 208     /** Input the time interval from the I/O stream. This expects the input
 209        to be a signed decimal integer number.
 210      */
 211     virtual void ReadFrom(
 212       istream & strm    /// I/O stream to input the time interval from.
 213     );
 214   //@}
 215
 216   /**@name Conversion functions */
 217   //@{
 218     enum Formats {
 219       NormalFormat,
 220       IncludeDays,
 221       SecondsOnly
 222     };
 223
 224     PString AsString(
 225       int decimals = 3,
 226       Formats format = NormalFormat,
 227       int width = 1
 228     ) const;
 229   //@}
 230
 231   /**@name Access functions */
 232   //@{
 233     /** Get the number of milliseconds for the time interval.
 234
 235        @return
 236        very long integer number of milliseconds.
 237      */
 238     PInt64 GetMilliSeconds() const;
 239
 240     /** Get the number of whole seconds for the time interval.
 241
 242        @return
 243        long integer number of seconds.
 244      */
 245     long GetSeconds() const;
 246
 247     /** Get the number of whole minutes for the time interval.
 248
 249        @return
 250        integer number of minutes.
 251      */
 252     long GetMinutes() const;
 253
 254     /** Get the number of whole hours for the time interval.
 255
 256        @return
 257        integer number of hours.
 258      */
 259     int GetHours() const;
 260
 261     /** Get the number of whole days for the time interval.
 262
 263        @return
 264        integer number of days.
 265      */
 266     int GetDays() const;
 267
 268     /** Get the number of milliseconds for the time interval.
 269
 270        @return
 271        long integer number of milliseconds.
 272      */
 273     DWORD GetInterval() const;
 274
 275     /** Set the value of the time interval. The time interval, in milliseconds,
 276        is the sum of all of the parameters. For example all of the following
 277        are equivalent:
 278 \begin{verbatim}
 279               SetInterval(120000)
 280               SetInterval(60000, 60)
 281               SetInterval(60000, 0, 1)
 282               SetInterval(0, 60, 1)
 283               SetInterval(0, 0, 2)
 284 \end{verbatim}
 285      */
 286     virtual void SetInterval(
 287       PInt64 milliseconds = 0,  /// Number of milliseconds for interval.
 288       long seconds = 0,         /// Number of seconds for interval.
 289       long minutes = 0,         /// Number of minutes for interval.
 290       long hours = 0,           /// Number of hours for interval.
 291       int days = 0              /// Number of days for interval.
 292     );
 293   //@}
 294
 295   /**@name Operations */
 296   //@{
 297     /** Unary minus, get negative of time interval.
 298
 299        @return
 300        difference of the time intervals.
 301      */
 302     PTimeInterval operator-() const;
 303
 304     /** Add the two time intervals yielding a third time interval.
 305
 306        @return
 307        sum of the time intervals.
 308      */
 309     PTimeInterval operator+(
 310       const PTimeInterval & interval   /// Time interval to add.
 311     ) const;
 312
 313     /** Add the second time interval to the first time interval.
 314
 315        @return
 316        reference to first time interval.
 317      */
 318     PTimeInterval & operator+=(
 319       const PTimeInterval & interval   /// Time interval to add.
 320     );
 321
 322     /** Subtract the two time intervals yielding a third time interval.
 323
 324        @return
 325        difference of the time intervals.
 326      */
 327     PTimeInterval operator-(
 328       const PTimeInterval & interval   /// Time interval to subtract.
 329     ) const;
 330
 331     /** Subtract the second time interval from the first time interval.
 332
 333        @return
 334        reference to first time interval.
 335      */
 336     PTimeInterval & operator-=(
 337       const PTimeInterval & interval   /// Time interval to subtract.
 338     );
 339
 340     /** Multiply the time interval by a factor yielding a third time interval.
 341
 342        @return
 343        the time intervals times the factor.
 344      */
 345     PTimeInterval operator*(
 346       int factor   /// factor to multiply.
 347     ) const;
 348
 349     /** Multiply the time interval by a factor.
 350
 351        @return
 352        reference to time interval.
 353      */
 354     PTimeInterval & operator*=(
 355       int factor   /// factor to multiply.
 356     );
 357
 358     /** Divide the time interval by a factor yielding a third time interval.
 359
 360        @return
 361        the time intervals divided by the factor.
 362      */
 363     PTimeInterval operator/(
 364       int factor   /// factor to divide.
 365     ) const;
 366
 367     /** Divide the time interval by a factor.
 368
 369        @return
 370        reference to time interval.
 371      */
 372     PTimeInterval & operator/=(
 373       int factor   /// factor to divide.
 374     );
 375   //@}
 376
 377   /**@name Comparison functions */
 378   //@{
 379     /** Compare to the two time intervals. This is provided as an override to
 380        the default in PObject so that comparisons can be made to integer
 381        literals that represent milliseconds.
 382
 383        @return
 384        TRUE if intervals are equal.
 385      */
 386     bool operator==(
 387       const PTimeInterval & interval   /// Time interval to compare.
 388     ) const;
 389     bool operator==(
 390       long msecs    /// Time interval as integer milliseconds to compare.
 391     ) const;
 392
 393     /** Compare to the two time intervals. This is provided as an override to
 394        the default in PObject so that comparisons can be made to integer
 395        literals that represent milliseconds.
 396
 397        @return
 398        TRUE if intervals are not equal.
 399      */
 400     bool operator!=(
 401       const PTimeInterval & interval   /// Time interval to compare.
 402     ) const;
 403     bool operator!=(
 404       long msecs    /// Time interval as integer milliseconds to compare.
 405     ) const;
 406
 407     /** Compare to the two time intervals. This is provided as an override to
 408        the default in PObject so that comparisons can be made to integer
 409        literals that represent milliseconds.
 410
 411        @return
 412        TRUE if intervals are greater than.
 413      */
 414     bool operator> (
 415       const PTimeInterval & interval   /// Time interval to compare.
 416     ) const;
 417     bool operator> (
 418       long msecs    /// Time interval as integer milliseconds to compare.
 419     ) const;
 420
 421     /** Compare to the two time intervals. This is provided as an override to
 422        the default in PObject so that comparisons can be made to integer
 423        literals that represent milliseconds.
 424
 425        @return
 426        TRUE if intervals are greater than or equal.
 427      */
 428     bool operator>=(
 429       const PTimeInterval & interval   /// Time interval to compare.
 430     ) const;
 431     bool operator>=(
 432       long msecs    /// Time interval as integer milliseconds to compare.
 433     ) const;
 434
 435     /** Compare to the two time intervals. This is provided as an override to
 436        the default in PObject so that comparisons can be made to integer
 437        literals that represent milliseconds.
 438
 439        @return
 440        TRUE if intervals are less than.
 441      */
 442     bool operator< (
 443       const PTimeInterval & interval   /// Time interval to compare.
 444     ) const;
 445     bool operator< (
 446       long msecs    /// Time interval as integer milliseconds to compare.
 447     ) const;
 448
 449     /** Compare to the two time intervals. This is provided as an override to
 450        the default in PObject so that comparisons can be made to integer
 451        literals that represent milliseconds.
 452
 453        @return
 454        TRUE if intervals are less than or equal.
 455      */
 456     bool operator<=(
 457       const PTimeInterval & interval   /// Time interval to compare.
 458     ) const;
 459     bool operator<=(
 460       long msecs    /// Time interval as integer milliseconds to compare.
 461     ) const;
 462   //@}
 463
 464   protected:
 465   // Member variables
 466     /// Number of milliseconds in time interval.
 467     PInt64 milliseconds;
 468
 469
 470 // Include platform dependent part of class
 471 #ifdef _WIN32
 472 #include "msos/ptlib/timeint.h"
 473 #else
 474 #include "unix/ptlib/timeint.h"
 475 #endif
 476 };
 477
 478 #endif
 479
 480
 481 // End Of File ///////////////////////////////////////////////////////////////