This class deals primarily with Frames and Times. More...

#include <carma/util/Time.h>

Public Types
enum	TimeZone { LOCAL = -1, GMT = 0, UTC = GMT, ADT = 3, AST = 4, EDT = AST, EST = 5, CDT = EST, CST = 6, MDT = CST, MST = 7, PDT = MST, PST = 8, AKDT = PST, AKST = 9, HADT = AKST, HAST = 10 }
	enumeration for defining timezones More...

Public Member Functions
double	getStoredMJD () const
	Return stored MJD. More...

	Time ()
	Default constructor. More...

	Time (double mjd)
	Create a Time object with given mjd. More...

virtual	~Time ()
	Destructor. More...

Static Public Member Functions
static frameType	computeClosestFrame ()
	Get integral half-second frame that is closest to current time. More...

static frameType	computeClosestFrame (double mjd)
	Get closest integral half-second frame since 2000 to requested time. More...

static frameType	computeClosestFrame (const std::string &date, const std::string &format="%Y %b %d %H:%M:%S", const TimeZone tz=LOCAL)
	Get the closest integral half-second frame since 2000 to the input date string. More...

static frameType	computeCurrentFrame ()
	Get integral half-second frame since 2000, rounded down. More...

static frameType	computeFrame (double mjd)
	Get integral half-second frame since 2000 for requested time, rounded down. More...

static double	computeFrameTimeDiff (frameType frame, double delay=0)
	Get time difference of current time to the delayed frame. More...

static double	computeMJD (time_t seconds)
	Compute the MJD of the Unix-style seconds since 1970. More...

static double	computeMJD (const std::string &date, const std::string &format="%Y %b %d %H:%M:%S", const TimeZone tz=LOCAL)
	Get the MJD given the input date string. More...

static double	computeMJD1 (const std::string &date, const std::string &format="%Y %b %d %H:%M:%S", const TimeZone tz=LOCAL)

static double	computeTimeToFrame (frameType frame, double delay=0)
	Get time from now to a specific frame with a delay after the frame. More...

static double	computeTimeToNextFrame (double delay=0)
	Get time to next frame (half-second) with a delay after the frame. More...

static int	diffHrsFromGmt (const struct tm myTime, const time_t secondsSince1970)
	Utility for obtaining GMT from a local time with faster performance. More...

static std::string	getDateString (const std::string &dateFormat="%d%b%y")
	Get date string for current time. More...

static std::string	getDateString (double mjd, const std::string &dateFormat="%d%b%y")
	Get date string for specified time. More...

static std::string	getDateString (frameType frame, const std::string &dateFormat="%d%b%y")
	Get date for given frame as a string. More...

static std::string	getDateString (int imjd, const std::string &dateFormat="%d%b%y")
	Get date for given MJD day as a string. More...

static std::string	getDateTimeString (int precision=0, const std::string &dateFormat="%d%b%y")
	Get date and time of day string for current time. More...

static std::string	getDateTimeString (frameType frame, int precision=0, const std::string &dateFormat="%d%b%y")
	Get date and time of day string for given frame. More...

static std::string	getDateTimeString (double mjd, int precision=0, const std::string &dateFormat="%d%b%y")
	Get date and time of day string for specified time. More...

static std::string	getFITSdateString ()
	Get date string for current time in FITS notation. More...

static std::string	getFITSdateString (int imjd)
	Get date string for specified day. More...

static std::string	getFITSdateString (double mjd)
	Get date string for specified time. More...

static std::string	getFITSdateString (frameType frame)
	Get date for given frame as a string. More...

static std::string	getFITSdateTimeString (int precision=0)
	Get FITS style date and time of day string for current time. More...

static std::string	getFITSdateTimeString (double mjd, int precision=0)
	Get FITS style date and time of day string for specified time. More...

static std::string	getFITSdateTimeString (frameType frame, int precision=0)
	Get FITS style date and time of day string for given frame. More...

static struct tm	getGmtFromLmt (const std::string &date, const std::string &format, const Time::TimeZone tz)
	Utility for obtaining GMT from a local time Note:This is expensive. More...

::std::string	getNonBuggyByDesignDateTimeString (double mjd, const ::std::string &dateFormat)
	Get date and time of day string for current time. More...

static time_t	gettime_t (const frameType frame)
	Converts a frame number to a time_t in UTC. More...

static std::string	getTimeString (int precision=0)
	Get time of day string for current time. More...

static std::string	getTimeString (double mjd, int precision=0)
	Get time of day string for specified time. More...

static std::string	getTimeString (frameType frame, int precision=0)
	Get time of day for given frame as a string. More...

static double	MJD ()
	Get current MJD. More...

static double	MJD (frameType frame)
	Get MJD for a given frame count. More...

static double	timespec2MJD (const struct timespec ts)
	Converts absolute time specified as a ::timespec to an MJD. More...

static double	timeval2MJD (const struct::timeval &abstimeval)
	Converts absolute time specified as a ::timeval to an MJD. More...

Static Public Attributes
static const double	FRAMES_PER_DAY
	The number of half-second frames per day. More...

static const double	JD2000 = 2451544.5
	The JD (Julian Data) for 2000.0 as a convenience. More...

static const double	MICROSECONDS_PER_DAY
	The number of milliseconds per day. More...

static const double	MILLISECONDS_PER_DAY
	The number of microseconds per day. More...

static const double	MINUTES_PER_DAY
	The number of minutes per day. More...

static const double	MJD1970 = 40587.0
	The MJD for 1970.0. More...

static const double	MJD2000 = 51544.0
	The MJD for 2000.0. More...

static const double	SECONDS_PER_DAY = 86400.0
	The number of seconds per day. More...

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (::std::ostream &os, const carma::util::Time &time)
	Insert (i.e. output) a presentation of the current time from an instance of carma::util::Time into an output stream. More...

Detailed Description

This class deals primarily with Frames and Times.

Half-second Frames are used for monitor and data collection and are aligned with absolute time. The time of a Frame refers to the start time of the data contained in the frame. Frames are counted as integers starting from 00:00:00 UTC, Jan 1, 2000. Times are expressed as doubles in units of days with a reference system of Modified Julian Daynumber (MJD), which is aligned with UTC. When any of the "get" methods are called without an explicit time or frame argument, the current time is gotten with the accuracy determined by the OS.

Note:
1) Frames are integers and our Time is a double. As with any integer/real conversion, care must be taken when converting. There are methods for converting with rounding and with truncation. The programmer must make an intelligent choice based on the circumstances of the conversion. 2) Frames, along with civil time, have a discontinuity at leap seconds. When these events occur (approx every year and half), the suggested action is to stop observing shortly before the leap second, have a celebratory drink to the God of Time, reset your clock if necessary, and then resume observing.
3) The string output of time is essential for debugging this class but can be used whenever the format is suitable. It does not include the century and is not Y2K compliant, a defect that is accepted in exchange for brevity. The FITS formatted time and date strings are Y2K compliant. The FITS format is also known as ISO 8601. Formatted time output is a broad topic and this class does not attempt to provide a general solution. If you develop a new format you are encouraged to incorporate it into this class.If a number of new formats are developed simultaneously, then a new class (FormattedTime?) might be useful. 4) The abbreviations "MJD" and "FITS" will be used in the code as a commonly accepted term in our field. 5) This class contains no state.

Todo:: Write method to interpret date/time string back to an MJD (see STL time_get).

Definition at line 74 of file Time.h.

Member Enumeration Documentation

enum carma::util::Time::TimeZone

enumeration for defining timezones

Definition at line 80 of file Time.h.

Constructor & Destructor Documentation

carma::util::Time::Time ( )

Default constructor.

carma::util::Time::Time ( double mjd )

Create a Time object with given mjd.

virtual carma::util::Time::~Time ( )

virtual

Destructor.

Member Function Documentation

static frameType carma::util::Time::computeClosestFrame ( )

static

Get integral half-second frame that is closest to current time.

Returns: half-second frame count, since 2000, closest to current time

See Also: computeCurrentFrame

static frameType carma::util::Time::computeClosestFrame ( double mjd )

static

Get closest integral half-second frame since 2000 to requested time.

Parameters

mjd	requested date/time as Modified Julian Daynumber

See Also: computeCurrentFrame

static frameType carma::util::Time::computeClosestFrame	(	const std::string &	date,
		const std::string &	format = `"%Y %b %d %H:%M:%S"`,
		const TimeZone	tz = `LOCAL`
	)

static

Get the closest integral half-second frame since 2000 to the input date string.

The timezone is defaulted to be the local timezone

Parameters

date	The date string specified in a format identifiable with a Unix date format string.
format	The date string in a Unix format. Default is format used by syslog plus the year (Y b %2d H:M:S).
tz	The time zone, defined by the enum Time::TimeZone, that "date" is in (not the time zone that you're currently in)

See Also: date(1), strptime(3)

Returns: the frame count closest to the input date, or zero if the date was not parsable for some reason.

static frameType carma::util::Time::computeCurrentFrame ( )

static

Get integral half-second frame since 2000, rounded down.

BEWARE: this truncation will probably not give what is desired if the MJD is just a smidgen below the frame (which is the case if it originally came from a frame).

See Also: computeClosestFrame

static frameType carma::util::Time::computeFrame ( double mjd )

static

Get integral half-second frame since 2000 for requested time, rounded down.

BEWARE: this truncation will probably not give what is desired if the MJD is just a smidgen below the frame (which is the case if it originally came from a frame).

Parameters

mjd	requested date/time as Modified Julian Daynumber

See Also: computeCurrentFrame; computeClosestFrame

static double carma::util::Time::computeFrameTimeDiff	(	frameType	frame,
		double	delay = `0`
	)

static

Get time difference of current time to the delayed frame.

Parameters

frame	number (number of half-seconds since J2000)
delay	in seconds after next half-second frame; default=0

Returns: time difference (now -[frame + delay]), in seconds

static double carma::util::Time::computeMJD ( time_t seconds )

static

Compute the MJD of the Unix-style seconds since 1970.

Parameters

seconds the seconds since January 1, 1970, as from ctime().

Returns: the MJD equivalent of seconds.

static double carma::util::Time::computeMJD	(	const std::string &	date,
		const std::string &	format = `"%Y %b %d %H:%M:%S"`,
		const TimeZone	tz = `LOCAL`
	)

static

Get the MJD given the input date string.

The timezone is assumed to be the local timezone.

Parameters

date	The date string specified in a format identifiable with a Unix date format string.
format	The date string in a Unix format. Default is format used by syslog plus the year (Y b %2d H:M:S).
tz	The time zone, defined by the enum Time::TimeZone, that "date" is in (not the time zone that you're currently in)

See Also: date(1), strptime(3)

Returns: the MJD closest to the input date, or zero if the date was not parsable for some reason.

static double carma::util::Time::computeTimeToFrame	(	frameType	frame,
		double	delay = `0`
	)

static

Get time from now to a specific frame with a delay after the frame.

Parameters

frame	number (number of half-seconds since 2000)
delay	in seconds after next half-second frame; default=0

Returns: time until next frame + delay, in seconds

static double carma::util::Time::computeTimeToNextFrame ( double delay = 0 )

static

Get time to next frame (half-second) with a delay after the frame.

This uses the current time from the OS.

Parameters

delay in seconds after next half-second frame; default=0

Returns: time until next frame + delay, in seconds

static int carma::util::Time::diffHrsFromGmt	(	const struct tm	myTime,
		const time_t	secondsSince1970
	)

static

Utility for obtaining GMT from a local time with faster performance.

About a 3x speedup over getGmtFromLmt, which adds up in a loop over thousands calls (e.g. filling a FluxCatalog from FluxSource.cat)

Parameters

myTime	tm struct giving time in local time zone.
secondsSince1970	- return from a call to mktime(&myTime) Note the call is not made from within this method for performance reasons as methods which call this method have to call mktime anyway.

Returns: the number of hours between local time and gmt

static std::string carma::util::Time::getDateString ( const std::string & dateFormat = "%d%b%y" )

static

Get date string for current time.

Parameters

dateFormat format that the date will be returned (see date(1))

Returns: string containing the date in specified dateFormat

static std::string carma::util::Time::getDateString	(	double	mjd,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date string for specified time.

Parameters

mjd	specified time as a Modified Julian Daynumber
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the date in specified dateFormat

static std::string carma::util::Time::getDateString	(	frameType	frame,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date for given frame as a string.

Parameters

frame	number (number of half-seconds since J2000)
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the date in specified dateFormat

static std::string carma::util::Time::getDateString	(	int	imjd,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date for given MJD day as a string.

Parameters

imjd	day number
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the date in specified dateFormat

static std::string carma::util::Time::getDateTimeString	(	int	precision = `0`,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date and time of day string for current time.

Parameters

precision	digits to the right of the decimal for seconds
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the MJD date and time format is dateFormat hh:mm:ss.ss using a 24 hour clock for the hours.

static std::string carma::util::Time::getDateTimeString	(	frameType	frame,
		int	precision = `0`,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date and time of day string for given frame.

Parameters

frame	number (number of half-seconds since J2000)
precision	digits to the right of the decimal for seconds
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the MJD date and time format is dateFormat hh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static std::string carma::util::Time::getDateTimeString	(	double	mjd,
		int	precision = `0`,
		const std::string &	dateFormat = `"%d%b%y"`
	)

static

Get date and time of day string for specified time.

Parameters

mjd	specified time as a Modified Julian Daynumber
precision	digits to the right of the decimal for seconds
dateFormat	format that the date will be returned (see `date(1)`)

Returns: string containing the MJD date and time format is dateFormat hh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static std::string carma::util::Time::getFITSdateString ( )

static

Get date string for current time in FITS notation.

Returns: string containing the date, format yyyy-mm-dd, e.g. 2003-03-27

static std::string carma::util::Time::getFITSdateString ( int imjd )

static

Get date string for specified day.

Parameters

imjd	specified time as an integer Modified Julian Daynumber

Returns: string containing the date, format yyyy-mm-dd

static std::string carma::util::Time::getFITSdateString ( double mjd )

static

Get date string for specified time.

Parameters

mjd	specified time as a Modified Julian Daynumber

Returns: string containing the date, format yyyy-mm-dd

static std::string carma::util::Time::getFITSdateString ( frameType frame )

static

Get date for given frame as a string.

Parameters

frame number (number of half-seconds since J2000)

Returns: string containing the date, format yyyy-mm-dd

static std::string carma::util::Time::getFITSdateTimeString ( int precision = 0 )

static

Get FITS style date and time of day string for current time.

Parameters

precision digits to the right of the decimal for seconds

Returns: string containing the MJD date and time format is yyyy-dd-mmThh:mm:ss.ss using a 24 hour clock for the hours.

static std::string carma::util::Time::getFITSdateTimeString	(	double	mjd,
		int	precision = `0`
	)

static

Get FITS style date and time of day string for specified time.

Parameters

mjd	specified time as a Modified Julian Daynumber
precision	digits to the right of the decimal for seconds

Returns: string containing the MJD date and time format is yyyy-mm-ddThh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static std::string carma::util::Time::getFITSdateTimeString	(	frameType	frame,
		int	precision = `0`
	)

static

Get FITS style date and time of day string for given frame.

Parameters

frame	number (number of half-seconds since J2000)
precision	digits to the right of the decimal for seconds

Returns: string containing the MJD date and time format is yyyy-mm-ddThh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static struct tm carma::util::Time::getGmtFromLmt	(	const std::string &	date,
		const std::string &	format,
		const Time::TimeZone	tz
	)

static

Utility for obtaining GMT from a local time Note:This is expensive.

Use diffHrsFromGmt if performance is an issue.

::std::string carma::util::Time::getNonBuggyByDesignDateTimeString	(	double	mjd,
		const ::std::string &	dateFormat
	)

static

Get date and time of day string for current time.

Parameters

dateFormat format that the date will be returned (see date(1))

Returns: string containing the MJD date and time format is what ever is specifyed in strftime format

double carma::util::Time::getStoredMJD ( ) const

Return stored MJD.

static time_t carma::util::Time::gettime_t ( const frameType frame )

static

Converts a frame number to a time_t in UTC.

static std::string carma::util::Time::getTimeString ( int precision = 0 )

static

Get time of day string for current time.

Parameters

precision digits to the right of the decimal for seconds

Returns: string containing the UT time of day (no date) format is hh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static std::string carma::util::Time::getTimeString	(	double	mjd,
		int	precision = `0`
	)

static

Get time of day string for specified time.

Parameters

mjd	specified time as a Modified Julian Daynumber
precision	digits to the right of the decimal for seconds

Returns: string containing the UT time of day (no date) format is hh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static std::string carma::util::Time::getTimeString	(	frameType	frame,
		int	precision = `0`
	)

static

Get time of day for given frame as a string.

Parameters

frame	number (number of half-seconds since J2000)
precision	digits to the right of the decimal for seconds

Returns: string containing the MJD time of day (no date) format is hh:mm:ss.ss using a 24 hour clock for the hours.

Exceptions

ErrorException if precision < 0 or > 10

static double carma::util::Time::MJD ( )

static

Get current MJD.

Returns: current MJD

static double carma::util::Time::MJD ( frameType frame )

static

Get MJD for a given frame count.

Note that is a real representation of a linear conversion of an integer. It will be very close, but subject to the limitations of real numbers.

Parameters

frame count to convert to MJD

Returns: an MJD for the input frame

static double carma::util::Time::timespec2MJD ( const struct timespec ts )

static

Converts absolute time specified as a ::timespec to an MJD.

NOTE - timespec assumed to contain absolute time, not some difference.

Parameters

ts	const struct timespec structure with abs time specified in seconds and nanoseconds from the Epoch

Returns: the MJD equivalent of abs time specified in timespec struct.

static double carma::util::Time::timeval2MJD ( const struct::timeval & abstimeval )

static

Converts absolute time specified as a ::timeval to an MJD.

Parameters

tv	const struct timeval structure with abs time specified in seconds and nanoseconds from the Epoch.

Returns: the MJD equivalent of abs time specified in timespec struct.

Friends And Related Function Documentation

std::ostream & operator<<	(	::std::ostream &	os,
		const carma::util::Time &	time
	)

The precision with which the seconds field is presented is determined by the precision of the stream. Hence, usage like this:

* ::std::cout << ::std::setprecision( 2 ) << myTime << ::std::endl;

*

would produce output that looks like this:

* 12:04:23.43

*

Parameters

os	The output stream to insert the presentation into.
time	The carma::util::Time instance to get the current time from.

Returns: The os output stream parameter so that stream insertions can be chained in the usual C++ way (as shown in the example).

Member Data Documentation

const double carma::util::Time::FRAMES_PER_DAY

static

The number of half-second frames per day.

Definition at line 515 of file Time.h.

const double carma::util::Time::JD2000 = 2451544.5

static

The JD (Julian Data) for 2000.0 as a convenience.

Definition at line 487 of file Time.h.

const double carma::util::Time::MICROSECONDS_PER_DAY

static

The number of milliseconds per day.

Definition at line 509 of file Time.h.

const double carma::util::Time::MILLISECONDS_PER_DAY

static

The number of microseconds per day.

Definition at line 503 of file Time.h.

const double carma::util::Time::MINUTES_PER_DAY

static

The number of minutes per day.

Definition at line 497 of file Time.h.

const double carma::util::Time::MJD1970 = 40587.0

static

The MJD for 1970.0.

Definition at line 476 of file Time.h.

const double carma::util::Time::MJD2000 = 51544.0

static

The MJD for 2000.0.

Definition at line 481 of file Time.h.

const double carma::util::Time::SECONDS_PER_DAY = 86400.0

static

The number of seconds per day.

Definition at line 492 of file Time.h.

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

carma/util/Time.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation