diff --git a/README.md b/README.md index cd4e5cc..8d515a6 100644 --- a/README.md +++ b/README.md @@ -259,7 +259,7 @@ Some functions are not necessarily useful for everyday users of this library, bu I hate documentation that still makes me reach for for the source code, so this manual supplies the function prototype with each function so you can see what types or arguments each function takes and what type the return value is. I took one shortcut though. A lot of functions allow you to specify a time. In the function prototype this looks like: -`time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL` +`time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL` Throughout this manual, we replace these two optional arguments in the function definitions with: @@ -460,11 +460,11 @@ To only get the timezone data from the internet when the cache is empty or outda ### setCache -`bool tz.setCache(const int16_t address)` +`bool tz.setCache(int16_t address)` If your ezTime is compiled with `#define EZTIME_CACHE_EEPROM` (which is the default), you can supply an EEPROM location. A single timezone needs 50 bytes to cache. The data is written in compressed form so that the Olsen and Posix strings fit in 3/4 of the space they would normally take up, and along with it is stored a checksum, a length field and a single byte for the month in which the cache was retrieved, in months after January 2018. -`bool tz.setCache(const String name, const String key)` +`bool tz.setCache(String name, String key)` On ESP32 and possibly other platforms, there is an emulation for the EEPROM in flash, bu there is also a nicer mechanism that stores keys and values in flash. You can use this by enabling `#define EZTIME_CACHE_NVS` in `ezTime.h` You can then supply a section name and a key to serve as the cache storage location for a given timezone. @@ -539,7 +539,7 @@ We'll start with one of the most powerful functions of ezTime. With `dateTime` y So as an example: `UTC.dateTime("l ~t~h~e jS ~o~f F Y, g:i A")` yields date and time in this format: `Saturday the 25th of August 2018, 2:23 PM`. -#  +  ### Built-in date and time formats @@ -617,7 +617,7 @@ Returns the one-letter military code for the timezone. See [here](https://www.ti `uint8_t [tz.]setEvent(void (*function)(), TIME)` -`uint8_t [tz.]setEvent(void (*function)(), const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t mnth, uint16_t yr)` +`uint8_t [tz.]setEvent(void (*function)(), uint8_t hr, uint8_t min, uint8_t sec, uint8_t day, uint8_t mnth, uint16_t yr)` With ezTime, you can set your own events to run at a specified time. Simply run `setEvent` specifying the name of the function you would like to call (without the brackets) and a time you would like to call it. The first time `events` runs and notices that it is at or after the time you specified it will run the event and delete the event. If you want an event to recur, simply set a new event in the function that gets called. You can have a maximum of 8 events by default (easily changed by changing `MAX_EVENTS` in `ezTime.h`). ezTime uses one event internally to trigger the next NTP update. @@ -646,12 +646,16 @@ Buy you can also call `deleteEvent` with the name of the function (again without `void [tz.]setTime(time_t t, uint16_t ms = 0)` -`void [tz.]setTime(const uint8_t hr, const uint8_t min, const uint8_t sec,`
          `const uint8_t day, const uint8_t mnth, uint16_t yr)` +`void [tz.]setTime(uint8_t hr, uint8_t min, uint8_t sec,`
          `uint8_t day, uint8_t mnth, uint16_t yr)` `setTime` pretty much does what it says on the package: it sets the time to the time specified, either as separate elements or as a time_t value in seconds since Jan 1st 1970. If you have another source of time — say, a GPS receiver — you can use `setTime` to set the time in the UTC timezone. Or you can set the local time in any other timezone you have set up and ezTime will set it's internal offset to the corresponding time in UTC so all timezones stay at the correct time. It's important to realise however that NTP updates will still become due and when they do time will be set to the time returned by the NTP server. If you do not want that, you can turn off NTP updates with `ezsetInterval()`. If you do not use NTP updates at all and do not use the network lookups for timezone information either, you can compile ezTime with no network support by commenting out `#define EZTIME_NETWORK_ENABLE` in the `ezTime.h` file, creating a smaller library. +### Alternate sources of time + +If your time source is not NTP, the way to update time is to create a user function that gets the time from somewhere and then sets the clock with `setTime` and then schedules the next time it synchronises the clock with `setEvent`. This way you have full flexibility: you can schedule the next update sooner if this update fails, for instance. Remember to turn off NTP updates if you want your new time to stick. + ## Working with time values ### *breakTime* @@ -698,7 +702,7 @@ This version takes the various numeric elements as arguments. Note that you can ### *makeOrdinalTime* -`time_t makeOrdinalTime(uint8_t hour, uint8_t minute, uint8_t second,`
          `uint8_t ordinal, uint8_t wday, uint8_t month, int16_t year);` +`time_t makeOrdinalTime(uint8_t hour, uint8_t minute, uint8_t second,`
          `uint8_t ordinal, uint8_t wday, uint8_t month, int16_t year);` With `makeOrdinalTime` you can get the `time_t` value for a date written as "the second Tuesday in March". The `ordinal` value is 1 for first, 2 for second, 3 for third, 4 for fourth and either 5 or 0 for the last of that weekday in the month. `wday` is weekdays starting with Sunday as 1. You can use the names of ordinals, months and weekdays in all caps as they are compiler defines. So the following would find the `time_t` value for midnight at the start of the first Thursday of the year in variable `year`. @@ -714,7 +718,7 @@ makeOrdinalTime(0, 0, 0, FIRST, THURSDAY, JANUARY, year) `time_t compileTime(String compile_date = __DATE__, String compile_time = __TIME__);` -Returns the time you compiled your sketch. You can check out the "NoNetwork" example with this library to see it in use: it makes your Arduino pretend to know what time it is. +You can ignore the arguments above and just say `compileTime()`. Returns the time value for when you compiled your sketch. You can check out the "NoNetwork" example with this library to see it in use: it makes your Arduino pretend to know what time it is.   @@ -766,7 +770,7 @@ Pads `number` with zeroes to the left until the resulting string is `length` pla | `DEBUG` | Detailed debugging information unlikely to be of much use unless you are trying to get to the bottom of certain internal behaviour of ezTime. | *Note:* you can specify which level of debug information would be compiled into the library. This is especially significant for AVR Arduino users that need to limit the flash and RAM footprint of ezTtime. See the "Smaller footprint, AVR Arduinos" chapter further down. -`device` is optional and can specify a device to receive the debug messages. This defaults to the Hardwareserial object names `Serial` but can be any device that has inherited from the `Print` class. Don't worry if you don't understand that: it means you can specify not only serial ports, but also a handle to a file you have opened on the SD card as well as a lot of LCD screen devices. For instance, on my M5Stack device I can — after `#include ` and `m5.begin()` — do: `setDebug(INFO, m5.lcd)` +`device` is optional and can specify a device to receive the debug messages. This defaults to the Hardwareserial object named `Serial` but can be any device that has inherited from the `Print` class. Don't worry if you don't understand that: it means you can specify not only serial ports, but also a handle to a file you have opened on the SD card as well as a lot of LCD screen devices. For instance, on my M5Stack device I can — after `#include ` and `m5.begin()` — do: `setDebug(INFO, m5.lcd)` ![](images/M5Stack-debug.jpg) diff --git a/src/ezTime.cpp b/src/ezTime.cpp index c3a5338..3698a40 100644 --- a/src/ezTime.cpp +++ b/src/ezTime.cpp @@ -77,7 +77,7 @@ namespace { String _ntp_server = NTP_SERVER; #endif - void error(ezError_t err) { + void error(const ezError_t err) { _last_error = err; if (_last_error) { err(F("ERROR: ")); @@ -85,7 +85,7 @@ namespace { } } - String debugLevelString(ezDebugLevel_t level) { + String debugLevelString(const ezDebugLevel_t level) { switch (level) { case NONE: return F("NONE"); case ERROR: return F("ERROR"); @@ -94,7 +94,7 @@ namespace { } } - time_t nowUTC(bool update_last_read = true) { + time_t nowUTC(const bool update_last_read = true) { time_t t; uint32_t m = millis(); t = _last_sync_time + ((m - _last_sync_millis) / 1000); @@ -111,7 +111,7 @@ namespace { ////////// Error handing -String errorString(ezError_t err /* = LAST_ERROR */) { +String errorString(const ezError_t err /* = LAST_ERROR */) { switch (err) { case NO_ERROR: return F("OK"); case LAST_ERROR: return errorString(_last_error); @@ -129,17 +129,17 @@ String errorString(ezError_t err /* = LAST_ERROR */) { -ezError_t error(bool reset /* = false */) { +ezError_t error(const bool reset /* = false */) { ezError_t tmp = _last_error; if (reset) _last_error = NO_ERROR; return tmp; } -void setDebug(ezDebugLevel_t level) { +void setDebug(const ezDebugLevel_t level) { setDebug(level, *_debug_device); } -void setDebug(ezDebugLevel_t level, Print &device) { +void setDebug(const ezDebugLevel_t level, Print &device) { _debug_level = level; _debug_device = &device; info(F("\r\nezTime debug level set to ")); @@ -148,7 +148,7 @@ void setDebug(ezDebugLevel_t level, Print &device) { //////////////////////// -String monthString(uint8_t month) { +String monthString(const uint8_t month) { switch(month) { case 1: return F("January"); case 2: return F("February"); @@ -166,7 +166,7 @@ String monthString(uint8_t month) { return ""; } -String dayString(uint8_t day) { +String dayString(const uint8_t day) { switch(day) { case 1: return F("Sunday"); case 2: return F("Monday"); @@ -202,7 +202,7 @@ void events() { yield(); } -void deleteEvent(uint8_t event_handle) { +void deleteEvent(const uint8_t event_handle) { if (event_handle && event_handle <= MAX_EVENTS) { debug(F("Deleted event (#")); debug(event_handle); debug(F("), set for ")); debugln(UTC.dateTime(_events[event_handle - 1].time)); _events[event_handle - 1] = { 0, NULL }; @@ -218,7 +218,7 @@ void deleteEvent(void (*function)()) { } } -void breakTime(time_t timeInput, tmElements_t &tm){ +void breakTime(const time_t timeInput, tmElements_t &tm){ // break the given time_t into time components // this is a more compact version of the C library localtime function // note that year is offset from 1970 !!! @@ -271,7 +271,7 @@ void breakTime(time_t timeInput, tmElements_t &tm){ tm.Day = time + 1; // day of month } -time_t makeTime(uint8_t hour, uint8_t minute, uint8_t second, uint8_t day, uint8_t month, uint16_t year) { +time_t makeTime(const uint8_t hour, const uint8_t minute, const uint8_t second, const uint8_t day, const uint8_t month, const uint16_t year) { tmElements_t tm; tm.Hour = hour; tm.Minute = minute; @@ -323,11 +323,11 @@ time_t makeTime(tmElements_t &tm){ // makeOrdinalTime allows you to resolve "second thursday in September in 2018" into a number of seconds since 1970 // (Very useful for the timezone calculations that ezTime does internally) // If ordinal is 0 or 5 it is taken to mean "the last $wday in $month" -time_t makeOrdinalTime(uint8_t hour, uint8_t minute, uint8_t second, uint8_t ordinal, uint8_t wday, uint8_t month, uint16_t year) { +time_t makeOrdinalTime(const uint8_t hour, const uint8_t minute, uint8_t const second, uint8_t ordinal, const uint8_t wday, const uint8_t month, uint16_t year) { if (year <= 68 ) year = 1970 + year; // fix user intent - if (ordinal == 5) ordinal = 0; uint8_t m = month; uint8_t w = ordinal; + if (w == 5) ordinal = 0; if (w == 0) { // is this a "Last week" rule? if (++m > 12) { // yes, for "Last", go to the next month m = 1; @@ -343,7 +343,7 @@ time_t makeOrdinalTime(uint8_t hour, uint8_t minute, uint8_t second, uint8_t ord return t; } -String urlEncode(String str) { +String urlEncode(const String str) { String encodedString=""; char c; char code0; @@ -372,7 +372,7 @@ String urlEncode(String str) { return encodedString; } -String zeropad(uint32_t number, uint8_t length) { +String zeropad(const uint32_t number, const uint8_t length) { String out; out.reserve(length); out = String(number); @@ -380,7 +380,7 @@ String zeropad(uint32_t number, uint8_t length) { return out; } -time_t compileTime(String compile_date /* = __DATE__ */, String compile_time /* = __TIME__ */) { +time_t compileTime(const String compile_date /* = __DATE__ */, const String compile_time /* = __TIME__ */) { uint8_t hrs = compile_time.substring(0,2).toInt(); uint8_t min = compile_time.substring(3,5).toInt(); @@ -448,7 +448,7 @@ bool minuteChanged() { // This is a nice self-contained NTP routine if you need one: feel free to use it. // It gives you the seconds since 1970 (unix epoch) and the millis() on your system when // that happened (by deducting fractional seconds and estimated network latency). - bool queryNTP(String server, time_t &t, unsigned long &measured_at) { + bool queryNTP(const String server, time_t &t, unsigned long &measured_at) { info(F("Querying ")); info(server); info(F(" ... ")); @@ -477,7 +477,7 @@ bool minuteChanged() { buffer[13] = 'E'; // (codes starting with 'X' are not interpreted) buffer[14] = 'Z'; buffer[15] = 'T'; - udp.beginPacket(_ntp_server.c_str(), 123); //NTP requests are to port 123 + udp.beginPacket(server.c_str(), 123); //NTP requests are to port 123 udp.write(buffer, NTP_PACKET_SIZE); udp.endPacket(); @@ -510,15 +510,15 @@ bool minuteChanged() { return true; } - void setInterval(uint16_t seconds /* = 0 */) { + void setInterval(const uint16_t seconds /* = 0 */) { deleteEvent(updateNTP); _ntp_interval = seconds; if (seconds) UTC.setEvent(updateNTP, nowUTC() + _ntp_interval); } - void setServer(String ntp_server /* = NTP_SERVER */) { _ntp_server = ntp_server; } + void setServer(const String ntp_server /* = NTP_SERVER */) { _ntp_server = ntp_server; } - bool waitForSync(uint16_t timeout /* = 0 */) { + bool waitForSync(const uint16_t timeout /* = 0 */) { unsigned long start = millis(); @@ -553,7 +553,7 @@ bool minuteChanged() { // Timezone class // -Timezone::Timezone(bool locked_to_UTC /* = false */) { +Timezone::Timezone(const bool locked_to_UTC /* = false */) { _locked_to_UTC = locked_to_UTC; _posix = "UTC"; #ifdef EZTIME_NETWORK_ENABLE @@ -570,7 +570,7 @@ Timezone::Timezone(bool locked_to_UTC /* = false */) { #endif } -bool Timezone::setPosix(String posix) { +bool Timezone::setPosix(const String posix) { if (_locked_to_UTC) { error(LOCKED_TO_UTC); return false; } _posix = posix; #ifdef EZTIME_NETWORK_ENABLE @@ -793,7 +793,7 @@ String Timezone::getPosix() { return _posix; } #ifdef EZTIME_NETWORK_ENABLE - bool Timezone::setLocation(String location /* = "" */) { + bool Timezone::setLocation(const String location /* = "" */) { info(F("Timezone lookup for: ")); infoln(location); @@ -930,7 +930,7 @@ String Timezone::getPosix() { return _posix; } return false; } - void Timezone::clearCache(bool delete_section /* = false */) { + void Timezone::clearCache(const bool delete_section /* = false */) { #ifdef EZTIME_CACHE_EEPROM eepromBegin(); @@ -1129,7 +1129,7 @@ void Timezone::setDefault() { debug(F("Default timezone set to ")); debug(_olsen); debug(F(" "));debugln(_posix); } -bool Timezone::isDST(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +bool Timezone::isDST(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { String tzname; bool is_dst; int16_t offset; @@ -1137,7 +1137,7 @@ bool Timezone::isDST(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = return is_dst; } -String Timezone::getTimezoneName(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +String Timezone::getTimezoneName(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { String tzname; bool is_dst; int16_t offset; @@ -1145,7 +1145,7 @@ String Timezone::getTimezoneName(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_ return tzname; } -int16_t Timezone::getOffset(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +int16_t Timezone::getOffset(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { String tzname; bool is_dst; int16_t offset; @@ -1158,7 +1158,7 @@ uint8_t Timezone::setEvent(void (*function)(), const uint8_t hr, const uint8_t m return setEvent(function, t); } -uint8_t Timezone::setEvent(void (*function)(), time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::setEvent(void (*function)(), time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); for (uint8_t n = 0; n < MAX_EVENTS; n++) { if (!_events[n].function) { @@ -1172,7 +1172,7 @@ uint8_t Timezone::setEvent(void (*function)(), time_t t /* = TIME_NOW */, ezLoca return 0; } -void Timezone::setTime(time_t t, uint16_t ms /* = 0 */) { +void Timezone::setTime(const time_t t, const uint16_t ms /* = 0 */) { int16_t offset; offset = getOffset(t); _last_sync_time = t + offset * 60; @@ -1198,15 +1198,15 @@ void Timezone::setTime(const uint8_t hr, const uint8_t min, const uint8_t sec, c setTime(makeTime(tm)); } -String Timezone::dateTime(String format /* = DEFAULT_TIMEFORMAT */) { +String Timezone::dateTime(const String format /* = DEFAULT_TIMEFORMAT */) { return dateTime(TIME_NOW, format); } -String Timezone::dateTime(time_t t, String format /* = DEFAULT_TIMEFORMAT */) { +String Timezone::dateTime(const time_t t, const String format /* = DEFAULT_TIMEFORMAT */) { return dateTime(t, LOCAL_TIME, format); } -String Timezone::dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format /* = DEFAULT_TIMEFORMAT */) { +String Timezone::dateTime(time_t t, const ezLocalOrUTC_t local_or_utc, const String format /* = DEFAULT_TIMEFORMAT */) { String tzname; bool is_dst; @@ -1229,7 +1229,7 @@ String Timezone::dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format / for (uint8_t n = 0; n < format.length(); n++) { - char c = (char) format.c_str()[n]; + char c = format.charAt(n); if (escape_char) { out += String(c); @@ -1368,7 +1368,7 @@ String Timezone::dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format / return out; } -String Timezone::militaryTZ(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +String Timezone::militaryTZ(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); int16_t o = getOffset(t); if (o % 60) return "?"; // If it's not a whole hour from UTC, it's not a timezone with a military letter code @@ -1380,17 +1380,17 @@ String Timezone::militaryTZ(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_ut } -uint8_t Timezone::hour(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::hour(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); return t / 3600 % 24; } -uint8_t Timezone::minute(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::minute(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); return t / 60 % 60; } -uint8_t Timezone::second(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::second(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); return t % 60; } @@ -1402,35 +1402,35 @@ uint16_t Timezone::ms(time_t t /*= TIME_NOW */) { return 0; } -uint8_t Timezone::day(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::day(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); tmElements_t tm; breakTime(t, tm); return tm.Day; } -uint8_t Timezone::weekday(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::weekday(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); tmElements_t tm; breakTime(t, tm); return tm.Wday; } -uint8_t Timezone::month(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::month(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); tmElements_t tm; breakTime(t, tm); return tm.Month; } -uint16_t Timezone::year(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint16_t Timezone::year(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); tmElements_t tm; breakTime(t, tm); return tm.Year + 1970; } -uint16_t Timezone::dayOfYear(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint16_t Timezone::dayOfYear(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); time_t jan_1st = makeTime(0, 0, 0, 1, 1, year(t)); return (t - jan_1st) / SECS_PER_DAY; @@ -1443,7 +1443,7 @@ uint16_t Timezone::dayOfYear(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_u // See https://en.wikipedia.org/wiki/ISO_week_date // #define startISOyear(year...) makeOrdinalTime(0, 0, 0, FIRST, THURSDAY, JANUARY, year) - 3UL * SECS_PER_DAY; -uint8_t Timezone::weekISO(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint8_t Timezone::weekISO(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); int16_t yr = year(t); time_t this_year = startISOyear(yr); @@ -1454,7 +1454,7 @@ uint8_t Timezone::weekISO(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc return (t - this_year) / ( SECS_PER_DAY * 7UL) + 1; } -uint16_t Timezone::yearISO(time_t t /*= TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { +uint16_t Timezone::yearISO(time_t t /*= TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { t = tzTime(t, local_or_utc); int16_t yr = year(t); time_t this_year = startISOyear(yr); @@ -1478,30 +1478,30 @@ String monthStr(const uint8_t month) { return monthString(month); } // All bounce-throughs to defaultTZ -String dateTime(String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(format)); } -String dateTime(time_t t, String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(t, format)); } -String dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(t, local_or_utc, format)); } -uint8_t day(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->day(t, local_or_utc)); } -uint16_t dayOfYear(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->dayOfYear(t, local_or_utc)); } -int16_t getOffset(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->getOffset(t, local_or_utc)); } -String getTimezoneName(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->getTimezoneName(t, local_or_utc)); } -uint8_t hour(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc)); } -uint8_t hourFormat12(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) % 12); } -bool isAM(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) < 12) ? true : false; } -bool isDST(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->isDST(t, local_or_utc)); } -bool isPM(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) >= 12) ? true : false; } -String militaryTZ(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->militaryTZ(t, local_or_utc)); } -uint8_t minute(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->minute(t, local_or_utc)); } -uint8_t month(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->month(t, local_or_utc)); } +String dateTime(const String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(format)); } +String dateTime(time_t t, const String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(t, format)); } +String dateTime(time_t t, const ezLocalOrUTC_t local_or_utc, const String format /* = DEFAULT_TIMEFORMAT */) { return (defaultTZ->dateTime(t, local_or_utc, format)); } +uint8_t day(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->day(t, local_or_utc)); } +uint16_t dayOfYear(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->dayOfYear(t, local_or_utc)); } +int16_t getOffset(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->getOffset(t, local_or_utc)); } +String getTimezoneName(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->getTimezoneName(t, local_or_utc)); } +uint8_t hour(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc)); } +uint8_t hourFormat12(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) % 12); } +bool isAM(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) < 12) ? true : false; } +bool isDST(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->isDST(t, local_or_utc)); } +bool isPM(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->hour(t, local_or_utc) >= 12) ? true : false; } +String militaryTZ(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->militaryTZ(t, local_or_utc)); } +uint8_t minute(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->minute(t, local_or_utc)); } +uint8_t month(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->month(t, local_or_utc)); } uint16_t ms(time_t t /* = TIME_NOW */) { return (defaultTZ->ms(t)); } time_t now() { return (defaultTZ->now()); } -uint8_t second(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->second(t, local_or_utc)); } +uint8_t second(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->second(t, local_or_utc)); } uint8_t setEvent(void (*function)(), const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t mnth, uint16_t yr) { return (defaultTZ->setEvent(function,hr, min, sec, day, mnth, yr)); } -uint8_t setEvent(void (*function)(), time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->setEvent(function, t, local_or_utc)); } +uint8_t setEvent(void (*function)(), time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->setEvent(function, t, local_or_utc)); } void setTime(const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t month, const uint16_t yr) { defaultTZ->setTime(hr, min, sec, day, month, yr); } void setTime(time_t t) { defaultTZ->setTime(t); } -uint8_t weekISO(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->weekISO(t, local_or_utc)); } -uint8_t weekday(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->weekday(t, local_or_utc)); } -uint16_t year(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->year(t, local_or_utc)); } -uint16_t yearISO(time_t t /* = TIME_NOW */, ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->yearISO(t, local_or_utc)); } +uint8_t weekISO(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->weekISO(t, local_or_utc)); } +uint8_t weekday(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->weekday(t, local_or_utc)); } +uint16_t year(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->year(t, local_or_utc)); } +uint16_t yearISO(time_t t /* = TIME_NOW */, const ezLocalOrUTC_t local_or_utc /* = LOCAL_TIME */) { return (defaultTZ->yearISO(t, local_or_utc)); } diff --git a/src/ezTime.h b/src/ezTime.h index 2a490ac..8585961 100644 --- a/src/ezTime.h +++ b/src/ezTime.h @@ -164,32 +164,32 @@ typedef struct { #define ISO8601_YWD "X-\\WW-N" #define DEFAULT_TIMEFORMAT COOKIE -void breakTime(time_t time, tmElements_t &tm); -time_t compileTime(String compile_date = __DATE__, String compile_time = __TIME__); -String dayString(uint8_t day); -void deleteEvent(uint8_t event_handle); +void breakTime(const time_t time, tmElements_t &tm); +time_t compileTime(const String compile_date = __DATE__, const String compile_time = __TIME__); +String dayString(const uint8_t day); +void deleteEvent(const uint8_t event_handle); void deleteEvent(void (*function)()); -ezError_t error(bool reset = false); -String errorString(ezError_t err = LAST_ERROR); +ezError_t error(const bool reset = false); +String errorString(const ezError_t err = LAST_ERROR); void events(); -time_t makeOrdinalTime(uint8_t hour, uint8_t minute, uint8_t second, uint8_t ordinal, uint8_t wday, uint8_t month, uint16_t year); +time_t makeOrdinalTime(const uint8_t hour, const uint8_t minute, const uint8_t second, uint8_t ordinal, const uint8_t wday, const uint8_t month, uint16_t year); time_t makeTime(tmElements_t &tm); -time_t makeTime(uint8_t hour, uint8_t minute, uint8_t second, uint8_t day, uint8_t month, uint16_t year); +time_t makeTime(const uint8_t hour, const uint8_t minute, const uint8_t second, const uint8_t day, const uint8_t month, const uint16_t year); bool minuteChanged(); -String monthString(uint8_t month); +String monthString(const uint8_t month); bool secondChanged(); -void setDebug(ezDebugLevel_t level); -void setDebug(ezDebugLevel_t level, Print &device); +void setDebug(const ezDebugLevel_t level); +void setDebug(const ezDebugLevel_t level, Print &device); timeStatus_t timeStatus(); -String urlEncode(String str); -String zeropad(uint32_t number, uint8_t length); +String urlEncode(const String str); +String zeropad(const uint32_t number, const uint8_t length); #ifdef EZTIME_NETWORK_ENABLE - bool queryNTP(String server, time_t &t, unsigned long &measured_at); - void setInterval(uint16_t seconds = 0); - void setServer(String ntp_server = NTP_SERVER); + bool queryNTP(const String server, time_t &t, unsigned long &measured_at); + void setInterval(const uint16_t seconds = 0); + void setServer(const String ntp_server = NTP_SERVER); void updateNTP(); - bool waitForSync(uint16_t timeout = 0); + bool waitForSync(const uint16_t timeout = 0); #endif @@ -200,42 +200,42 @@ String zeropad(uint32_t number, uint8_t length); class Timezone { public: - Timezone(bool locked_to_UTC = false); - String dateTime(String format = DEFAULT_TIMEFORMAT); - String dateTime(time_t t, String format = DEFAULT_TIMEFORMAT); - String dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format = DEFAULT_TIMEFORMAT); - uint8_t day(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 1-31 - uint16_t dayOfYear(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // days from start of year, jan 1st = 0 - int16_t getOffset(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); + Timezone(const bool locked_to_UTC = false); + String dateTime(const String format = DEFAULT_TIMEFORMAT); + String dateTime(time_t t, const String format = DEFAULT_TIMEFORMAT); + String dateTime(time_t t, const ezLocalOrUTC_t local_or_utc, const String format = DEFAULT_TIMEFORMAT); + uint8_t day(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 1-31 + uint16_t dayOfYear(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // days from start of year, jan 1st = 0 + int16_t getOffset(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); String getPosix(); - String getTimezoneName(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); - uint8_t hour(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-23 - bool isDST(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); - String militaryTZ(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); - uint8_t minute(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-59 - uint8_t month(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 1-12 + String getTimezoneName(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); + uint8_t hour(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-23 + bool isDST(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); + String militaryTZ(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); + uint8_t minute(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-59 + uint8_t month(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 1-12 uint16_t ms(time_t t = TIME_NOW); // 0-999 time_t now(); - uint8_t second(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-59 + uint8_t second(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // 0-59 void setDefault(); uint8_t setEvent(void (*function)(), const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t mnth, uint16_t yr); - uint8_t setEvent(void (*function)(), time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); - bool setPosix(String posix); + uint8_t setEvent(void (*function)(), time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); + bool setPosix(const String posix); void setTime(const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t mnth, uint16_t yr); - void setTime(time_t t, uint16_t ms = 0); + void setTime(const time_t t, const uint16_t ms = 0); time_t tzTime(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); time_t tzTime(time_t t, ezLocalOrUTC_t local_or_utc, String &tzname, bool &is_dst, int16_t &offset); - uint8_t weekISO(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // ISO-8601 week number (weeks starting on Monday) - uint8_t weekday(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // Day of the week (1-7), Sunday is day 1 - uint16_t year(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // four digit year - uint16_t yearISO(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // ISO-8601 year, can differ from actual year, plus or minus one + uint8_t weekISO(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // ISO-8601 week number (weeks starting on Monday) + uint8_t weekday(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // Day of the week (1-7), Sunday is day 1 + uint16_t year(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // four digit year + uint16_t yearISO(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); // ISO-8601 year, can differ from actual year, plus or minus one private: String _posix, _olsen; bool _locked_to_UTC; #ifdef EZTIME_NETWORK_ENABLE public: - bool setLocation(String location = ""); + bool setLocation(const String location = ""); String getOlsen(); #ifdef EZTIME_CACHE_EEPROM public: @@ -251,7 +251,7 @@ class Timezone { #endif #if defined(EZTIME_CACHE_EEPROM) || defined(EZTIME_CACHE_NVS) public: - void clearCache(bool delete_section = false); + void clearCache(const bool delete_section = false); private: bool setCache(); bool writeCache(String &str); @@ -267,32 +267,32 @@ extern Timezone *defaultTZ; // These bounce through to same-named methods in defaultTZ -String dateTime(String format = DEFAULT_TIMEFORMAT); -String dateTime(time_t t, String format = DEFAULT_TIMEFORMAT); -String dateTime(time_t t, ezLocalOrUTC_t local_or_utc, String format = DEFAULT_TIMEFORMAT); -uint8_t day(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint16_t dayOfYear(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -int16_t getOffset(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -String getTimezoneName(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint8_t hour(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint8_t hourFormat12(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -bool isAM(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -bool isDST(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -bool isPM(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -String militaryTZ(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint8_t minute(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint8_t month(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +String dateTime(const String format = DEFAULT_TIMEFORMAT); +String dateTime(time_t t, const String format = DEFAULT_TIMEFORMAT); +String dateTime(time_t t, const ezLocalOrUTC_t local_or_utc, const String format = DEFAULT_TIMEFORMAT); +uint8_t day(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint16_t dayOfYear(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +int16_t getOffset(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +String getTimezoneName(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t hour(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t hourFormat12(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +bool isAM(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +bool isDST(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +bool isPM(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +String militaryTZ(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t minute(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t month(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); uint16_t ms(time_t t = TIME_NOW); time_t now(); -uint8_t second(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t second(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); uint8_t setEvent(void (*function)(), const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t mnth, uint16_t yr); -uint8_t setEvent(void (*function)(), time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t setEvent(void (*function)(), time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); void setTime(const uint8_t hr, const uint8_t min, const uint8_t sec, const uint8_t day, const uint8_t month, const uint16_t yr); void setTime(time_t t); -uint8_t weekISO(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint8_t weekday(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint16_t year(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); -uint16_t yearISO(time_t t = TIME_NOW, ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t weekISO(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint8_t weekday(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint16_t year(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME); +uint16_t yearISO(time_t t = TIME_NOW, const ezLocalOrUTC_t local_or_utc = LOCAL_TIME);