See Quick start guide for Calendar service.

This is the common API for a calendar service. It provides functionality to convert UNIX timestamps to dates and back. It also provides functionality for calculating the difference between dates and converting timestamps to dates with different time zones and back.

Note: This module is a pure software module, and does not interface hardware calendar peripherals (e.g. the AST on UC3L)

Modules
	Related Project(s)
	In this section you can find all the projects related to the Calendar service.

	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the Calendar service.

Data Structures
struct	calendar_date
	Calendar structure to hold a date. More...

Functions
void	calendar_add_second_to_date (struct calendar_date *date)
	Increments a date with one second. More...

uint32_t	calendar_date_to_timestamp (struct calendar_date *date)
	Convert a date to a UNIX timestamp. More...

uint32_t	calendar_date_to_timestamp_tz (struct calendar_date *date, int8_t hour, uint8_t min)
	This function converts a date in a given time zone to a UNIX timestamp. More...

bool	calendar_is_date_valid (struct calendar_date *date)
	Check if a date is valid. More...

void	calendar_time_between_dates (struct calendar_date date_end, struct calendar_date date_start, struct calendar_date *date_out)
	This function calculates the time difference between to dates. More...

void	calendar_timestamp_to_date (uint32_t timestamp, struct calendar_date *date_out)
	Convert a UNIX timestamp to a date. More...

void	calendar_timestamp_to_date_tz (uint32_t timestamp, int8_t hour, uint8_t min, struct calendar_date *date_out)
	Convert a UNIX timestamp to a date in a given time zone. More...

void calendar_add_second_to_date ( struct calendar_date * date )

Increments a date with one second.

This function will add one second to specified date. If second is 59, it will increment minute.

Parameters

date	The date to add a second to

References Assert, calendar_add_minute_to_date(), calendar_is_date_valid(), and calendar_date::second.

Referenced by run_add_second_to_end_feb_test(), run_add_second_to_end_of_day_test(), run_add_second_to_end_of_year_test(), run_add_second_to_leap_year_feb2_test(), run_add_second_to_leap_year_feb_test(), and run_add_second_to_normal_date_test().

uint32_t calendar_date_to_timestamp ( struct calendar_date * date )

Convert a date to a UNIX timestamp.

Note: If date is invalid, timestamp 0 will be returned.

Parameters

date Date

Returns: The corresponding UNIX timestamp

Return values

0	if date is not valid

References calendar_is_date_valid(), calendar_leapyear(), calendar_yearsize(), calendar_date::date, EPOCH_YEAR, calendar_date::hour, calendar_date::minute, month, calendar_date::month, calendar_date::second, SECS_PER_DAY, SECS_PER_HOUR, SECS_PER_MINUTE, and calendar_date::year.

Referenced by calendar_date_to_timestamp_tz(), calendar_time_between_dates(), main(), run_date_1855_to_timestamp_test(), run_date_2107_to_timestamp_test(), run_date_to_timestamp_0_test(), run_date_to_timestamp_test(), run_erronous_date_to_timestamp_test(), run_erronous_time_to_timestamp_test(), and run_leap_year_date_to_timestamp_test().

uint32_t calendar_date_to_timestamp_tz	(	struct calendar_date *	date,
		int8_t	hour,
		uint8_t	min
	)

This function converts a date in a given time zone to a UNIX timestamp.

Note: If date is invalid, timestamp 0 will be returned.

Parameters

date	Date
hour	Hour offset from UTC (UTC-12 to UTC+14)
min	Minute offset from UTC (0, 15, 30, 45)

Returns: The corresponding UNIX timestamp

Return values

0	if date is not valid

References calendar_date_to_timestamp(), SECS_PER_HOUR, and SECS_PER_MINUTE.

bool calendar_is_date_valid ( struct calendar_date * date )

Check if a date is valid.

Checks that number of seconds, minutes and hours is a valid value. Checks that number of days does not exceed number of days in current month. Checks that number of months is a valid value, and checks that year is between 1970 (epoch year) and 2106 (overflow year).

Parameters

*date the date to check if valid

References calendar_leapyear(), calendar_date::date, EPOCH_YEAR, calendar_date::hour, calendar_date::minute, month, calendar_date::month, calendar_date::second, and calendar_date::year.

Referenced by calendar_add_second_to_date(), and calendar_date_to_timestamp().

void calendar_time_between_dates	(	struct calendar_date *	date_end,
		struct calendar_date *	date_start,
		struct calendar_date *	date_out
	)

This function calculates the time difference between to dates.

The time difference is provided as number of years, months, days, hours, minutes and seconds between the dates. If end date is before start date, the dates are switched.

Parameters

date_end	The end date
date_start	The start date
date_out	The time between the dates

References calendar_date_to_timestamp(), calendar_leapyear(), calendar_date::date, calendar_date::hour, calendar_date::minute, month, calendar_date::month, calendar_date::second, temp, and calendar_date::year.

Referenced by main(), run_time_between_dates_diff_year_test(), run_time_between_dates_exchanged_test(), run_time_between_dates_leap_year_test(), run_time_between_dates_same_year_test(), run_time_between_dates_years2_test(), and run_time_between_dates_years_test().

void calendar_timestamp_to_date	(	uint32_t	timestamp,
		struct calendar_date *	date_out
	)

Convert a UNIX timestamp to a date.

Finds the corresponding date and time for a UNIX timestamp.

Parameters

timestamp	UNIX timestamp
date_out	Date to store result

References calendar_leapyear(), calendar_yearsize(), calendar_date::date, calendar_date::dayofweek, EPOCH_YEAR, calendar_date::hour, calendar_date::minute, month, calendar_date::month, calendar_date::second, SECS_PER_DAY, SECS_PER_HOUR, SECS_PER_MINUTE, and calendar_date::year.

Referenced by calendar_timestamp_to_date_tz(), get_fattime(), main(), run_time_between_dates_diff_year_test(), run_time_between_dates_exchanged_test(), run_time_between_dates_leap_year_test(), run_time_between_dates_same_year_test(), run_time_between_dates_years2_test(), run_time_between_dates_years_test(), run_timestamp_0_to_date_test(), run_timestamp_to_leap_year_date2_test(), run_timestamp_to_leap_year_date_test(), and run_timestamp_to_normal_date_test().

void calendar_timestamp_to_date_tz	(	uint32_t	timestamp,
		int8_t	hour,
		uint8_t	min,
		struct calendar_date *	date_out
	)

Convert a UNIX timestamp to a date in a given time zone.

The provided UNIX timestamp is converted to the corresponding time in the provided time zone.

Parameters

timestamp	UNIX timestamp
hour	Hour offset from UTC (UTC-12 to UTC+14)
min	Minute offset from UTC (0, 15, 30, 45)
date_out	Date to store result

References calendar_timestamp_to_date(), SECS_PER_HOUR, and SECS_PER_MINUTE.

Microchip® Advanced Software Framework

Modules

Data Structures

Functions