A class for parsing, formatting and doing operations on time, based on Unix time conventions, where leap seconds are ignored, so that there are always 60 seconds in a minute, 3600 seconds in an hour and 86400 seconds in a day. More...

#include <UTime.h>

Public Member Functions
	UTime ()
	No-arg constructor initializes to current time, with isUTC() true. More...

	UTime (long long t)
	Constructor. More...

	UTime (time_t t)
	Constructor. More...

	UTime (double t)
	Constructor. More...

	UTime (bool utc, const struct tm *tmp, int usecs=0)
	Constructor from a struct tm. More...

	UTime (bool utc, int year, int mon, int day, int hour, int min, double sec)
	Constructor. More...

	UTime (bool utc, int year, int yday, int hour, int min, double sec)
	Constructor. More...

	UTime (const UTime &u)

void	setFromSecs (time_t t)

struct tm *	toTm (bool utc, struct tm tmp, int usecs=0) const
	Set values in a struct tm from a UTime. More...

struct tm *	toTm (struct tm tmp, int usecs=0) const
	Set values in a struct tm from a UTime, using the isUTC() attribute. More...

bool	isUTC () const
	Format this UTime relative to UTC, or based on the TZ environment variable. More...

void	setUTC (bool val)
	Format this UTime relative to UTC, or the local timezone? More...

void	set (bool utc, const std::string &string, int *nparsed=0) throw (ParseException)
	Updates the value of a UTime by doing a parse(utc,string,nparsed). More...

void	set (bool utc, const std::string &string, const std::string &format, int *nparsed=0) throw (ParseException)
	Updates the value of a UTime by doing a parse(utc,string,format,nparsed). More...

std::string	format (bool utc, const std::string &fmt) const
	Format a UTime into a string. More...

std::string	format (const std::string &fmt) const
	Format a UTime into a string. More...

std::string	format (bool utc) const
	Format a UTime into a string using the format returned by getFormat(). More...

std::string	format () const
	Format a UTime into a string using the format returned by getFormat(). More...

UTime &	operator= (const UTime &u)

UTime &	operator= (long long u)

UTime	operator+ (long long u) const

UTime	operator- (long long u) const

long long	operator- (const UTime &u) const

UTime &	operator+= (long long u)

UTime &	operator-= (long long u)

bool	operator< (const UTime &u) const

bool	operator<= (const UTime &u) const

bool	operator> (const UTime &u) const

bool	operator>= (const UTime &u) const

bool	operator== (const UTime &u) const

bool	operator!= (const UTime &u) const

UTime	earlier (long long y) const

long long	toUsecs () const

double	toDoubleSecs () const

time_t	toSecs () const

UTime &	setFormat (const std::string &val)
	Set the format used when converting this UTime to a string with format(utc), or format(), or on a ostream. More...

const std::string &	getFormat () const
	Get the format used when converting this UTime to a string with format(utc), or format(), or on a ostream. More...

struct tm	tm (bool utc) const

Static Public Member Functions
static long long	fromTm (bool utc, const struct tm *tmp, int usecs=0)
	Return number of non-leap micro-seconds since Jan 1970 00:00 UTC computed from time fields in a struct tm. More...

static UTime	parse (bool utc, const std::string &string, int *nparsed=0) throw (ParseException)
	Parse a character string into a UTime, using these formats until success: More...

static UTime	parse (bool utc, const std::string &string, const std::string &format, int *nparsed=0) throw (ParseException)
	Parse a character string into a UTime. More...

static int	month (std::string monstr)

static void	setDefaultFormat (const std::string &val)
	Static method to set the default output format. More...

static const std::string &	getDefaultFormat ()

static void	setTZ (const std::string &val)
	Set the TZ environment variable to val. More...

static std::string	getTZ ()

static long long	pmod (long long x, long long y)
	Positive modulus: if x > 0, returns x % y else y + (x % y) Useful for time calculation on negative times, for example: pmod((long long)ut,USECS_PER_DAY) gives microseconds since 00:00 of day whether date is negative or positive. More...

Static Protected Member Functions
static long long	fromSecs (time_t x)
	Convert a unsigned value in seconds to a value in the units of UTime. More...

static long long	fromSecs (double x)
	Convert a double value in seconds to a value in the units of UTime. More...

static double	toDoubleSecs (long long x)

static time_t	toSecs (long long x)

Private Member Functions
bool	checkParse (bool utc, const std::string &str, const std::string &fmt, int *ncharp, bool throwx=false)
	Parse into this UTime same as parse(), returning true on success. More...

Private Attributes
long long	_utime
	non-leap micro-seconds since 1970 Jan 1 00:00 UTC. More...

std::string	_fmt
	strftime string to use when formatting this UTime. More...

bool	_utc
	Whether to format this UTime relative to UTC. More...

Static Private Attributes
static std::string	_defaultFormat

static Mutex	_fmtMutex

Friends
template<typename charT >
std::basic_ostream< charT, std::char_traits< charT > > &	operator<< (std::basic_ostream< charT, std::char_traits< charT > > &os, const UTime &x)

Detailed Description

A class for parsing, formatting and doing operations on time, based on Unix time conventions, where leap seconds are ignored, so that there are always 60 seconds in a minute, 3600 seconds in an hour and 86400 seconds in a day.

Time values are typically assigned by a computer with an NTP controlled clock, and that time is converted to a Unix time as the number of non-leap seconds since Jan 1970 00:00 GMT. Conversion back to human readable time uses the same no-leap-second convention. Time values around the time that a system's NTP clock are being adjusted for a leap second will be indeterminate by up to a second, depending on how the Unix clock on that system was adjusted.

Constructor & Destructor Documentation

UTime::UTime ( )

No-arg constructor initializes to current time, with isUTC() true.

References _utime, NSECS_PER_USEC, and USECS_PER_SEC.

Referenced by checkParse(), earlier(), operator+(), and operator-().

nidas::util::UTime::UTime ( long long t )

inline

Constructor.

isUTC() will be set to true.

Parameters

t	Non-leap microseconds since Jan 1, 1970 00:00 UTC

nidas::util::UTime::UTime ( time_t t )

inline

Constructor.

isUTC() will be set to true.

Parameters

t	Non-leap seconds since Jan 1, 1970 00:00 UTC

nidas::util::UTime::UTime ( double t )

inline

Constructor.

isUTC() will be set to true.

Parameters

t	Non-leap seconds since Jan 1, 1970 00:00 UTC

UTime::UTime	(	bool	utc,
		const struct tm *	tmp,
		int	usecs = `0`
	)

Constructor from a struct tm.

See the fromTm() static method.

UTime::UTime	(	bool	utc,
		int	year,
		int	mon,
		int	day,
		int	hour,
		int	min,
		double	sec
	)

Constructor.

mon is 1-12, day is 1-31. Note that mon differs from the definition of tm_mon in struct tm which is in the range 0-11.

References _utime, fromSecs(), fromTm(), and tm().

UTime::UTime	(	bool	utc,
		int	year,
		int	yday,
		int	hour,
		int	min,
		double	sec
	)

Constructor.

yday is day of year, 1-366. Note that yday differs from the definition of tm_yday in struct tm which is in the range 0-365.

References _utime, fromSecs(), fromTm(), and tm().

nidas::util::UTime::UTime ( const UTime & u )

inline

Member Function Documentation

bool UTime::checkParse	(	bool	utc,
		const std::string &	str,
		const std::string &	fmt,
		int *	ncharp,
		bool	throwx = `false`
	)

private

Parse into this UTime same as parse(), returning true on success.

If parsing fails and throwx is true, then throw an exception. If parsing fails and throwx is false, then return false.

References tm(), UTime(), and VLOG.

Referenced by parse().

UTime UTime::earlier ( long long y ) const

References _utime, and UTime().

Referenced by format(), and toTm().

std::string UTime::format	(	bool	utc,
		const std::string &	fmt
	)		const

Format a UTime into a string.

Parameters

utc,:	if true, use UTC timezone, otherwise the TZ environment variable.
fmt,:	a time format in the form of strftime. All the % format descriptors of strftime are available. In addition one can use "%nf" to print fractional seconds, where n is the precision, a digit from 1 to 9. n defaults to 3, providing millisecond precision, if not specified. For example: ut.format(true,"time is: %Y %m %d %H:%M:%S.%2f");

The "%s" format descriptor will print the number of non-leap seconds since 1970 Jan 01 00:00 UTC. This is the same number returned by toSecs(). Note that s will generate the same value as strftime in the following code: struct tm tm; char timestr[12]; time_t tval = mytime; localtime_r(&tval,&tm); strftime(timestr,sizeof(timestr),"%s",&tm);

Using gmtime_r to fill in struct tm and then call strftime with a s generates the wrong value if the local timezone is other than GMT, since strftime with a s assumes the struct tm is in the local timezone: gmtime_r(&tval,&tm); strftime(timestr,sizeof(timestr),"%s",&tm); // wrong

References _utime, earlier(), tm(), toUsecs(), and USECS_PER_SEC.

Referenced by nidas::core::SampleClock::addSampleDate(), nidas::dynld::raf::SyncRecordSource::advanceRecord(), nidas::dynld::raf::IRIGSensor::checkClock(), nidas::dynld::StatisticsCruncher::computeStats(), nidas::util::FileSet::createFile(), nidas::dynld::isff::SE_GOESXmtr::decodeClock(), nidas::core::SampleTracer::format_time(), format_time(), nidas::util::FileSet::formatName(), ftime(), nidas::core::ProjectConfigs::getConfig(), main(), nidas::dynld::isff::CSAT3_Sonic::open(), operator<<(), nidas::core::operator<<(), nidas::core::Polynomial::parseFields(), nidas::dynld::RawSampleService::printClock(), nidas::dynld::RawSampleService::printStatus(), nidas::core::SampleArchiver::printStatus(), nidas::dynld::isff::SimGOESXmtr::printStatus(), nidas::dynld::raf::SyncRecordGenerator::printStatus(), nidas::dynld::raf::TwoD32_USB::processImage(), nidas::core::VariableConverter::readCalFile(), nidas::core::CalFile::readCFInclude(), nidas::dynld::AsciiOutput::receive(), DumpClient::receive(), nidas::dynld::StatisticsCruncher::receive(), nidas::core::NearestResamplerAtRate::receive(), MergeVerifier::run(), NidsMerge::run(), StatsProcess::run(), DmdA2dCk::run(), nidas::core::DSMEngineStat::run(), nidas::dynld::isff::GOESOutput::run(), DataPrep::run(), Garmin::sendInit(), GPS_SetClock::setSysTime(), nidas::dynld::isff::SE_GOESXmtr::testTransmitSE120(), tformat(), time_format(), nidas::dynld::isff::WisardMote::unpackAccumSec(), nidas::core::MessageStreamScanner::warnBackwardsStepTimeTag(), nidas::core::MessageStreamScanner::warnNonIncrTimeTag(), and nidas::core::Socket::write().

string UTime::format ( const std::string & fmt ) const

Format a UTime into a string.

isUTC() attribute detemines whether it is formatted in UTC or based on the TZ environment variable.

Parameters

fmt,: as in format(utc,fmt).

References _utc, and format().

string UTime::format ( bool utc ) const

Format a UTime into a string using the format returned by getFormat().

Parameters

utc,: if true, use UTC timezone, otherwise the TZ environment variable.

References format(), and getFormat().

string UTime::format ( ) const

Format a UTime into a string using the format returned by getFormat().

isUTC() attribute detemines whether it is formatted in UTC or based on the TZ environment variable.

References _utc, and getFormat().

Referenced by format().

static long long nidas::util::UTime::fromSecs ( time_t x )

inlinestaticprotected

Convert a unsigned value in seconds to a value in the units of UTime.

References USECS_PER_SEC.

Referenced by setFromSecs(), and UTime().

static long long nidas::util::UTime::fromSecs ( double x )

inlinestaticprotected

Convert a double value in seconds to a value in the units of UTime.

References USECS_PER_SEC.

long long UTime::fromTm	(	bool	utc,
		const struct tm *	tmp,
		int	usecs = `0`
	)

static

Return number of non-leap micro-seconds since Jan 1970 00:00 UTC computed from time fields in a struct tm.

See "man mktime". If the value of tmp->tm_yday is greater than or equal to 0, and tmp->tm_mon is less than 0 or tmp->tm_mday is less than 1, then the result is calculated using tm_yday. Otherwise tm_mon and tm_mday are used.

References tm(), and USECS_PER_SEC.

Referenced by nidas::dynld::isff::WisardMote::unpackAccumSec(), and UTime().

const string & UTime::getDefaultFormat ( )

static

References _defaultFormat, and _fmtMutex.

Referenced by getFormat().

const std::string& nidas::util::UTime::getFormat ( ) const

inline

Get the format used when converting this UTime to a string with format(utc), or format(), or on a ostream.

If the user hasn't set the format, the default value is getDefaultFormat().

References _fmt, and getDefaultFormat().

Referenced by format().

string UTime::getTZ ( )

static

References nidas::util::Process::getEnvVar().

Referenced by nidas::core::CalFile::parseTime().

bool nidas::util::UTime::isUTC ( ) const

inline

Format this UTime relative to UTC, or based on the TZ environment variable.

References _utc.

int UTime::month ( std::string monstr )

static

References tm().

bool nidas::util::UTime::operator!= ( const UTime & u ) const

inline

References _utime.

UTime nidas::util::UTime::operator+ ( long long u ) const

inline

References _utime, and UTime().

UTime& nidas::util::UTime::operator+= ( long long u )

inline

References _utime.

UTime nidas::util::UTime::operator- ( long long u ) const

inline

References _utime, and UTime().

long long nidas::util::UTime::operator- ( const UTime & u ) const

inline

References _utime.

UTime& nidas::util::UTime::operator-= ( long long u )

inline

References _utime.

bool nidas::util::UTime::operator< ( const UTime & u ) const

inline

References _utime.

bool nidas::util::UTime::operator<= ( const UTime & u ) const

inline

References _utime.

UTime& nidas::util::UTime::operator= ( const UTime & u )

inline

References _fmt, and _utime.

UTime& nidas::util::UTime::operator= ( long long u )

inline

References _utime.

bool nidas::util::UTime::operator== ( const UTime & u ) const

inline

References _utime.

bool nidas::util::UTime::operator> ( const UTime & u ) const

inline

References _utime.

bool nidas::util::UTime::operator>= ( const UTime & u ) const

inline

References _utime.

UTime UTime::parse	(	bool	utc,
		const std::string &	string,
		int *	nparsed = `0`
	)
throw	(	ParseException
	)

static

Parse a character string into a UTime, using these formats until success:

[CC]YY [cmon|mon] day h:m[:s.f] h,m and s are one or two digits [CC]YY [cmon|mon] day hhmmss[.f] hh, mm and ss are two digits [CC]YY [cmon|mon] day s.f YYYY-mm-dd[THH:MM[:SS[.f]]] ISO format YYYY-mm-dd[ HH:MM[:SS[.f]]] ISO format with space separator

"cmon" is a character month or abbreviation. "mon" is a numeric month (1-12). "day" is day of month, 1-31. "h" or "hh" are in the range 0-23. "f" is the fractional seconds, one or more digits. The last format, "s.f" is the number of non-leap seconds since 1970 Jan 1 00:00 GMT. For example, 1262304000.0 is 2010 Jan 1 00:00 GMT. Note: one can also use a "%s" descriptor in the format argument to parse(false,str,format,nparsed) to do the same conversion. If all parsing fails, throw ParseException.

Parameters

nparsed,: number of characters parsed.

References checkParse(), and USECS_PER_SEC.

Referenced by ARLIngest::arl_ingest_one(), nidas::core::ProjectConfig::fromDOMElement(), main(), nidas::dynld::raf::SyncServer::openStream(), ProjConfigIO::parseRunstring(), MergeVerifier::parseRunstring(), nidas::core::CalFile::parseTime(), nidas::core::NidasApp::parseTime(), and set().

UTime UTime::parse	(	bool	utc,
		const std::string &	string,
		const std::string &	format,
		int *	nparsed = `0`
	)
throw	(	ParseException
	)

static

Parse a character string into a UTime.

Parameters

format,:	a time format in the form of strptime. All the % format descriptors of strptime are available. In addition one can use "%nf" to parse fractional seconds, where n is the number of digits in the fraction to parse. n defaults to 3 if not specified. If the "%s" descriptor is used, then the utc parameter is silently forced to false, since strptime does that conversion in local time.
nparsed,:	number of characters parsed. Example: UTime ut = UTime::parse(true,timestr,"%Y %m %d %H:%M:%S.%2f");

References checkParse().

long long UTime::pmod	(	long long	x,
		long long	y
	)

static

Positive modulus: if x > 0, returns x % y else y + (x % y) Useful for time calculation on negative times, for example: pmod((long long)ut,USECS_PER_DAY) gives microseconds since 00:00 of day whether date is negative or positive.