Time

Contents

• Time and Duration in general
• Time
• Duration
• Calculating with Time
• API

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.

• All time classes can be serialized via the reflect mechanism. For BinarySerializer nanosecond format is used as representation. For XML- and JSONSerializer millisecond format is used as representation.
• By default, a Time object represents a timestamp in UTC time.
• Time has nanosecond resolution and can be converted to nanoseconds since 00:00:00-1970/01/01
• Duration has nanosecond resolution

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