mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/dateTimeHelpers/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/dateTimeHelpers/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/dateTimeHelpers/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/dateTimeHelpers/releases)
|
|
|
|
|
|
# dateTimeHelpers
|
|
|
|
Arduino library with date and time helper functions.
|
|
|
|
## Description
|
|
|
|
This library contains functions that have the goal to help with date and time processing.
|
|
It is primary a placeholder.
|
|
|
|
Please report missing functions, open an issue or preferably a PR.
|
|
|
|
|
|
#### Related libraries
|
|
|
|
- https://github.com/RobTillaart/printHelpers
|
|
- https://github.com/RobTillaart/stopWatch_RT
|
|
- https://github.com/RobTillaart/CountDown
|
|
- https://github.com/RobTillaart/timing
|
|
|
|
|
|
#### Implementation notes
|
|
|
|
- the functions share an output buffer.
|
|
This can give problems when prints are made fast after each other as the buffer
|
|
is not printed completely before it is filled again. (think also RTOS)
|
|
- math is straightforward, may be optimized? sprintf()?
|
|
- code has repeating parts, may be optimized?
|
|
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "dateTimeHelpers.h"
|
|
```
|
|
|
|
#### Display functions
|
|
|
|
- **void secondsSplit(uint32_t seconds, uint16_t \* days, uint8_t \* hours, uint8_t \* minutes, uint8_t \* sec)** Splits the seconds into days, hours, minutes and seconds.
|
|
This is the worker for the next three.
|
|
Note: days is max 65535 == 179 years.
|
|
- **char \* seconds2duration(uint32_t seconds, bool displaySeconds = false)** returns "days 00:00:00 .. 23:59:59" or "days 00:00 .. 23:59"
|
|
- **char \* seconds2clock24(uint32_t seconds, bool displaySeconds = false)** returns "00:00:00 .. 23:59:59" or "00:00 .. 23:59"
|
|
- **char \* seconds2clock12(uint32_t seconds, bool displaySeconds = false)** returns "00:00:00 .. 12:59:59" or "00:00 .. 12:59".
|
|
Note this function has no morning or afternoon indication.
|
|
- **char \* seconds2clockAMPM(uint32_t seconds, bool displaySeconds = false)** returns "00:00:00 AM .. 12:59:59 PM" or "00:00 AM .. 12:59 PM".
|
|
- **char \* millis2duration(uint32_t millis)** returns "days 00:00:00.000 .. 23:59:59.999"
|
|
- **char \* millis2clock(uint32_t millis)** returns "00:00:00.000 .. 23:59:59.999"
|
|
|
|
|
|
#### AM PM
|
|
|
|
**seconds2clockAMPM** has two more or less undefined moments: midnight (00:00 AM 12:00 PM) and noon (12:00 AM 12:00 PM).
|
|
See https://www.npl.co.uk/resources/q-a/is-midnight-12am-or-12pm)
|
|
|
|
At night one uses 00:15 AM and after noon one uses 12:15 PM.
|
|
Therefore I use in this implementation:
|
|
- midnight == 00:00 AM
|
|
- noon == 12:00 PM
|
|
|
|
|
|
### Convertors
|
|
|
|
Note: the following functions use float math so there might occur rounding.
|
|
|
|
- **float seconds2weeks(uint32_t seconds)** idem.
|
|
- **float seconds2days(uint32_t seconds)** idem.
|
|
- **float seconds2hours(uint32_t seconds)** idem.
|
|
- **float seconds2minutes(uint32_t seconds)** idem.
|
|
|
|
|
|
## Future
|
|
|
|
#### Must
|
|
|
|
- improve documentation
|
|
- test a lot
|
|
|
|
#### Should
|
|
|
|
- optimize for performance
|
|
- secondssplit() (see fast math lib)
|
|
- merge code where possible
|
|
- extend examples
|
|
- add unit tests
|
|
- create .cpp file, + move code
|
|
|
|
|
|
#### Could
|
|
|
|
- date math functions
|
|
- days=date-date or date = date + days
|
|
- day of week
|
|
- time math functions
|
|
- 64 bit versions of convertors?
|
|
- unusual time units for converters?
|
|
- atomic time
|
|
- micros2clock()
|
|
- mm:ss:ttt:mmm or mm:ss.ttt.mmm ?
|
|
- hour2angle(hh.mm.ss) = angle of the hour hand
|
|
- 12x60x60 = 360° in 1/12th parts
|
|
- idem radians..
|
|
- minute2angle(mm.ss) = angle of the minute hand (mm x 6 + ss x 0.1
|
|
- seconds2angle(ss) = angle of the seconds hand (ssx6)
|
|
- "classify" ?
|
|
- extern "C" ?
|
|
|
|
#### Won't
|
|
|
|
|