utctime Namespace Reference

Namespace for UTCTime() class and associated functions.

Classes
class	UTCTimeException
	Base exception class. More...
class	bad_time_init
	Thrown when the time cannot be initialized. More...
class	bad_time
	Thrown when the time cannot be obtained. More...
class	invalid_date
	Thrown when an invalid date is provided to the constructor. More...
class	UTCTime

Functions
bool	validate_date (const int year, const int month, const int day, const int hour, const int minute, const int second)
	Checks whether a supplied date is valid.
time_t	get_day_diff ()
	Returns a time_t interval representing one day.
time_t	get_hour_diff ()
	Returns a time_t interval representing one hour.
time_t	get_sec_diff ()
	Returns a time_t interval representing one second.
int	tm_compare (const std::tm &first, const std::tm &second)
	Compares two std::tm structs.
int	tm_intraday_secs_diff (const std::tm &first, const std::tm &second)
	Returns the difference between two std::tm structs.
bool	is_leap_year (const int year)
	Checks if the supplied year is a leap year.
std::tm *	tm_increment_day (std::tm *changing_tm, const int quantity=1)
	Adds one or more days to a std::tm struct.
std::tm *	tm_increment_hour (std::tm *changing_tm, const int quantity=1)
	Adds one or more hours to a std::tm struct.
std::tm *	tm_increment_minute (std::tm *changing_tm, const int quantity=1)
	Adds one or more minutes to a std::tm struct.
std::tm *	tm_increment_second (std::tm *changing_tm, const int quantity=1)
	Adds one or more seconds to a std::tm struct.
std::tm *	tm_decrement_day (std::tm *changing_tm, const int quantity=1)
	Deducts one or more days from a std::tm struct.
std::tm *	tm_decrement_hour (std::tm *changing_tm, const int quantity=1)
	Deducts one or more hours from a std::tm struct.
std::tm *	tm_decrement_minute (std::tm *changing_tm, const int quantity=1)
	Deducts one or more minutes from a std::tm struct.
std::tm *	tm_decrement_second (std::tm *changing_tm, const int quantity=1)
	Deducts one or more seconds from a std::tm struct.
bool	check_utc_timestamp (const time_t check_time, int &secs_diff, const int year, const int month, const int day, const int hour, const int minute, const int second)
	Checks if a UTC timestamp is accurate.
time_t	get_utc_timestamp (const int year, const int month, const int day, const int hour, const int minute, const int second)
	Gets a time_t timestamp for a requested UTC time.
int	get_utc_timestamp_sec_diff (const time_t check_time, const int year, const int month, const int day, const int hour, const int minute, const int second)
	Checks a time_t timestamp against a UTC time.

Function Documentation

bool utctime::check_utc_timestamp	(	const time_t	check_time,
		int &	secs_diff,
		const int	year,
		const int	month,
		const int	day,
		const int	hour,
		const int	minute,
		const int	second
	)

Checks if a UTC timestampe is accurate. A time_t timestamp is computed from the supplied datetime elements, and compared to the supplied time_t timestamp. The difference between the two, in seconds, is stored in the supplied secs_diff argument. This function is needed because the methodology used to calculate a timestamp by this library can sometimes be inaccurate when leap seconds or other unpredictable calendar changes occur. We therefore need a method to check if the returned timestamp is accurate. Other functions provided in this library call this function, so the user should not normally need to call it.

Parameters

check_time	The time_t timestamp to check
secs_diff	Modified to contain the difference, in seconds
year	The year
month	The month, 1 to 12
day	The day, 1 to 31, depending on the month
hour	The hour, 0 to 23
minute	The minute, 0 to 59
second	The second, 0 to 59

Returns

true if the supplied timestamp is accurate, false otherwise

Exceptions

bad_time

if the current time cannot be obtained.

time_t utctime::get_day_diff

(

)

Returns a time_t interval representing one day. The C standard does not define the units in which a time_t value is measured. On POSIX-compliant systems it is measured in seconds, but we cannot assume this for full portability.

Returns

A time_t interval representing one day.

Exceptions

bad_time

if the current time cannot be obtained.

time_t utctime::get_hour_diff

(

)

Returns a time_t interval representing one hour. The C standard does not define the units in which a time_t value is measured. On POSIX-compliant systems it is measured in seconds, but we cannot assume this for full portability.

Returns

A time_t interval representing one hour.

Exceptions

bad_time

if the current time cannot be obtained.

time_t utctime::get_sec_diff

(

)

Returns a time_t interval representing one second. The C standard does not define the units in which a time_t value is measured. On POSIX-compliant systems it is measured in seconds, but we cannot assume this for full portability.

Returns

A time_t interval representing one second.

Exceptions

bad_time

if the current time cannot be obtained.

time_t utctime::get_utc_timestamp	(	const int	year,
		const int	month,
		const int	day,
		const int	hour,
		const int	minute,
		const int	second
	)

Gets a time_t timestamp for a requested UTC time.

Parameters

year	The year
month	The month, 1 to 12
day	The day, 1 to 31, depending on the month
hour	The hour, 0 to 23
minute	The minute, 0 to 59
second	The second, 0 to 59. Leap seconds are not supported.

Returns

A time_t timestamp for the requested UTC time.

Exceptions

bad_time

if the current time cannot be obtained.

int utctime::get_utc_timestamp_sec_diff	(	const time_t	check_time,
		const int	year,
		const int	month,
		const int	day,
		const int	hour,
		const int	minute,
		const int	second
	)

Checks a time_t timestamp against a UTC time, and returns the difference in seconds. This function only returns a good value if the timestamp is less than 24 hours away from the desired time, so the caller is responsible for making sure that it is. This function may also return a bad value if a leap second or other unpredictable calendar change falls between the desired UTC time and the provided time stamp. The result should therefore always be checked with utctime::check_utc_timestamp(), or by calling this function again.

Parameters

check_time	The time_t timestamp to check
year	The year
month	The month, 1 to 12
day	The day, 1 to 31, depending on the month
hour	The hour, 0 to 23
minute	The minute, 0 to 59
second	The second, 0 to 59. Leap seconds are not supported.

Returns

The difference, if any, represented in seconds.

Exceptions

bad_time

if the current time cannot be obtained.

bool utctime::is_leap_year

(

const int

year

)

Checks if the supplied year is a leap year.

Parameters

year

A year

Returns

true is year is a leap year, false otherwise.

int utctime::tm_compare	(	const std::tm &	first,
		const std::tm &	second
	)

Compares two std::tm structs. Only the year, month, day, hour, minute and second are compared. Any timezone or DST information is ignored.

Parameters

first	The first std::tm struct.
second	The second std::tm struct.

Returns

-1 if first is earlier than second, 1 if first is later than second, and 0 if first is equal to second.

std::tm * utctime::tm_decrement_day	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Deducts one or more days from a std::tm struct, decrementing the month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of days to deduct

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_decrement_hour	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Deducts one or more hours from a std::tm struct, decrementing the day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of hours to deduct

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_decrement_minute	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Deducts one or more minutes from a std::tm struct, decrementing the hour, day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of minutes to deduct

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_decrement_second	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Deducts one or more seconds from a std::tm struct, decrementing the minute, hour, day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of seconds to deduct

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_increment_day	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Adds one or more days to a std::tm struct, incrementing the month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of days to add

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_increment_hour	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Adds one or more hours to a std::tm struct, incrementing the day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of hours to add

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_increment_minute	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Adds one or more minutes to a std::tm struct, incrementing the hour, day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of minutes to add

Returns

A pointer to the same std::tm struct.

std::tm * utctime::tm_increment_second	(	std::tm *	changing_tm,
		const int	quantity = 1
	)

Adds one or mor seconds to a std::tm struct, incrementing the minute, hour, day, month and/or the year as necessary.

Parameters

changing_tm	A pointer to the std::tm struct to increment. The struct referred to by the pointer is modified by the function.
quantity	The number of seconds to add

Returns

A pointer to the same std::tm struct.

int utctime::tm_intraday_secs_diff	(	const std::tm &	first,
		const std::tm &	second
	)

Returns the difference between two std::tm structs. The structs are assumed to be within 24 hours of each other, and if they are not, the returned result is computed as if they were. For instance, comparing 10:00 on one day to 14:00 on the next day will yield a difference equivalent to 4 hours, not to 28 hours.

Parameters

first	The first std::tm struct
second	The second std::tm struct

Returns

The difference, in seconds, between the two std::tm structs. The difference is positive if first is earlier than second, and negative if second is earlier than first.

bool utctime::validate_date	(	const int	year,
		const int	month,
		const int	day,
		const int	hour,
		const int	minute,
		const int	second
	)

Checks whether a supplied date is valid.

Parameters

year	The year
month	The month, 1 to 12
day	The day, 1 to 31, depending on the month
hour	The hour, 0 to 23
minute	The minute, 0 to 59
second	The second, 0 to 59. Leap seconds are not supported.

Returns

true if the date if valid.

Exceptions

invalid_date

if the date is not valid.

Todo:

Why does this throw an exception? Why not return false? In order so that the error message can show why it's invalid?