OpenMAMA C++ API
Wombat::MamaDateTime Class Reference

A date/time representation with additional hints for precision, advanced output formatting and support for time zone conversion (using the MamaTimeZone type). More...

#include <MamaDateTime.h>

Public Member Functions

 MamaDateTime ()
 
 MamaDateTime (const MamaDateTime &copy)
 
 MamaDateTime (const char *str, const MamaTimeZone *tz=NULL)
 Constructor taking a string argument. More...
 
 ~MamaDateTime ()
 
MamaDateTimeoperator= (const MamaDateTime &rhs)
 
bool operator== (const MamaDateTime &rhs) const
 
bool operator!= (const MamaDateTime &rhs) const
 
bool operator< (const MamaDateTime &rhs) const
 
bool operator> (const MamaDateTime &rhs) const
 
int compare (const MamaDateTime &rhs) const
 
bool empty () const
 
void setEpochTime (mama_u32_t secondsSinceEpoch, mama_u32_t microseconds, mamaDateTimePrecision precision=MAMA_DATE_TIME_PREC_UNKNOWN)
 
void setEpochTimeF64 (double secondsSinceEpoch)
 
void setEpochTimeMilliseconds (mama_u64_t millisecondsSinceEpoch)
 
void setEpochTimeMicroseconds (mama_u64_t microsecondsSinceEpoch)
 
void setWithHints (mama_u32_t secondsSinceEpoch, mama_u32_t microseconds, mamaDateTimePrecision precision=MAMA_DATE_TIME_PREC_UNKNOWN, mamaDateTimeHints hints=0)
 
mamaDateTimePrecision getPrecision ()
 
void setPrecision (mamaDateTimePrecision precision)
 
mamaDateTimeHints getHints ()
 
void setHints (mamaDateTimeHints hints)
 
void setFromString (const char *str, const MamaTimeZone *tz=NULL)
 
void setFromString (const char *str, mama_size_t strLen, const MamaTimeZone *tz=NULL)
 
void setToNow ()
 
void setToMidnightToday (const MamaTimeZone *tz=NULL)
 
void setFromStructTimeSpec (struct timespec &inputTimeSpec)
 Set the underlying C mamaDateTime from a TimeSpec Struct. More...
 
void set (struct timeval inputTimeVal)
 Set the underlying C mamaDateTime from a TimeVal Struct. More...
 
void set (mama_u32_t year, mama_u32_t month, mama_u32_t day, mama_u32_t hour, mama_u32_t minute, mama_u32_t second, mama_u32_t microsecond, mamaDateTimePrecision precision=MAMA_DATE_TIME_PREC_UNKNOWN, const MamaTimeZone *tz=NULL)
 Set the entire date and time for the MamaDateTime. More...
 
void setTime (mama_u32_t hour, mama_u32_t minute, mama_u32_t second, mama_u32_t microsecond, mamaDateTimePrecision precision=MAMA_DATE_TIME_PREC_UNKNOWN, const MamaTimeZone *tz=NULL)
 Set the time-of-day portion of the MamaDateTime. More...
 
void setDate (mama_u32_t year, mama_u32_t month, mama_u32_t day)
 Set the date portion of the MamaDateTime. More...
 
void copyTime (const MamaDateTime &copy)
 Copy the time-of-day portion of the MamaDateTime. More...
 
void copyDate (const MamaDateTime &copy)
 Copy the date portion of the MamaDateTime. More...
 
void clear ()
 Clear the entire MamaDateTime. More...
 
void clearTime ()
 Clear the time-of-day portion of the MamaDateTime. More...
 
void clearDate ()
 Clear the date portion of the MamaDateTime. More...
 
void addSeconds (mama_f64_t seconds)
 
void addSeconds (mama_i32_t seconds)
 
void addMicroseconds (mama_i64_t microSeconds)
 
mama_u64_t getEpochTimeMicroseconds () const
 Get the date and time as microseconds since the Epoch, (using the UTC timezone). More...
 
mama_u64_t getEpochTimeMicroseconds (const MamaTimeZone &tz) const
 Get the date and time as microseconds since the Epoch in the supplied time zone. More...
 
mama_u64_t getEpochTimeMilliseconds () const
 
mama_u64_t getEpochTimeMilliseconds (const MamaTimeZone &tz) const
 
mama_f64_t getEpochTimeSeconds () const
 
mama_f64_t getEpochTimeSeconds (const MamaTimeZone &tz) const
 
mama_i64_t getEpochTimeExtSeconds () const
 Get the extended datetime value in whole seconds since the Epoch (UTC). More...
 
uint32_t getEpochTimeExtNanoseconds () const
 Get the extended datetime subsecond portion of the datetime value in nanoseconds. More...
 
void setEpochTimeExt (mama_i64_t seconds, uint32_t nanoseconds) const
 Set the extended datetime values expressed in seconds since the Epoch (UTC) and nanoseconds since this epoch time. More...
 
mama_f64_t getEpochTimeSecondsWithCheck () const
 Get the date and time as seconds since the Epoch, (using the UTC timezone). More...
 
void getAsString (char *result, mama_size_t maxLen) const
 
void getTimeAsString (char *result, mama_size_t maxLen) const
 
void getDateAsString (char *result, mama_size_t maxLen) const
 
const char * getAsString () const
 Return a string representation of the date/time. More...
 
const char * getTimeAsString () const
 
const char * getDateAsString () const
 
void getAsFormattedString (char *result, mama_size_t maxLen, const char *format) const
 
void getAsFormattedString (char *result, mama_size_t maxLen, const char *format, const MamaTimeZone &tz) const
 
void getAsStructTimeVal (struct timeval &result) const
 
void getAsStructTimeVal (struct timeval &result, const MamaTimeZone &tz) const
 
void getAsStructTimeSpec (struct timespec &result) const
 
void getAsStructTm (struct tm &result) const
 
void getAsStructTm (struct tm &result, const MamaTimeZone &tz) const
 
mama_u32_t getYear () const
 
mama_u32_t getMonth () const
 
mama_u32_t getDay () const
 
mama_u32_t getHour () const
 
mama_u32_t getMinute () const
 
mama_u32_t getSecond () const
 
mama_u32_t getMicrosecond () const
 
mamaDayOfWeek getDayOfWeek () const
 
bool hasTime () const
 Return whether the object has a time component. More...
 
bool hasDate () const
 Return whether the object has a date component. More...
 
mamaDateTime getCValue ()
 
const mamaDateTime getCValue () const
 

Detailed Description

A date/time representation with additional hints for precision, advanced output formatting and support for time zone conversion (using the MamaTimeZone type).

Hints include:

  • Whether the time stamp contains a date part, a time part, or both.
  • The level of accuracy (if known) of the time part (e.g., minutes, seconds, milliseconds, etc.).

The output format strings are similar to that available for the strftime() function with the addition of %; which adds optional (non-zero) fractional second to the string, and %: which adds fractional seconds including trailing zeros, but does not include the ".". The following table provides examples of output.

Actual Time Output of "%T%;" Output of "%T%.:"
01:23:45 and 678 millisecs 01:23:45.678 01:23:45.678
01:23:45 and 0 millisecs 01:23:45 01:23:45.000

Constructor & Destructor Documentation

§ MamaDateTime() [1/3]

Wombat::MamaDateTime::MamaDateTime ( )

§ MamaDateTime() [2/3]

Wombat::MamaDateTime::MamaDateTime ( const MamaDateTime copy)

§ MamaDateTime() [3/3]

Wombat::MamaDateTime::MamaDateTime ( const char *  str,
const MamaTimeZone tz = NULL 
)
explicit

Constructor taking a string argument.

This is the same as calling setFromString() immediately after construction.

§ ~MamaDateTime()

Wombat::MamaDateTime::~MamaDateTime ( )

Member Function Documentation

§ operator=()

MamaDateTime& Wombat::MamaDateTime::operator= ( const MamaDateTime rhs)

§ operator==()

bool Wombat::MamaDateTime::operator== ( const MamaDateTime rhs) const

§ operator!=()

bool Wombat::MamaDateTime::operator!= ( const MamaDateTime rhs) const
inline

§ operator<()

bool Wombat::MamaDateTime::operator< ( const MamaDateTime rhs) const

§ operator>()

bool Wombat::MamaDateTime::operator> ( const MamaDateTime rhs) const

§ compare()

int Wombat::MamaDateTime::compare ( const MamaDateTime rhs) const

§ empty()

bool Wombat::MamaDateTime::empty ( ) const

§ setEpochTime()

void Wombat::MamaDateTime::setEpochTime ( mama_u32_t  secondsSinceEpoch,
mama_u32_t  microseconds,
mamaDateTimePrecision  precision = MAMA_DATE_TIME_PREC_UNKNOWN 
)

§ setEpochTimeF64()

void Wombat::MamaDateTime::setEpochTimeF64 ( double  secondsSinceEpoch)

§ setEpochTimeMilliseconds()

void Wombat::MamaDateTime::setEpochTimeMilliseconds ( mama_u64_t  millisecondsSinceEpoch)

§ setEpochTimeMicroseconds()

void Wombat::MamaDateTime::setEpochTimeMicroseconds ( mama_u64_t  microsecondsSinceEpoch)

§ setWithHints()

void Wombat::MamaDateTime::setWithHints ( mama_u32_t  secondsSinceEpoch,
mama_u32_t  microseconds,
mamaDateTimePrecision  precision = MAMA_DATE_TIME_PREC_UNKNOWN,
mamaDateTimeHints  hints = 0 
)

§ getPrecision()

mamaDateTimePrecision Wombat::MamaDateTime::getPrecision ( )

§ setPrecision()

void Wombat::MamaDateTime::setPrecision ( mamaDateTimePrecision  precision)

§ getHints()

mamaDateTimeHints Wombat::MamaDateTime::getHints ( )

§ setHints()

void Wombat::MamaDateTime::setHints ( mamaDateTimeHints  hints)

§ setFromString() [1/2]

void Wombat::MamaDateTime::setFromString ( const char *  str,
const MamaTimeZone tz = NULL 
)

§ setFromString() [2/2]

void Wombat::MamaDateTime::setFromString ( const char *  str,
mama_size_t  strLen,
const MamaTimeZone tz = NULL 
)

§ setToNow()

void Wombat::MamaDateTime::setToNow ( )

§ setToMidnightToday()

void Wombat::MamaDateTime::setToMidnightToday ( const MamaTimeZone tz = NULL)

§ setFromStructTimeSpec()

void Wombat::MamaDateTime::setFromStructTimeSpec ( struct timespec &  inputTimeSpec)

Set the underlying C mamaDateTime from a TimeSpec Struct.

This will allow for extended date ranges.

§ set() [1/2]

void Wombat::MamaDateTime::set ( struct timeval  inputTimeVal)

Set the underlying C mamaDateTime from a TimeVal Struct.

This will allow for extended date ranges.

§ set() [2/2]

void Wombat::MamaDateTime::set ( mama_u32_t  year,
mama_u32_t  month,
mama_u32_t  day,
mama_u32_t  hour,
mama_u32_t  minute,
mama_u32_t  second,
mama_u32_t  microsecond,
mamaDateTimePrecision  precision = MAMA_DATE_TIME_PREC_UNKNOWN,
const MamaTimeZone tz = NULL 
)

Set the entire date and time for the MamaDateTime.

The year, month and day parameters must all be integers greater than zero.

Parameters
yearThe year (must be 1970 or later).
monthThe month (1 - 12).
dayThe day (1 - 31).
hourThe hour (0 - 23).
minuteThe minute (0 - 59).
secondThe second (0 - 59).
microsecondThe second (0 - 999999).
precisionAn explicit precision, if known.
tzA timezone to shift from.

§ setTime()

void Wombat::MamaDateTime::setTime ( mama_u32_t  hour,
mama_u32_t  minute,
mama_u32_t  second,
mama_u32_t  microsecond,
mamaDateTimePrecision  precision = MAMA_DATE_TIME_PREC_UNKNOWN,
const MamaTimeZone tz = NULL 
)

Set the time-of-day portion of the MamaDateTime.

The date portion is not affected.

Parameters
hourThe hour (0 - 23).
minuteThe minute (0 - 59).
secondThe second (0 - 59).
microsecondThe second (0 - 999999).
precisionAn explicit precision, if known.
tzA timezone to shift from.

§ setDate()

void Wombat::MamaDateTime::setDate ( mama_u32_t  year,
mama_u32_t  month,
mama_u32_t  day 
)

Set the date portion of the MamaDateTime.

The time-of-day portion is not affected. The year, month and day parameters must all be integers greater than zero.

Parameters
yearThe year (must be 1970 or later).
monthThe month (1 - 12).
dayThe day (1 - 31).

§ copyTime()

void Wombat::MamaDateTime::copyTime ( const MamaDateTime copy)

Copy the time-of-day portion of the MamaDateTime.

The date portion is not affected.

Parameters
copyThe object to copy from

§ copyDate()

void Wombat::MamaDateTime::copyDate ( const MamaDateTime copy)

Copy the date portion of the MamaDateTime.

The time-of-day portion is not affected.

Parameters
copyThe object to copy from

§ clear()

void Wombat::MamaDateTime::clear ( )

Clear the entire MamaDateTime.

§ clearTime()

void Wombat::MamaDateTime::clearTime ( )

Clear the time-of-day portion of the MamaDateTime.

The date portion is not affected.

§ clearDate()

void Wombat::MamaDateTime::clearDate ( )

Clear the date portion of the MamaDateTime.

The time-of-day portion is not affected.

§ addSeconds() [1/2]

void Wombat::MamaDateTime::addSeconds ( mama_f64_t  seconds)

§ addSeconds() [2/2]

void Wombat::MamaDateTime::addSeconds ( mama_i32_t  seconds)

§ addMicroseconds()

void Wombat::MamaDateTime::addMicroseconds ( mama_i64_t  microSeconds)

§ getEpochTimeMicroseconds() [1/2]

mama_u64_t Wombat::MamaDateTime::getEpochTimeMicroseconds ( ) const

Get the date and time as microseconds since the Epoch, (using the UTC timezone).

Returns
The number of microseconds since the Epoch.

§ getEpochTimeMicroseconds() [2/2]

mama_u64_t Wombat::MamaDateTime::getEpochTimeMicroseconds ( const MamaTimeZone tz) const

Get the date and time as microseconds since the Epoch in the supplied time zone.

Parameters

§ getEpochTimeMilliseconds() [1/2]

mama_u64_t Wombat::MamaDateTime::getEpochTimeMilliseconds ( ) const

§ getEpochTimeMilliseconds() [2/2]

mama_u64_t Wombat::MamaDateTime::getEpochTimeMilliseconds ( const MamaTimeZone tz) const

§ getEpochTimeSeconds() [1/2]

mama_f64_t Wombat::MamaDateTime::getEpochTimeSeconds ( ) const

§ getEpochTimeSeconds() [2/2]

mama_f64_t Wombat::MamaDateTime::getEpochTimeSeconds ( const MamaTimeZone tz) const

§ getEpochTimeExtSeconds()

mama_i64_t Wombat::MamaDateTime::getEpochTimeExtSeconds ( ) const

Get the extended datetime value in whole seconds since the Epoch (UTC).

Returns
The number of whole seconds since the Epoch.

§ getEpochTimeExtNanoseconds()

uint32_t Wombat::MamaDateTime::getEpochTimeExtNanoseconds ( ) const

Get the extended datetime subsecond portion of the datetime value in nanoseconds.

Returns
The nanosecond portion of the datetime value.

§ setEpochTimeExt()

void Wombat::MamaDateTime::setEpochTimeExt ( mama_i64_t  seconds,
uint32_t  nanoseconds 
) const

Set the extended datetime values expressed in seconds since the Epoch (UTC) and nanoseconds since this epoch time.

Parameters
secondsThe number of seconds since the Epoch.
nanosecondsThe number of nanoseconds since the seconds parameter.

§ getEpochTimeSecondsWithCheck()

mama_f64_t Wombat::MamaDateTime::getEpochTimeSecondsWithCheck ( ) const

Get the date and time as seconds since the Epoch, (using the UTC timezone).

If no date value is contained in the dateTime then it will be set to today's date and the calculation made.

Returns
The number of seconds, (including partial seconds), since the Epoch.

§ getAsString() [1/2]

void Wombat::MamaDateTime::getAsString ( char *  result,
mama_size_t  maxLen 
) const

§ getTimeAsString() [1/2]

void Wombat::MamaDateTime::getTimeAsString ( char *  result,
mama_size_t  maxLen 
) const

§ getDateAsString() [1/2]

void Wombat::MamaDateTime::getDateAsString ( char *  result,
mama_size_t  maxLen 
) const

§ getAsString() [2/2]

const char* Wombat::MamaDateTime::getAsString ( ) const

Return a string representation of the date/time.

Note that the alternative getAsString() methods are more efficient because these method must allocate a temporary buffer (automatically destroyed upon object destruction). The timezone must to set to UTC if calling this from multiple threads concurrently to avoid contention in strftime.p

§ getTimeAsString() [2/2]

const char* Wombat::MamaDateTime::getTimeAsString ( ) const

§ getDateAsString() [2/2]

const char* Wombat::MamaDateTime::getDateAsString ( ) const

§ getAsFormattedString() [1/2]

void Wombat::MamaDateTime::getAsFormattedString ( char *  result,
mama_size_t  maxLen,
const char *  format 
) const

§ getAsFormattedString() [2/2]

void Wombat::MamaDateTime::getAsFormattedString ( char *  result,
mama_size_t  maxLen,
const char *  format,
const MamaTimeZone tz 
) const

§ getAsStructTimeVal() [1/2]

void Wombat::MamaDateTime::getAsStructTimeVal ( struct timeval &  result) const

§ getAsStructTimeVal() [2/2]

void Wombat::MamaDateTime::getAsStructTimeVal ( struct timeval &  result,
const MamaTimeZone tz 
) const

§ getAsStructTimeSpec()

void Wombat::MamaDateTime::getAsStructTimeSpec ( struct timespec &  result) const

§ getAsStructTm() [1/2]

void Wombat::MamaDateTime::getAsStructTm ( struct tm &  result) const

§ getAsStructTm() [2/2]

void Wombat::MamaDateTime::getAsStructTm ( struct tm &  result,
const MamaTimeZone tz 
) const

§ getYear()

mama_u32_t Wombat::MamaDateTime::getYear ( ) const

§ getMonth()

mama_u32_t Wombat::MamaDateTime::getMonth ( ) const

§ getDay()

mama_u32_t Wombat::MamaDateTime::getDay ( ) const

§ getHour()

mama_u32_t Wombat::MamaDateTime::getHour ( ) const

§ getMinute()

mama_u32_t Wombat::MamaDateTime::getMinute ( ) const

§ getSecond()

mama_u32_t Wombat::MamaDateTime::getSecond ( ) const

§ getMicrosecond()

mama_u32_t Wombat::MamaDateTime::getMicrosecond ( ) const

§ getDayOfWeek()

mamaDayOfWeek Wombat::MamaDateTime::getDayOfWeek ( ) const

§ hasTime()

bool Wombat::MamaDateTime::hasTime ( ) const

Return whether the object has a time component.

§ hasDate()

bool Wombat::MamaDateTime::hasDate ( ) const

Return whether the object has a date component.

§ getCValue() [1/2]

mamaDateTime Wombat::MamaDateTime::getCValue ( )

§ getCValue() [2/2]

const mamaDateTime Wombat::MamaDateTime::getCValue ( ) const