1 #ifndef TIME_STAMP_CLASS
2 #define TIME_STAMP_CLASS
4 /*****************************************************************************\
7 * Author : Chris Koeritz *
9 *******************************************************************************
10 * Copyright (c) 1995-$now By Author. This program is free software; you can *
11 * redistribute it and/or modify it under the terms of the GNU General Public *
12 * License as published by the Free Software Foundation; either version 2 of *
13 * the License or (at your option) any later version. This is online at: *
14 * http://www.fsf.org/copyleft/gpl.html *
15 * Please send any updates to: fred@gruntose.com *
16 \*****************************************************************************/
18 #include <basis/astring.h>
19 #include <basis/contracts.h>
20 #include <basis/definitions.h>
23 class rollover_record;
28 //! Represents a point in time relative to the operating system startup time.
30 This duration is measured in milliseconds. This class provides a handy way
31 of measuring relative durations at the millisecond time scale.
32 Unfortunately, operating systems that reckon their millisecond uptime in
33 32 bit integers will suffer from a rollover problem every 49 days or so,
34 but this class corrects this issue.
37 class time_stamp : public virtual basis::orderable
40 DEFINE_CLASS_NAME("time_stamp");
42 typedef double time_representation;
43 //!< the representation of time for this universe, measured in milliseconds.
46 //!< creates a time_stamp containing the current time.
48 time_stamp(time_representation offset);
49 //!< creates a stamp after the current time by "offset" milliseconds.
50 /*!< negative offsets are allowed, in which case the stamp will be
51 prior to the current time. */
53 static double rolling_uptime();
54 //!< give the OS uptime in a more durable form that handles rollovers.
57 //!< sets the stamp time back to now.
58 void reset(time_representation offset);
59 //!< sets the stamp forward by "offset" similar to the second constructor.
61 time_representation value() const { return c_stamp; }
62 //!< returns the time_stamp in terms of the lower level type.
64 enum stamp_display_style { STAMP_RELATIVE, STAMP_ABSOLUTE };
66 basis::astring text_form(stamp_display_style style = STAMP_RELATIVE) const;
67 //!< returns a simple textual representation of the time_stamp.
68 /*!< if the "style" is ABSOLUTE, then the stamp is shown in H:M:S.ms
69 form based on the system uptime. if the "style" is RELATIVE, then the
70 stamp is shown as an offset from now. */
72 static basis::astring notarize(bool add_space = true);
73 //!< a useful method for getting a textual version of the time "right now".
74 /*!< this was formerly known as a very useful method called 'utility::timestamp'.
75 that naming was fairly abusive to keep straight from the time_stamp class, so the
76 functionality has been absorbed. */
78 // standard operators: keep in mind that time is represented by an ever
79 // increasing number. so, if a value A is less than a value B, that means
80 // that A is older than B, since it occurred at an earlier time.
81 virtual bool less_than(const basis::orderable &that) const {
82 const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
83 if (!cast) return false;
84 return c_stamp < cast->c_stamp;
87 virtual bool equal_to(const basis::equalizable &that) const {
88 const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
89 if (!cast) return false;
90 return c_stamp == cast->c_stamp;
93 // helper functions for using the OS's time support.
95 static void fill_timeval_ms(timeval &time_point, int milliseconds);
96 //!< returns a timeval system object that represents the "milliseconds".
97 /*!< if "milliseconds" is zero, then the returned timeval will
98 represent zero time passing (rather than infinite duration as some
102 time_representation c_stamp; //!< the low-level time stamp is held here.
104 void fill_in_time(); //!< stuffs the current time into the held value.
106 static time_representation get_time_now();
107 //!< platform specific function that gets uptime.
109 static rollover_record &rollover_rover();