Stores when leap seconds occur to allow conversions between Interstellar Time or TAI and planetary time systems like UTC and POSIX. More...

#include <LeapSeconds.hpp>

Collaboration diagram for duds::time::planetary::LeapSeconds:

[legend]

Public Types
typedef std::map< duds::time::interstellar::SecondTime, duds::time::interstellar::Seconds >	LeapMap
	The data structure used to hold leap seconds. More...

Public Member Functions
	LeapSeconds ()
	Makes a new LeapSeconds object with no leap seconds and a current time as far in the past as possible. More...

	LeapSeconds (const std::string &zoneinfo)
	Makes a new LeapSeconds object and fills it with the leap seconds from the indicated zoneinfo database file. More...

void	add (const duds::time::interstellar::SecondTime leapOn, const duds::time::interstellar::Seconds additional=duds::time::interstellar::Seconds(1))
	Adds new leap second(s) at the given time and adjusts existing records to match. More...

duds::time::interstellar::Seconds	currentUntil () const
	Returns the time when the leap second data may no longer be up to date. More...

LeapBounds	getLeapBounds (const duds::time::interstellar::SecondTime time) const
	Create a LeapBounds object with the data for the time period covered for the given time. More...

shared_ptr< const LeapMap >	leapMap () const
	Returns a new shared pointer to the current map of leap seconds. More...

LeapMap	leapMapCopy () const
	Returns a copy of the current map of leap seconds. More...

duds::time::interstellar::Seconds	leapSeconds (const duds::time::interstellar::SecondTime &when) const
	Returns the sum of all leap seconds in use at the given time. More...

int	readZoneinfo (const std::string &zoneinfo)
	Reads the indicated zoneinfo database file. More...

void	set (const duds::time::interstellar::SecondTime leapOn, const duds::time::interstellar::Seconds total)
	Makes a new leap second entry. More...

void	setCurrent (const duds::time::interstellar::Seconds when)
	Sets a timestamp for when the leap second information becomes outdated. More...

Private Attributes
duds::general::Spinlock	block
	Used to make access and changes thread-safe. More...

duds::time::interstellar::Seconds	currUntil
	A time stamp indicating when the stored information may be outdated. More...

shared_ptr< LeapMap >	leaps
	The leap seconds. More...

Detailed Description

Stores when leap seconds occur to allow conversions between Interstellar Time or TAI and planetary time systems like UTC and POSIX.

A time indicating when the data will be outdated is also stored; no additional leap seconds should be added until after this time.

Note: This class assumes the leap seconds before the first record is 0. This may not work well for times well in the past.

Todo:: Allow for leap seconds that occur regularly in a more efficent manner. This will be useful to handle all possible cases of days or Sols or whatnot with lengths including fractional seconds when there is an insistance on using a whole number of seconds to describe the period.

Author: Jeff Jackowski

Definition at line 32 of file LeapSeconds.hpp.

Member Typedef Documentation

◆ LeapMap

typedef std::map< duds::time::interstellar::SecondTime, duds::time::interstellar::Seconds > duds::time::planetary::LeapSeconds::LeapMap

The data structure used to hold leap seconds.

The key is the time, and the value is the sum of all leap seconds in use after the time in the key.

Definition at line 42 of file LeapSeconds.hpp.

Constructor & Destructor Documentation

◆ LeapSeconds() [1/2]

duds::time::planetary::LeapSeconds::LeapSeconds ( )

Makes a new LeapSeconds object with no leap seconds and a current time as far in the past as possible.

Definition at line 40 of file LeapSeconds.cpp.

◆ LeapSeconds() [2/2]

duds::time::planetary::LeapSeconds::LeapSeconds ( const std::string & zoneinfo )

Makes a new LeapSeconds object and fills it with the leap seconds from the indicated zoneinfo database file.

readZoneinfo() is called, and any exception it throws is not caught.

Parameters

zoneinfo The zoneinfo database file.

See also: readZoneinfo()

Definition at line 43 of file LeapSeconds.cpp.

Member Function Documentation

◆ add()

void duds::time::planetary::LeapSeconds::add	(	const duds::time::interstellar::SecondTime	leapOn,
		const duds::time::interstellar::Seconds	additional = `duds::time::interstellar::Seconds(1)`
	)

Adds new leap second(s) at the given time and adjusts existing records to match.

Parameters

leapOn	The time when the change of leap seconds will take take place.
additional	The number of leap seconds to add.

Definition at line 101 of file LeapSeconds.cpp.

◆ currentUntil()

duds::time::interstellar::Seconds duds::time::planetary::LeapSeconds::currentUntil ( ) const

Returns the time when the leap second data may no longer be up to date.

This is intended to allow software to tell if the leap second data is current or outdated. Such a check cannot be done using the leap second records since they can occur irregularly.

Definition at line 96 of file LeapSeconds.cpp.

◆ getLeapBounds()

LeapBounds duds::time::planetary::LeapSeconds::getLeapBounds ( const duds::time::interstellar::SecondTime time ) const

Create a LeapBounds object with the data for the time period covered for the given time.

Parameters

time	The time that will be within the bounds of the resulting LeapBounds.

Returns: A new LeapBounds object.

Definition at line 154 of file LeapSeconds.cpp.

Referenced by duds::time::planetary::Earth::addLeapSeconds().

◆ leapMap()

shared_ptr< const LeapSeconds::LeapMap > duds::time::planetary::LeapSeconds::leapMap ( ) const

Returns a new shared pointer to the current map of leap seconds.

This allows inspection of all the leap seconds in a mostly thread-safe manner. To keep it thread-safe, the const modifier must not be violated, and the map object should not be used during a call to add() or set(). readZoneinfo() may be called without breaking thread-safety, but if it succeeds, this object will hold a different LeapMap.

Todo:: Justify the need or remove this function. Maybe quit using a shared pointer, too. Or make a copy in add() and set().

Definition at line 176 of file LeapSeconds.cpp.

◆ leapMapCopy()

LeapSeconds::LeapMap duds::time::planetary::LeapSeconds::leapMapCopy ( ) const

Returns a copy of the current map of leap seconds.

This allows inspection of all leap second records in a thread-safe manner.

Definition at line 181 of file LeapSeconds.cpp.

◆ leapSeconds()

duds::time::interstellar::Seconds duds::time::planetary::LeapSeconds::leapSeconds ( const duds::time::interstellar::SecondTime & when ) const

Returns the sum of all leap seconds in use at the given time.

Parameters

when	The time to inspect for leap seconds.

Definition at line 142 of file LeapSeconds.cpp.

Referenced by duds::time::planetary::Earth::date(), duds::time::planetary::Earth::dateUtcToTai(), duds::time::planetary::Earth::posix(), duds::time::planetary::Earth::posixUtcToTai(), duds::time::planetary::Earth::time(), and duds::time::planetary::Earth::timeUtc().

◆ readZoneinfo()

int duds::time::planetary::LeapSeconds::readZoneinfo ( const std::string & zoneinfo )

Reads the indicated zoneinfo database file.

If successful, the leap second data in this object is replaced with the information from the file. Otherwise, the object's data will not change.

It is assumed that the file is intended for use with timezones on Earth. The files include leap seconds from 1972 onward. However, TAI and UTC had diverged by about 10 seconds before the leap second system was instituted. Prior to that, UTC was either adjusted daily by thosandths of a second, or used a varying definition for a second; I'm not sure which.

To address this situation, the first leap second record is the start of an 11 second difference between TAI and UTC. As a result, times before the very end of 30 June 1972 will be given 0 leap seconds after this function is successful.

Parameters

zoneinfo The zoneinfo database file path. This function works on the binary zoneinfo files that are typically found on Linux systems. The most common zoneinfo files lack leap second information, but those that do contain it typically (always?) have the same leap second data regardless of the described time zone. On Linux, "/usr/share/zoneinfo/right/UTC" (older), "/usr/share/zoneinfo-leaps/UTC", or wherever the distribution puts them, is a good choice.

Returns: The number of leap second records read.

Exceptions

ZoneIoError	Failed to open the file.
ZoneDuplicateLeap	Two leap second records have the same time of occurance.
ZoneTruncated	Fewer leap second records were read than the file claims to have.

Bug:: The current until time (currUntil) is not changed. Is an acceptable time available?

Definition at line 47 of file LeapSeconds.cpp.

Referenced by LeapSeconds().

◆ set()

void duds::time::planetary::LeapSeconds::set	(	const duds::time::interstellar::SecondTime	leapOn,
		const duds::time::interstellar::Seconds	total
	)

Makes a new leap second entry.

Postcondition: The new leap second entry is added, and the existing entries remain unchanged. This means the number of leap seconds applied for all existing time periods will remain the same.

Parameters

leapOn	The time when the leap second is added.
total	The total number of leap seconds up to the point in time in leapOn.

Definition at line 133 of file LeapSeconds.cpp.

◆ setCurrent()

void duds::time::planetary::LeapSeconds::setCurrent ( const duds::time::interstellar::Seconds when )

Sets a timestamp for when the leap second information becomes outdated.

Parameters

when	The time when the data may be outdated. The most correct value to use is one that will assure more leap seconds will not be added until after when.

Definition at line 91 of file LeapSeconds.cpp.

Member Data Documentation

◆ block

duds::general::Spinlock duds::time::planetary::LeapSeconds::block

mutableprivate

Used to make access and changes thread-safe.

Todo:: Consider having functions first get a shared pointrt to leaps and then use that shared pointer rather than the member.

Definition at line 57 of file LeapSeconds.hpp.

Referenced by add(), currentUntil(), getLeapBounds(), leapMap(), leapMapCopy(), leapSeconds(), readZoneinfo(), set(), and setCurrent().

◆ currUntil

duds::time::interstellar::Seconds duds::time::planetary::LeapSeconds::currUntil

private

A time stamp indicating when the stored information may be outdated.

Definition at line 51 of file LeapSeconds.hpp.

Referenced by currentUntil(), and setCurrent().

◆ leaps

shared_ptr<LeapMap> duds::time::planetary::LeapSeconds::leaps

private

The leap seconds.

Definition at line 47 of file LeapSeconds.hpp.

Referenced by add(), getLeapBounds(), leapMap(), leapMapCopy(), leapSeconds(), readZoneinfo(), and set().

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

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ LeapMap

Constructor & Destructor Documentation

◆ LeapSeconds() [1/2]

◆ LeapSeconds() [2/2]

Member Function Documentation

◆ add()

◆ currentUntil()

◆ getLeapBounds()

◆ leapMap()

◆ leapMapCopy()

◆ leapSeconds()

◆ readZoneinfo()

◆ set()

◆ setCurrent()

Member Data Documentation

◆ block

◆ currUntil

◆ leaps