Timestamp Module

Module Contents

typedef boost::posix_time::ptime tracktable::Timestamp

Use Boost timestamps in Tracktable.

Date/time math is such a pain to get right. We will be much happier and will spend much more time on trajectories if we delegate this to someone else who is more passionate about dates and times than moving objects.

This may be a part of our API where the underlying implementation shows through you may need to use Boost constructs if you want to do time arithmetic on hours, minutes and seconds. There is room for improvement here.

typedef boost::posix_time::time_duration tracktable::Duration
typedef boost::gregorian::date tracktable::Date

Use Boost Gregorian dates in Tracktable.

As above, but worse. The notion of dividing a day into 24 equal parts has been around for at least a couple thousand years. Indexing those days, though… Gregorian? Julian? Babylonian? Mayan? Hebrew? Which calendar system do you use?

We throw up our hands in existential dismay and adopt the Gregorian calendar as the least terrible option.

const Date tracktable::jan_1_1900(1900, boost::date_time::Jan, 1)

Beginning of time.

We’re going to use this as our standard “before any reasonable

timestamp” value. This is because we can’t actually use time t = 0.

const Timestamp tracktable::BeginningOfTime(jan_1_1900)
TRACKTABLE_CORE_EXPORT Timestamp tracktable::time_from_string(std::string const & tstring)

Construct a timestamp from a std::string.

This function will convert a string such as “2014-03-05 13:44:06” into a Timestamp that represents March 5, 2014 at 13:44:06.

The date/time format for this particular function is fixed. If you need more flexible parsing, please use the Boost date/time IO routines:

http://www.boost.org/doc/libs/1_55_0/doc/html/date_time/date_time_io.html

We will provide a friendlier way to do this in an upcoming version.

Return

Timestamp derived from string

Parameters

  • [in] tstring: String containing formatted time

TRACKTABLE_CORE_EXPORT string_type tracktable::time_to_string(Timestamp const & ts)
TRACKTABLE_CORE_EXPORT Timestamp tracktable::no_such_timestamp()

Return a timestamp containing boost::posix_time::not_a_date_time.

We may need to create an invalid timestamp to signal “not yet

initialized”. This function does that. Note

I think this will fail to translate into a Python datetime. Need to test this.

TRACKTABLE_CORE_EXPORT bool tracktable::is_timestamp_valid(Timestamp const & ts)

Check to see whether a timestamp is valid.

Boost’s date/time library can return timestamps that do not represent any real date. This function tells you whether you’ve got a “real” timestamp or one of those special values.

TRACKTABLE_CORE_EXPORT Timestamp tracktable::truncate_fractional_seconds(Timestamp const & input)

Truncate a timestamp downward to the nearest second.

We have sub-second precision on these timestamps all the way down to nanoseconds if we really want but there are often cases when we only care about precision to a single second. This gives us a clean way to get there.

TRACKTABLE_CORE_EXPORT Timestamp tracktable::round_to_nearest_second(Timestamp const & input)

Round a timestamp to the nearest second.

A time with a fractional component of at least 500 milliseconds will be rounded up to the next whole second. A time with a fractional component of fewer than 500 milliseconds will be rounded down to the previous whole second.

TRACKTABLE_CORE_EXPORT Duration tracktable::hours(int num_hours)

Create a duration measured in hours.

This is a convenience method to create a Duration that is an integral number of hours.

TRACKTABLE_CORE_EXPORT Duration tracktable::minutes(int num_hours)

Create a duration measured in minutes.

This is a convenience method to create a Duration that is an integral number of minutes.

TRACKTABLE_CORE_EXPORT Duration tracktable::seconds(int num_hours)

Create a duration measured in seconds.

This is a convenience method to create a Duration that is an integral number of seconds.

TRACKTABLE_CORE_EXPORT Duration tracktable::milliseconds(int64_t num_hours)

Create a duration measured in milliseconds.

This is a convenience method to create a Duration that is an integral number of milliseconds.

TRACKTABLE_CORE_EXPORT Duration tracktable::microseconds(int64_t num_hours)

Create a duration measured in microseconds.

This is a convenience method to create a Duration that is an integral number of seconds.

TRACKTABLE_CORE_EXPORT Duration tracktable::days(int num_days)

Create a duration measured in days.

This is a convenience method to create a Duration that is an integral number of seconds.

template<typename stream_type>
void tracktable::imbue_stream_with_timestamp_output_format(stream_type &stream, std::string const &format)

Change the string format for timestamp parsing.

This function will change the format used to parse timestamps. The effect is process-wide.

There are many flags available for use in the format. The following web page documents them all:

http://www.boost.org/doc/libs/1_55_0/doc/html/date_time/date_time_io.html

The default value is “%Y-%m-%d %H:%M:%S”, corresponding to timestamps such as “2014-04-05 12:33:40”.

TRACKTABLE_CORE_EXPORT void tracktable::set_default_timestamp_output_format(string_type const & format)

Set the default format for timestamp output.

This format will be used when printing timestamps in (for example) trajectory points.

Parameters

  • [in] format: Format string to use

TRACKTABLE_CORE_EXPORT string_type tracktable::default_timestamp_output_format()

Get the default format for timestamp output.

This format will be used when printing timestamps in (for example) trajectory points.

Return

Format string currently set as default

TRACKTABLE_CORE_EXPORT void tracktable::set_default_timestamp_input_format(string_type const & format)

Set the default format for timestamp input.

This format will be used when printing timestamps in (for example) trajectory points unless otherwise overridden.

Parameters

  • [in] format: Format string to use

TRACKTABLE_CORE_EXPORT string_type tracktable::default_timestamp_input_format()

Get the default format for timestamp input.

This format will be used when parsing timestamps.

Return

Format string currently set as default