wow. that was easy: git mv core nucleus

[feisty_meow.git] / nucleus / library / timely / time_stamp.h

diff --git a/nucleus/library/timely/time_stamp.h b/nucleus/library/timely/time_stamp.h
new file mode 100644 (file)
index 0000000..691660d
--- /dev/null
+++ b/nucleus/library/timely/time_stamp.h
@@ -0,0 +1,113 @@
+#ifndef TIME_STAMP_CLASS
+#define TIME_STAMP_CLASS
+
+/*****************************************************************************\
+*                                                                             *
+*  Name   : time_stamp                                                        *
+*  Author : Chris Koeritz                                                     *
+*                                                                             *
+*******************************************************************************
+* Copyright (c) 1995-$now By Author.  This program is free software; you can  *
+* redistribute it and/or modify it under the terms of the GNU General Public  *
+* License as published by the Free Software Foundation; either version 2 of   *
+* the License or (at your option) any later version.  This is online at:      *
+*     http://www.fsf.org/copyleft/gpl.html                                    *
+* Please send any updates to: fred@gruntose.com                               *
+\*****************************************************************************/
+
+#include <basis/astring.h>
+#include <basis/contracts.h>
+#include <basis/definitions.h>
+
+// forward.
+class rollover_record;
+struct timeval;
+
+namespace timely {
+
+//! Represents a point in time relative to the operating system startup time.
+/*!
+  This duration is measured in milliseconds.  This class provides a handy way
+  of measuring relative durations at the millisecond time scale.
+  Unfortunately, operating systems that reckon their millisecond uptime in
+  32 bit integers will suffer from a rollover problem every 49 days or so,
+  but this class corrects this issue.
+*/
+
+class time_stamp : public virtual basis::orderable
+{
+public:
+  typedef double time_representation;
+    //!< the representation of time for this universe, measured in milliseconds.
+
+  time_stamp();
+    //!< creates a time_stamp containing the current time.
+
+  time_stamp(time_representation offset);
+    //!< creates a stamp after the current time by "offset" milliseconds.
+    /*!< negative offsets are allowed, in which case the stamp will be
+    prior to the current time. */
+
+  static double rolling_uptime();
+    //!< give the OS uptime in a more durable form that handles rollovers.
+
+  void reset();
+    //!< sets the stamp time back to now.
+  void reset(time_representation offset);
+    //!< sets the stamp forward by "offset" similar to the second constructor.
+
+  time_representation value() const { return c_stamp; }
+    //!< returns the time_stamp in terms of the lower level type.
+
+  enum stamp_display_style { STAMP_RELATIVE, STAMP_ABSOLUTE };
+
+  basis::astring text_form(stamp_display_style style = STAMP_RELATIVE) const;
+    //!< returns a simple textual representation of the time_stamp.
+    /*!< if the "style" is ABSOLUTE, then the stamp is shown in H:M:S.ms
+    form based on the system uptime.  if the "style" is RELATIVE, then the
+    stamp is shown as an offset from now. */
+
+  static basis::astring notarize(bool add_space = true);
+    //!< a useful method for getting a textual version of the time "right now".
+    /*!< this was formerly known as a very useful method called 'utility::timestamp'.
+    that naming was fairly abusive to keep straight from the time_stamp class, so the
+    functionality has been absorbed. */
+
+  // standard operators: keep in mind that time is represented by an ever
+  // increasing number.  so, if a value A is less than a value B, that means
+  // that A is older than B, since it occurred at an earlier time.
+  virtual bool less_than(const basis::orderable &that) const {
+    const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
+    if (!cast) return false;
+    return c_stamp < cast->c_stamp;
+  }
+
+  virtual bool equal_to(const basis::equalizable &that) const {
+    const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
+    if (!cast) return false;
+    return c_stamp == cast->c_stamp;
+  }
+
+  // helper functions for using the OS's time support.
+
+  static timeval fill_timeval_ms(int milliseconds);
+    //!< returns a timeval system object that represents the "milliseconds".
+    /*!< if "milliseconds" is zero, then the returned timeval will
+    represent zero time passing (rather than infinite duration as some
+    functions assume). */
+
+private:
+  time_representation c_stamp;  //!< the low-level time stamp is held here.
+
+  void fill_in_time();  //!< stuffs the current time into the held value.
+
+  static time_representation get_time_now();
+    //!< platform specific function that gets uptime.
+
+  static rollover_record &rollover_rover();
+};
+
+} //namespace.
+
+#endif
+