Perform time conversions. This is the main class you will need. More...

#include <LocalTimeRK.h>

Public Types
enum class	Position { BEFORE_DST , IN_DST , AFTER_DST , BEFORE_STANDARD , IN_STANDARD , AFTER_STANDARD , NO_DST }
	Whether the specified time is DST or not. See also isDST(). More...

Public Member Functions
LocalTimeConvert &	withConfig (LocalTimePosixTimezone config)
	Sets the timezone configuration to use for time conversion. More...

LocalTimeConvert &	withTime (time_t time)
	Sets the UTC time to begin conversion from. More...

LocalTimeConvert &	withCurrentTime ()
	Use the current time as the time to start with. More...

void	convert ()
	Do the time conversion. More...

bool	isDST () const
	Returns true if the current time is in daylight saving time.

bool	isStandardTime () const
	Returns true of the current time in in standard time.

void	addSeconds (int seconds)
	Adds a number of seconds to the current object. More...

void	nextMinuteMultiple (int increment, int startingModulo=0)
	Moves the current time the next specified multiple of minutes. More...

void	nextTime (LocalTimeHMS hms)
	Moves the current time the next specified local time. This could be today or tomorrow. More...

void	nextTimeList (std::initializer_list< LocalTimeHMS > hmsList)
	Moves the current time the closest local time om hmsList. This could be today or tomorrow. More...

void	nextDay (LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the current time to the next day. More...

void	nextDayOrTimeChange (LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the current to the next day, or right after the next time change, whichever comes first. More...

bool	nextDayOfWeek (int dayOfWeek, LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the current time to the next of the specified day of week. More...

void	nextWeekday (LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Returns the next day that is a weekday (Monday - Friday) More...

void	nextWeekendDay (LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Returns the next day that is a weekend day (Saturday or Sunday) More...

bool	nextDayOfMonth (int dayOfMonth, LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the date and time (local time) forward to the specified day of month and local time. More...

bool	nextDayOfNextMonth (int dayOfMonth, LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the date and time (local time) forward to the specified day of month and local time. More...

bool	nextDayOfWeekOrdinal (int dayOfWeek, int ordinal, LocalTimeHMS hms=LocalTimeIgnoreHMS())
	Moves the date and time (local time) forward to the specified day of month and local time. More...

void	nextLocalTime (LocalTimeHMS hms)
	Sets the time to the nearest hms in local time in the future. More...

bool	nextSchedule (const LocalTimeSchedule &schedule)
	Sets the time to the nearest scheduled time in the future base on the schedule. More...

void	atLocalTime (LocalTimeHMS hms)
	Changes the time of day to the specified hms in local time on the same local day. More...

LocalTimeHMS	getLocalTimeHMS () const
	Get the value of this object as a LocalTimeHMS (hour minute second) More...

LocalTimeYMD	getLocalTimeYMD () const
	Get the value of this object as a LocalTimeYMD (year month day0) More...

String	timeStr ()
	Works like Time.timeStr() to generate a readable string of the local time. More...

String	format (const char *formatSpec)
	Works like Time.format() More...

String	zoneName () const
	Returns the abbreviated time zone name for the current time. More...

int	lastDayOfMonth () const
	Returns the last day of the month, local time (based on localTimeValue)

Data Fields
Position	position = Position::NO_DST
	Where time is relative to DST.

LocalTimePosixTimezone	config
	Timezone configuration for this time conversion. More...

time_t	time
	The time that is being converted. This is always Unix time at UTC. More...

LocalTimeValue	localTimeValue
	The local time that corresponds to time. More...

time_t	dstStart
	The time that daylight saving starts, Unix time, UTC. More...

struct tm	dstStartTimeInfo
	The struct tm that corresponds to dstStart (UTC)

time_t	standardStart
	The time that standard time starts, Unix time, UTC. More...

struct tm	standardStartTimeInfo
	The struct tm that corresponds to standardStart (UTC)

Detailed Description

Perform time conversions. This is the main class you will need.

Member Enumeration Documentation

◆ Position

enum class LocalTimeConvert::Position

strong

Whether the specified time is DST or not. See also isDST().

Enumerator
BEFORE_DST	This time is before the start of DST (northern hemisphere)
IN_DST	This time is in daylight saving time (northern hemisphere)
AFTER_DST	This time is after the end of DST (northern hemisphere)
BEFORE_STANDARD	This time is before the start of standard time (southern hemisphere)
IN_STANDARD	This time is in standard saving time (southern hemisphere)
AFTER_STANDARD	This time is after the end of standard time (southern hemisphere)
NO_DST	This config does not use daylight saving.

Member Function Documentation

◆ addSeconds()

void LocalTimeConvert::addSeconds ( int seconds )

Adds a number of seconds to the current object.

Parameters

seconds

◆ atLocalTime()

void LocalTimeConvert::atLocalTime ( LocalTimeHMS hms )

Changes the time of day to the specified hms in local time on the same local day.

Parameters

hms	A LocalTimeHMS object with hour, minute, and second

You can use the string constructor like this to set the time to 2:00 PM local time.

converter.atLocalTime(LocalTimeHms("14:00:00"));

It's possible that this will set the time to a time earlier than the object's current time. To only set a time in the future, use nextLocalTime() instead.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ convert()

void LocalTimeConvert::convert ( )

Do the time conversion.

You must call this after changing the configuration or the time using withTime() or withCurrentTime()

◆ format()

String LocalTimeConvert::format ( const char * formatSpec )

Works like Time.format()

Parameters

formatSpec the format specifies, which can be

TIME_FORMAT_DEFAULT (example: "Thu Apr 1 12:00:00 2021")
TIME_FORMAT_ISO8601_FULL (example: "2021-04-01T12:00:00-04:00")
custom format based on strftime()

There are many options to strftime described here: https://www.cplusplus.com/reference/ctime/strftime/?kw=strftime

Unlike Time.format(), you can use Z to output the timezone abbreviation, for example "EDT" for the Eastern United States, daylight saving instead of -04:00.

The z formatting matches that of Time.format(), which is wrong. The correct output should be "-400" but the output will be "-04:00" for compatibility.

◆ getLocalTimeHMS()

LocalTimeHMS LocalTimeConvert::getLocalTimeHMS ( ) const

inline

Get the value of this object as a LocalTimeHMS (hour minute second)

Returns: LocalTimeHMS

◆ getLocalTimeYMD()

LocalTimeYMD LocalTimeConvert::getLocalTimeYMD ( ) const

inline

Get the value of this object as a LocalTimeYMD (year month day0)

Returns: LocalTimeYMD

◆ nextDay()

void LocalTimeConvert::nextDay ( LocalTimeHMS hms = LocalTimeIgnoreHMS() )

Moves the current time to the next day.

Parameters

hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextDayOfMonth()

bool LocalTimeConvert::nextDayOfMonth	(	int	dayOfMonth,
		LocalTimeHMS	hms = `LocalTimeIgnoreHMS()`
	)

Moves the date and time (local time) forward to the specified day of month and local time.

Parameters

dayOfMonth	The day of the month (1 = first day of the month). See also special cases below.
hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

This version will move to the closest forward time. It could be as close as 1 second later, but it will always advance at least once second. It could be as much as 1 month minus 1 second later.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

dayOfMonth is normally a a day number (1 = first day of the month). There are also special cases: 0 = the last day of the month, -1 the second to last day of month, ... The number of days in the month are based on the date in local time.

◆ nextDayOfNextMonth()

bool LocalTimeConvert::nextDayOfNextMonth	(	int	dayOfMonth,
		LocalTimeHMS	hms = `LocalTimeIgnoreHMS()`
	)

Moves the date and time (local time) forward to the specified day of month and local time.

Parameters

dayOfMonth	The day of the month (1 = first day of the month). See also special cases below.
hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

This version always picks the next month, even if the target day of month hasn't been reached in this month yet. This will always more forward at least a month, and may be as much as two months minus one day.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

dayOfMonth is normally a a day number (1 = first day of the month). There are also special cases: 0 = the last day of the month, -1 the second to last day of month, ... The number of days in the month are based on the date in local time.

◆ nextDayOfWeek()

bool LocalTimeConvert::nextDayOfWeek	(	int	dayOfWeek,
		LocalTimeHMS	hms = `LocalTimeIgnoreHMS()`
	)

Moves the current time to the next of the specified day of week.

Parameters

dayOfWeek	The day of week (0 - 6, 0 = Sunday, 1 = Monday, ..., 6 = Saturday)
hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextDayOfWeekOrdinal()

bool LocalTimeConvert::nextDayOfWeekOrdinal	(	int	dayOfWeek,
		int	ordinal,
		LocalTimeHMS	hms = `LocalTimeIgnoreHMS()`
	)

Moves the date and time (local time) forward to the specified day of month and local time.

Parameters

dayOfWeek	The day of week (0 - 6, 0 = Sunday, 1 = Monday, ..., 6 = Saturday)
ordinal	1 = first of that day of week in month, 2 = second, ...
hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

If you specify an ordinal that does not exist (for example, there may not be a 5th ordinal for certain days in certain months), returns false and leaves the date unchanged.

Upon successful completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextDayOrTimeChange()

void LocalTimeConvert::nextDayOrTimeChange ( LocalTimeHMS hms = LocalTimeIgnoreHMS() )

Moves the current to the next day, or right after the next time change, whichever comes first.

Parameters

hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

This method is used when you want to synchronize an external device clock daily to keep it synchronized, or right after a time change.

Do not pick the local time of the time change as the hms time! For example, in the United State do not select 02:00:00. The reason is that on spring forward, that time doesn't actually exist, because as soon as the clock hits 02:00:00 it jumps forward to 03:00:00 local time. Picking 03:00:00 or really any other time that's not between 02:00:00 and 02:59:59 is fine. During fall back, even though you've picked the time sync time to be 03:00 local time it will sync at the time of the actual time change correctly, which is why this function is different than nextDay().

◆ nextLocalTime()

void LocalTimeConvert::nextLocalTime ( LocalTimeHMS hms )

Sets the time to the nearest hms in local time in the future.

Parameters

hms	The time of day to set in local time

Moves the time forward to the next instance of hms in local time. If hms has not occurred yet, it will select the one today, but it will always move the time forward.

There is a weird special case on the beginning of daylight saving (spring forward in the northern hemisphere). If you select a hms between 2:00 AM and 2:59:59 AM local time, this time does not exist on spring forward day because it's the hour that is skipped. In order to preserve the requirement that the time will always be advanced by this call, it will jump forward to the next day when the 2:00 hour occurs next. (The hour may be different in other locations, for example it's 1:00 AM in the UK.)

In the case of fall back, if you specify a hms in the repeated hour (1:00:00 to 1:59:59) the time returned will be the second time this time occurs, in standard time in the US.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextMinuteMultiple()

void LocalTimeConvert::nextMinuteMultiple	(	int	increment,
		int	startingModulo = `0`
	)

Moves the current time the next specified multiple of minutes.

Parameters

increment	Typically something like 5, 15, 20, 30 that 60 is evenly divisible by
startingModulo	(optional). If present, must be 0 < startingModulo < increment

Moves the time forward to the next multiple of that number of minutes. For example, if the clock is at :10 past the hour and the multiple is 15, then time will be updated to :15. If the time is equal to an even multple, the next multiple is selected.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextSchedule()

bool LocalTimeConvert::nextSchedule ( const LocalTimeSchedule & schedule )

Sets the time to the nearest scheduled time in the future base on the schedule.

Parameters

schedule

◆ nextTime()

void LocalTimeConvert::nextTime ( LocalTimeHMS hms )

Moves the current time the next specified local time. This could be today or tomorrow.

Parameters

hms	Moves to the next occurrence of that time of day (local time)

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextTimeList()

void LocalTimeConvert::nextTimeList ( std::initializer_list< LocalTimeHMS > hmsList )

Moves the current time the closest local time om hmsList. This could be today or tomorrow.

Parameters

hmsList An initialize list of LocalTimeHMS surrounded by {}

For example, this sets the time to the nearest noon or midnight local time greater than the time set in this object:

conv.nextTimeList({LocalTimeHMS("00:00"), LocalTimeHMS("12:00")});

◆ nextWeekday()

void LocalTimeConvert::nextWeekday ( LocalTimeHMS hms = LocalTimeIgnoreHMS() )

Returns the next day that is a weekday (Monday - Friday)

Parameters

hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ nextWeekendDay()

void LocalTimeConvert::nextWeekendDay ( LocalTimeHMS hms = LocalTimeIgnoreHMS() )

Returns the next day that is a weekend day (Saturday or Sunday)

Parameters

hms	If specified, moves to that time of day (local time). If omitted, leaves the current time and only changes the date.

Upon completion, all fields are updated appropriately. For example:

time specifies the time_t of the new time at UTC
localTimeValue contains the broken-out values for the local time
isDST() return true if the new time is in daylight saving time

◆ timeStr()

String LocalTimeConvert::timeStr ( )

Works like Time.timeStr() to generate a readable string of the local time.

Uses asctime formatting, which looks like "Fri Jan 1 18:45:56 2021". The strings are not localized; they're always in English.

◆ withConfig()

LocalTimeConvert & LocalTimeConvert::withConfig ( LocalTimePosixTimezone config )

inline

Sets the timezone configuration to use for time conversion.

If you do not use withConfig() the global default set in the LocalTime class is used. If neither are set, the local time is UTC (with no DST).

◆ withCurrentTime()

LocalTimeConvert & LocalTimeConvert::withCurrentTime ( )

inline

Use the current time as the time to start with.

This does not start the conversion; you must also call the convert() method after setting all of the settings you want to use.

◆ withTime()

LocalTimeConvert & LocalTimeConvert::withTime ( time_t time )

inline

Sets the UTC time to begin conversion from.

Parameters

time	The time (UTC) to set. This is the Unix timestamp (seconds since January 1, 1970) UTC such as returned by Time.now().

This does not start the conversion; you must also call the convert() method after setting all of the settings you want to use.

For the current time, you can instead use withCurrentTime();

◆ zoneName()

String LocalTimeConvert::zoneName ( ) const

Returns the abbreviated time zone name for the current time.

For example, for the United States east coast, EST or EDT depending on whether the current time is DST or not. See also isDST().

This string comes from the LocalTimePosixTimezone object.

Field Documentation

◆ config

LocalTimePosixTimezone LocalTimeConvert::config

Timezone configuration for this time conversion.

If you don't specify this using withConfig then the global setting is retrieved from the LocalTime singleton instance.

◆ dstStart

time_t LocalTimeConvert::dstStart

The time that daylight saving starts, Unix time, UTC.

The config specifies the rule (2nd Sunday in March, for example), and the local time that the change occurs. This is the UTC value that corresponds to that rule in the year specified by time.

Note in the southern hemisphere, dstStart is after standardStart.

◆ localTimeValue

LocalTimeValue LocalTimeConvert::localTimeValue

The local time that corresponds to time.

The convert() method sets this, as do methods like nextDay(). The local time will depend on the timezone set in config, as well as the date which will determine whether it's daylight saving or not.

◆ standardStart

time_t LocalTimeConvert::standardStart

The time that standard time starts, Unix time, UTC.

The config specifies the rule (1st Sunday in November, for example), and the local time that the change occurs. This is the UTC value that corresponds to that rule in the year specified by time.

Note in the southern hemisphere, dstStart is after standardStart.

◆ time

time_t LocalTimeConvert::time

The time that is being converted. This is always Unix time at UTC.

Seconds after January 1, 1970, UTC. Using methods like nextDay() increment this value.

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

src/LocalTimeRK.h
src/LocalTimeRK.cpp

Public Types

Public Member Functions

Data Fields

Detailed Description

Member Enumeration Documentation

◆ Position

Member Function Documentation

◆ addSeconds()

◆ atLocalTime()

◆ convert()

◆ format()

◆ getLocalTimeHMS()

◆ getLocalTimeYMD()

◆ nextDay()

◆ nextDayOfMonth()

◆ nextDayOfNextMonth()

◆ nextDayOfWeek()

◆ nextDayOfWeekOrdinal()

◆ nextDayOrTimeChange()

◆ nextLocalTime()

◆ nextMinuteMultiple()

◆ nextSchedule()

◆ nextTime()

◆ nextTimeList()

◆ nextWeekday()

◆ nextWeekendDay()

◆ timeStr()

◆ withConfig()

◆ withCurrentTime()

◆ withTime()

◆ zoneName()

Field Documentation

◆ config

◆ dstStart

◆ localTimeValue

◆ standardStart

◆ time