PSTime::Time Class Reference
[PSTime package]

Standard time class for use in LCLS software. More...

#include <Time.h>

List of all members.

Public Types
	UTC
	Local
enum	Zone { UTC, Local }
	Type for time zone designation. More...
Public Member Functions
	Time ()
	Default constructor makes zero (epoch) time.
	Time (time_t sec_since_1970_01_01, uint32_t nsec=0)
	Construct from UNIX time.
	Time (int year, int month, int day, int hour, int min, int sec, uint32_t nsec=0, Zone zone=Local)
	Construct from broken-down representation.
	Time (struct timespec &ts)
	Constructs a time from the timespec struct (for high resolution time).
	Time (struct tm &tms, Zone zone=Local)
	Constructs a time from the tm struct (broken-down time) and zone.
	Time (const std::string &str)
	Constructs a time from the string representation.
Duration	operator- (const Time &t) const
	Subtract two times and return duration.
Time &	operator+= (const Duration &d)
	Add duration to time.
Time &	operator-= (const Duration &d)
	Subtract duration from time.
bool	operator!= (const Time &t) const
	Compare two times.
bool	operator== (const Time &t) const
	Compare two times.
bool	operator< (const Time &t) const
	Compare two times.
bool	operator> (const Time &t) const
	Compare two times.
bool	operator>= (const Time &t) const
	Compare two times.
bool	operator<= (const Time &t) const
	Compare two times.
time_t	sec () const
	POSIX sec. since 00:00:00 Jan. 1, 1970 UTC.
uint32_t	nsec () const
	returns nanoseconds value
timespec	getTimeSpec () const
	Returns the Time object content via high-resolution time timespec structure.
tm	gettm (Zone zone=Local) const
	Returns the Time object content via broken-down time tm structure for indicated zone.
std::string	asString (Zone zone=Local, int nsecPrecision=9) const
	Return time representation in extended ISO8601 format.
std::string	asStringCompact (Zone zone=Local, int nsecPrecision=0) const
	Return time representation in basic ISO8601 format.
std::string	asStringFormat (const std::string &fmt="%Y-%m-%d %H:%M:%S%f%z", Zone zone=Local) const
	Format time according the supplied format string.
Static Public Member Functions
static Time	now ()
	Returns current time.

---

Detailed Description

Standard time class for use in LCLS software.

The transformation to/from human-readable time format, required by I/O, is based on the standard ISO8601 time presentation.

This is essentially a wrap-up for clock_gettime() [UNIX/POSIX time] access to high-resolution time method, utilizing "struct timespec" and "struct tm" from <time.h> Some arithmetics between PSTime and PSDuration objects is also available.

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Version:

$Id: Time.h 5859 2013-03-22 22:35:24Z salnikov@SLAC.STANFORD.EDU $

Author:

Mikhail S. Dubrovin

Definition at line 74 of file Time.h.

---

Member Enumeration Documentation

enum PSTime::Time::Zone

Type for time zone designation.

There are several methods in Time class which can produce time representation in either local or UTC time zones. By default all these methods assume local time zone, use UTC enum value as the parameter to those methods to produce UTC representation.

Enumerator:

UTC
Local

Definition at line 85 of file Time.h.

---

Constructor & Destructor Documentation

PSTime::Time::Time

(

)

Default constructor makes zero (epoch) time.

Use now() method if you need current time.

Definition at line 53 of file Time.cpp.

Referenced by now().

PSTime::Time::Time	(	time_t	sec_since_1970_01_01,
		uint32_t	nsec = 0
	)			[explicit]

Construct from UNIX time.

Constructs a time from an unsigned number of seconds since the the Unix epoch of 1970-01-01; nanoseconds are optional, if needed.

Definition at line 59 of file Time.cpp.

PSTime::Time::Time	(	int	year,
		int	month,
		int	day,
		int	hour,
		int	min,
		int	sec,
		uint32_t	nsec = 0,
		Zone	zone = Local
	)

Construct from broken-down representation.

Parameters:

[in]	year	Calendar year C.E. (e.g., 2010).
[in]	month	Month in the range [1,12].
[in]	day	Day of the month in the range [1,31].
[in]	hour	Hours in the range [0,23].
[in]	min	Minutes after the hour in the range [0,59].
[in]	sec	Seconds in the range [0,59*] (*) might be up to 61 for leap seconds.
[in]	nsec	Nanoseconds after the second in the range [0,999999999].
[in]	zone	Time zone, default is local time zone.

Definition at line 65 of file Time.cpp.

References PSTime::TimeUtils::timegm(), and UTC.

PSTime::Time::Time

(

struct timespec &

ts

)

[explicit]

Constructs a time from the timespec struct (for high resolution time).

Definition at line 92 of file Time.cpp.

PSTime::Time::Time	(	struct tm &	tms,
		Zone	zone = Local
	)			[explicit]

Constructs a time from the tm struct (broken-down time) and zone.

Definition at line 98 of file Time.cpp.

References PSTime::TimeUtils::timegm(), and UTC.

PSTime::Time::Time

(

const std::string &

str

)

[explicit]

Constructs a time from the string representation.

Accepts the time stamp in format:

• <date>, or
• <date> <time>[.<fraction-of-sec>][<zone>], or
• <date>T<time>[.<fraction-of-sec>][<zone>]

where

• <date> should be in format YYYY-MM-DD, YYYYMMDD, YYYY-MM, YYYYMM, or YYYY, if month or day is missing they are assumed to be 1;
• <time> should be in format HH:MM:SS, HHMMSS, HH:MM, HHMM, HH, if minutes or seconds are missing they are assumed to be 0;
• <fraction-of-sec> may have up to 9 digits; if this field is missing, it is assumed equal to 0, fraction require seconds to be specified;
• <zone> should be Z for UTC or in format {sign}HH[:MM] or {sign}HHMM, if this field is missing time is assumed to be in local time zone.

Examples of valid input are:

• "2000-01-01 00:00:00" - beginning of year 2000 in local time zone
• "2000-01-01 00:00:00Z" - beginning of year 2000 in UTC
• "2000-01-01 00:00:00-08" - beginning of year 2000 in PST
• "2000-01-01 00:00:00.000000001" - one nanosecond after the beginning of year 2000 in local time zone
• "20000101T000000.001" - one millisecond after the beginning of year 2000 in local time zone in compact form
• "20000101" - beginning of year 2000 in local time zone
• "2000" - same as above

Exceptions:

TimeParseException

Definition at line 110 of file Time.cpp.

References PSTime::TimeFormat::parseTime(), and mpids_test::t.

---

Member Function Documentation

std::string PSTime::Time::asString	(	Zone	zone = Local,
		int	nsecPrecision = 9
	)			const

Return time representation in extended ISO8601 format.

Output will look like "2011-01-30 17:52:50.123456789-08". This format is acceptable for human-readable output.

Parameters:

[in]	zone	Time zone to use for string representation
[in]	nsecPrecision	Precision of nanoseconds field, if 0 then nanoseconds will not be shown.

Definition at line 247 of file Time.cpp.

References PSTime::TimeFormat::format().

Referenced by main().

std::string PSTime::Time::asStringCompact	(	Zone	zone = Local,
		int	nsecPrecision = 0
	)			const

Return time representation in basic ISO8601 format.

Output will look like "20110130T175250-08". This format is intended for machine-readable output, such as timestamps in file names, etc.

Parameters:

[in]	zone	Time zone to use for string representation
[in]	nsecPrecision	Precision of nanoseconds field, if 0 then nanoseconds will not be shown.

Definition at line 263 of file Time.cpp.

References PSTime::TimeFormat::format().

Referenced by main().

std::string PSTime::Time::asStringFormat	(	const std::string &	fmt = "%Y-%m-%d %H:%M:%S%f%z",
		Zone	zone = Local
	)			const

Format time according the supplied format string.

For full description of the acceptable format codes see TimeFormat::format() method.

Parameters:

[in]	fmt	Format string
[in]	zone	Time zone to use for string representation

Definition at line 279 of file Time.cpp.

References PSTime::TimeFormat::format().

Referenced by main().

struct timespec PSTime::Time::getTimeSpec

(

)

const

Returns the Time object content via high-resolution time timespec structure.

Definition at line 222 of file Time.cpp.

struct tm PSTime::Time::gettm

(

Zone

zone = Local

)

const

Returns the Time object content via broken-down time tm structure for indicated zone.

Definition at line 231 of file Time.cpp.

Referenced by PSTime::TimeFormat::format().

Time PSTime::Time::now

(

)

[static]

Returns current time.

Returns current time.

Definition at line 288 of file Time.cpp.

References Time().

uint32_t PSTime::Time::nsec

(

)

const [inline]

returns nanoseconds value

Definition at line 210 of file Time.h.

Referenced by PSTime::TimeFormat::format(), main(), and operator-().

bool PSTime::Time::operator!=

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 181 of file Time.h.

References mpids_test::t.

Time & PSTime::Time::operator+=

(

const Duration &

d

)

Add duration to time.

Definition at line 197 of file Time.cpp.

References PSTime::Duration::getNsec(), PSTime::Duration::getSec(), and nsecInASec.

Duration PSTime::Time::operator-

(

const Time &

t

)

const

Subtract two times and return duration.

Duration cannot be negative, so t1-t2 is always equal to t2-t1.

Definition at line 127 of file Time.cpp.

References m_utcNsec, m_utcSec, nsec(), nsecInASec, and sec().

Time & PSTime::Time::operator-=

(

const Duration &

d

)

Subtract duration from time.

Definition at line 170 of file Time.cpp.

References PSTime::Duration::getNsec(), PSTime::Duration::getSec(), and nsecInASec.

bool PSTime::Time::operator<

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 189 of file Time.h.

References mpids_test::t.

bool PSTime::Time::operator<=

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 204 of file Time.h.

References mpids_test::t.

bool PSTime::Time::operator==

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 186 of file Time.h.

References mpids_test::t.

bool PSTime::Time::operator>

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 195 of file Time.h.

References mpids_test::t.

bool PSTime::Time::operator>=

(

const Time &

t

)

const [inline]

Compare two times.

Definition at line 201 of file Time.h.

References mpids_test::t.

time_t PSTime::Time::sec

(

)

const [inline]

POSIX sec. since 00:00:00 Jan. 1, 1970 UTC.

Definition at line 207 of file Time.h.

Referenced by PSTime::TimeFormat::format(), main(), and operator-().

---

The documentation for this class was generated from the following files:

• PSTime/include/Time.h
• PSTime/src/Time.cpp

---