MIRA
Time

Contents

Time and Duration in general

For a general reference, the documentation http://www.boost.org/doc/libs/1_44_0/doc/html/date_time/posix_time.html can be used, since boost::posix_time::ptime and boost::posix_time::time_duration are the underlying classes of Time and Duration. However, there are some minor differences and additions to the ptime class.

Time

The time class is used to represent a certain point in time. There are multiple ways of creating Time objects.

Time t1(Date(1,1,2010)); // creates January 1th 2010 00:00:00.0
Time t2(Date(1,Oct,2000),Duration::hours(10)); // creates October 1th 2000 10:00:00.0
Time t3(Date(10,Sep,2000),Duration(8,30,0)); // creates September 10th 2000 08:30:00.0

To obtain the current system time, call Time::now().

Time t = Time::now();

For conversion of Time from and to unix timestamp, use toUnixTimestamp() and fromUnixTimestamp(). Please note that the returned timestamp of toUnixTimestamp() is in seconds. Therefore, fromUnixTimestamp() also requires a timestamp with second resolution.

uint32 timestamp = Time::now().toUnixTimestamp();
Time t = Time::fromUnixTimestamp(timestamp);

To use the full resolution one can turn a Time object into nanoseconds since 00:00:00-1970/01/01.

uint64 ns = Time::now().toUnixNS();
Time t = Time::fromUnixNS(ns);

You can also create an invalid time or a representation for eternity, if necessary.

Time t = Time::invalid();
if (!t.isValid())
return;
Time t = Time::eternity(); // will produce 9999/12/31 23:59:59.999999

Duration

Time durations can be used to describe a length of time. The Duration class provides several ways for easy Duration object creation ranging from hours to nanoseconds.

Duration oneHour = Duration::hours(1);
Duration fiveMinutes = Duration::minutes(5);
Duration twoSeconds = Duration::seconds(2);
Duration hundredMilliseconds = Duration::milliseconds(100);
Duration tenMicroseconds = Duration::microseconds(10);
Duration oneNanosecond = Duration::nanoseconds(1);

Like Time, Durations can also be invalid.

Duration d = Duration::invalid();
if (!d.isValid())
return;

Calculating with Time

There are multiple ways of combining Time and Duration objects in equations.

Time tomorrow = Time::now() + Duration::hours(24);
Time sent, received;
Duration delay = received - sent;
...

Converting time zones

Time objects can be converted to other time zones. By default, a time object represents a timestamp in UTC time.

To convert the time to timestamps in other time zones, the following methods can be used:

Time t = Time::now();
t.toLocal(); // converts to the current local time zone of the system
t.toTimeZone("CET+1"); // converts to central european time + 1h