DateTime.h
Go to the documentation of this file.
1 /*
2  DateTime.h - Arduino library for date and time functions
3  Copyright (c) Michael Margolis. All right reserved.
4 
5 
6  This library is distributed in the hope that it will be useful,
7  but WITHOUT ANY WARRANTY; without even the implied warranty of
8  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
9 
11  Heavily rewritten for Sming Framework
12 */
13 
17 #pragma once
18 
19 #include <time.h>
20 #include <WString.h>
21 #include "SmingLocale.h"
22 #include <sming_attr.h>
23 
24 /*==============================================================================*/
25 /* Useful Constants */
26 #define SECS_PER_MIN (60UL)
27 #define SECS_PER_HOUR (3600UL)
28 #define SECS_PER_DAY (SECS_PER_HOUR * 24L)
29 #define DAYS_PER_WEEK (7L)
30 #define SECS_PER_WEEK (SECS_PER_DAY * DAYS_PER_WEEK)
31 #define SECS_PER_YEAR (SECS_PER_WEEK * 52L)
32 #define SECS_YR_2000 (946681200UL)
33 
34 /* Useful Macros for getting elapsed time */
36 #define numberOfSeconds(_time_) (_time_ % SECS_PER_MIN)
38 #define numberOfMinutes(_time_) ((_time_ / SECS_PER_MIN) % SECS_PER_MIN)
40 #define numberOfHours(_time_) ((_time_ % SECS_PER_DAY) / SECS_PER_HOUR)
42 #define dayOfWeek(_time_) ((_time_ / SECS_PER_DAY + 4) % DAYS_PER_WEEK) // 0 = Sunday
44 #define elapsedDays(_time_) (_time_ / SECS_PER_DAY) // this is number of days since Jan 1 1970
46 #define elapsedSecsToday(_time_) (_time_ % SECS_PER_DAY) // the number of seconds since last midnight
48 #define previousMidnight(_time_) ((_time_ / SECS_PER_DAY) * SECS_PER_DAY) // time at the start of the given day
50 #define nextMidnight(_time_) (previousMidnight(_time_) + SECS_PER_DAY) // time at the end of the given day
52 #define elapsedSecsThisWeek(_time_) (elapsedSecsToday(_time_) + (dayOfWeek(_time_) * SECS_PER_DAY))
53 
54 // todo add date math macros
55 /*============================================================================*/
56 
59 enum dtDays_t {
66  dtSaturday
67 };
68 
79 class DateTime
80 {
81 public:
85  {
86  }
87 
91  DateTime(time_t time)
92  {
93  setTime(time);
94  }
95 
99  operator time_t()
100  {
101  return toUnixTime();
102  }
103 
107  void setTime(time_t time);
108 
117  void setTime(uint8_t sec, uint8_t min, uint8_t hour, uint8_t day, uint8_t month, uint16_t year)
118  {
119  Second = sec;
120  Minute = min;
121  Hour = hour;
122  Day = day;
123  Month = month;
124  Year = year;
125  Milliseconds = 0;
126  calcDayOfYear();
127  }
128 
135  bool fromHttpDate(const String& httpDate);
136 
140  bool isNull();
141 
146  time_t toUnixTime();
147 
152 
157  String toShortTimeString(bool includeSeconds = false);
158 
163 
168 
173 
177  void addMilliseconds(long add);
178 
179  // functions to convert to and from time components (hrs, secs, days, years etc) to time_t
196  static void fromUnixTime(time_t timep, uint8_t* psec, uint8_t* pmin, uint8_t* phour, uint8_t* pday, uint8_t* pwday,
197  uint8_t* pmonth, uint16_t* pyear);
198 
199  // functions to convert to and from time components (hrs, secs, days, years etc) to time_t
200 
213  static time_t toUnixTime(uint8_t sec, uint8_t min, uint8_t hour, uint8_t day, uint8_t month, uint16_t year);
214 
258  String format(const char* formatString);
259 
265  String format(const String& formatString)
266  {
267  return format(formatString.c_str());
268  }
269 
270 private:
271  void calcDayOfYear(); // Helper function calculates day of year
272  uint8_t calcWeek(uint8_t firstDay); //Helper function calculates week number based on firstDay of week
273 
274 public:
275  uint8_t Hour = 0;
276  uint8_t Minute = 0;
277  uint8_t Second = 0;
278  uint16_t Milliseconds = 0;
279  uint8_t Day = 0;
280  uint8_t DayofWeek = 0;
281  uint16_t DayofYear = 0;
282  uint8_t Month = 0;
283  uint16_t Year = 0;
284 };
285 
Date and time class.
Definition: DateTime.h:80
uint8_t Minute
Minute (0-59)
Definition: DateTime.h:276
String toFullDateTimeString()
Get human readable date and time.
uint8_t Hour
Hour (0-23)
Definition: DateTime.h:275
DateTime(time_t time)
Instantiate a date and time object from a Unix timestamp.
Definition: DateTime.h:91
DateTime()
Instantiate an uninitialised date and time object.
Definition: DateTime.h:84
uint8_t Second
Second (0-59)
Definition: DateTime.h:277
String toHTTPDate()
Get human readable date and time.
uint16_t DayofYear
Day of year (0-365)
Definition: DateTime.h:281
String toISO8601()
Get human readable date and time.
uint16_t Milliseconds
Milliseconds (0-999)
Definition: DateTime.h:278
void addMilliseconds(long add)
Add time to date time object.
String toShortDateString()
Get human readable date.
String format(const String &formatString)
Create string formatted with time and date placeholders.
Definition: DateTime.h:265
void setTime(time_t time)
Set time using Unix timestamp.
static time_t toUnixTime(uint8_t sec, uint8_t min, uint8_t hour, uint8_t day, uint8_t month, uint16_t year)
Convert from individual time components to Unix time.
uint8_t DayofWeek
Day of week (0-6 Sunday is day 0)
Definition: DateTime.h:280
bool isNull()
Check if time date object is initialised.
time_t toUnixTime()
Get Unix time.
bool fromHttpDate(const String &httpDate)
Parse a HTTP full date and set time and date.
void setTime(uint8_t sec, uint8_t min, uint8_t hour, uint8_t day, uint8_t month, uint16_t year)
Set time using time and date component values.
Definition: DateTime.h:117
static void fromUnixTime(time_t timep, uint8_t *psec, uint8_t *pmin, uint8_t *phour, uint8_t *pday, uint8_t *pwday, uint8_t *pmonth, uint16_t *pyear)
Convert from Unix time to individual time components.
uint16_t Year
Full Year number.
Definition: DateTime.h:283
String format(const char *formatString)
Create string formatted with time and date placeholders.
String toShortTimeString(bool includeSeconds=false)
Get human readable time.
uint8_t Day
Day of month (1-31)
Definition: DateTime.h:279
uint8_t Month
Month (0-11 Jan is month 0)
Definition: DateTime.h:282
The String class.
Definition: WString.h:137
const char * c_str() const
Get a constant (un-modifiable) pointer to String content.
Definition: WString.h:616
dtDays_t
Days of week.
Definition: DateTime.h:59
@ dtWednesday
Wednesday.
Definition: DateTime.h:63
@ dtMonday
Monday.
Definition: DateTime.h:61
@ dtTuesday
Tuesday.
Definition: DateTime.h:62
@ dtSunday
Sunday.
Definition: DateTime.h:60
@ dtFriday
Friday.
Definition: DateTime.h:65
@ dtThursday
Thursday.
Definition: DateTime.h:64
@ dtSaturday
Saturday.
Definition: DateTime.h:66
Time< T > time(Unit unit, T value)
Helper function to create a Time and deduce the type.
Definition: NanoTime.h:423