fix #4 start() returns bool to indicate overflow (#6)

* fix #4 let start() detect overflow + refactor

Author: RobTillaart

CountDown.cpp

@@ -1,36 +1,40 @@
 //
 //    FILE: CountDown.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.3
+// VERSION: 0.2.4
 // PURPOSE: CountDown library for Arduino
 //     URL: https://github.com/RobTillaart/CountDown
 //
-// HISTORY:
-// 0.2.3    2020-12-17  add arduino-ci + unit test
-// 0.2.2    2020-07-08  add MINUTES; refactor
-// 0.2.1    2020-06-05  fix library.json
-// 0.2.0    2020-03-29  #pragma once, removed pre 1.0 support
-// 0.1.3    2017-07-16  TODO improved seconds - OdoMeter see below ... TODO 
-// 0.1.2    2017-07-16  added start(days, hours, minutes, seconds) + cont() == continue countdown
-// 0.1.1    2015-10-29  added start(h, m, s)
-// 0.1.0    2015-10-27  initial version
-//
+//  HISTORY:
+//  0.2.4   2021-01-15  start detect overflow now.
+//  0.2.3   2020-12-17  add arduino-ci + unit test
+//  0.2.2   2020-07-08  add MINUTES; refactor
+//  0.2.1   2020-06-05  fix library.json
+//  0.2.0   2020-03-29  #pragma once, removed pre 1.0 support
+//  0.1.3   2017-07-16  TODO improved seconds - OdoMeter see below ... TODO 
+//  0.1.2   2017-07-16  added start(days, hours, minutes, seconds) + cont() == continue countdown
+//  0.1.1   2015-10-29  added start(h, m, s)
+//  0.1.0   2015-10-27  initial version
+
 
 #include "CountDown.h"
 
+
 CountDown::CountDown(const enum Resolution res)
 {
   setResolution(res);
   stop();
 }
 
+
 void CountDown::setResolution(const enum Resolution res)
 {
   _res = res;
   _ticks = 0;
 }
 
-void CountDown::start(uint32_t ticks)
+
+bool CountDown::start(uint32_t ticks)
 {
   _ticks = ticks;
   _state = CountDown::RUNNING;
@@ -42,30 +46,45 @@ void CountDown::start(uint32_t ticks)
   {
     _starttime = millis();
   }
+  return true;  // can not overflow
 }
 
-void CountDown::start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds)
+
+bool CountDown::start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds)
 {
+  float _days = seconds / 86400.0 + minutes / 1440.0 + hours / 24.0 + days; 
+  bool rv = (_days < 49.7102696);
+
   uint32_t ticks = 86400UL * days + 3600UL * hours + 60UL * minutes + seconds;
   if (ticks > 4294967) ticks = 4294967;  // prevent underlying millis() overflow
   setResolution(SECONDS);
   start(ticks);
+
+  return rv;
 }
 
-void CountDown::start(uint8_t days, uint16_t hours, uint32_t minutes)
+
+bool CountDown::start(uint8_t days, uint16_t hours, uint32_t minutes)
 {
+  float _days = minutes / 1440.0 + hours / 24.0 + days; 
+  bool rv = (_days < 49.7102696);
+
   uint32_t ticks = 86400UL * days + 3600UL * hours + 60UL * minutes;
   if (ticks > 4294967) ticks = 4294967;  // prevent underlying millis() overflow
   setResolution(MINUTES);
   start(ticks);
+
+  return rv;
 }
 
+
 void CountDown::stop()
 {
   calcRemaining();
   _state = CountDown::STOPPED;
 }
 
+
 void CountDown::cont()
 {
   if (_state == CountDown::STOPPED)
@@ -74,20 +93,22 @@ void CountDown::cont()
   }
 }
 
+
 bool CountDown::isRunning() 
 {
-  if (_state == CountDown::STOPPED) return false;
-  if (remaining() == 0) return false;
-  return true;
+  calcRemaining();
+  return (_state == CountDown::RUNNING);
 }
 
+
 uint32_t CountDown::remaining()
 {
   calcRemaining();
   if (_remaining == 0) _state = CountDown::STOPPED;
   return _remaining;
 }
 
+
 void CountDown::calcRemaining()
 {
   uint32_t t = 0;
@@ -109,7 +130,7 @@ void CountDown::calcRemaining()
         t = millis() - _starttime;
         break;
     }
-    _remaining = _ticks > t ? _ticks - t: 0;
+    _remaining = _ticks > t ? _ticks - t : 0;
     if (_remaining == 0) 
     {
       _state = CountDown::STOPPED;

CountDown.h

@@ -2,36 +2,41 @@
 //
 //    FILE: CountDown.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.3
+// VERSION: 0.2.4
 // PURPOSE: CountDown library for Arduino
 //     URL: https://github.com/RobTillaart/CountDown
 //
 // HISTORY: See CountDown.cpp
 //
 
+
 #include "Arduino.h"
 
-#define COUNTDOWN_LIB_VERSION "0.2.3"
+
+#define COUNTDOWN_LIB_VERSION       (F("0.2.4"))
+
 
 class CountDown
 {
 public:
     enum Resolution { MILLIS, MICROS, SECONDS, MINUTES };
 
     explicit CountDown(const enum Resolution res = MILLIS);
-    void setResolution(const enum Resolution res = MILLIS);
 
-    void start(uint32_t ticks);
-    // Implicit set resolution to SECONDS.
-    void start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds);
-    // Implicit set resolution to MINUTES.
-    void start(uint8_t days, uint16_t hours, uint32_t minutes);
-    void stop();
-    void cont();
+    void     setResolution(const enum Resolution res = MILLIS);
+
+    bool     start(uint32_t ticks);
+             // Implicit set resolution to SECONDS.
+    bool     start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds);
+             // Implicit set resolution to MINUTES.
+    bool     start(uint8_t days, uint16_t hours, uint32_t minutes);
+
+    void     stop();
+    void     cont();
 
     uint32_t remaining();
-    bool isRunning();
-    enum Resolution resolution() const  { return _res; };
+    bool     isRunning();
+    enum     Resolution resolution() const  { return _res; };
 
 private:
     enum State { RUNNING, STOPPED };

README.md

@@ -4,47 +4,75 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/CountDown/blob/master/LICENSE)
 [![GitHub release](https://img.shields.io/github/release/RobTillaart/CountDown.svg?maxAge=3600)](https://github.com/RobTillaart/CountDown/releases)
 
+
 # CountDown
 
 Arduino Library to implement a CountDown clock (in SW polling, no HW timer).
 
+
 ## Description
 
+The countdown library is a clock that counts down from a given time to zero.
+It does not call a function or so as the user is responsible to check the time remaining.
+Typically one checks the remaining time in every loop.
+
+UNder the hood the function uses **micros()** or **millis()** which results in a maximum time
+of 4294 seconds in micros (1h10m) or something like 49+ days when using millis.
+
+For longer periods one could cascade countDown, so when one is finished the next starts.
+
+
+## Interface
+
 The main functions of the CountDown clock are:
 
-- **void start(ticks);**
-- **void start(days, hours, minutes, seconds);**
-- **void start(days, hours, minutes);**
-- **void stop();**
-- **void cont();**  *(continue is a C-Keyword)*
-- **uint32_t remaining();**
-- **bool isRunning();**
+- **bool start(ticks)**
+- **bool start(days, hours, minutes, seconds)**
+- **bool start(days, hours, minutes)**
+- **void stop()**
+- **void cont()**  *(continue is a C-Keyword)*
+- **uint32_t remaining()**
+- **bool isRunning()**
 
 These functions work straightforward.
 
+
+## Operation
+
 The function **start(days, hours, minutes, seconds)** has changed its
 parameters type to minimize them, given that the total time may not exceed 2^32 milliseconds.
 This allows the user to call **start()** with e.g. four hundred minutes **start(0, 0, 400, 0)** 
 or a million seconds **start(0, 0, 0, 1000000)** as parameter.
-The resolution is implicitly set to *SECONDS*.
-
-Note: the function **start()** does not check if the parameters cause an overflow
-in the underlying math. That is responsibility of the user.
+The resolution is implicitly set to **SECONDS**.
 
-The function **start(days, hours, minutes)** is new since 0.2.2.
-It also uses **millis()** under the hood. The resolution is implicitly set to *MINUTES*.
+Since 0.2.4 the function **start()** will check if the parameters cause an overflow
+in the underlying math. If there is no overflow call to **start()** returns true. 
+If there is an overflow it returns false
 
 Total amount of time to countdown for **MICROS** may not exceed 2\^32 micros ~ 1hr 10 minutes.
 Total amount of time to countdown for **MILLIS**, **SECONDS** and **MINUTES**
 may not exceed 2\^32 millis  ~49 days
 
-## Operation
+
+The function **start(days, hours, minutes)** is new since 0.2.2.
+It also uses **millis()** under the hood. The resolution is implicitly set to **MINUTES**.
+
+
+| Call to start()                       | resolution       |  max time | comments |
+|:--------------------------------------|:-----------------|:---------:|:---------|
+| start(days, hours, minutes, seconds)  | SECONDS = millis |  49+ days |
+| start(days, hours, minutes)           | MINUTES = millis |  49+ days |
+| start(ticks)                          | MILLIS  = millis |  49+ days | default |
+| start(ticks)                          | MICROS  = micros |  ~70 min  | use setResolution(MICROS)  |
+| start(ticks)                          | SECONDS = millis |  49+ days | use setResolution(SECONDS) |
+| start(ticks)                          | MINUTES = millis |  49+ days | use setResolution(MINUTES) |
+
 
 The Countdown clock uses by default **millis()** to do the time keeping,
 although this can be changed runtime by **setResolution(res)**. The parameter 
 **res** can be:
 - **MICROS**
-- **MILLIS**
+- **MILLIS**   // default
 - **SECONDS**  // based upon millis()
 - **MINUTES**  // based upon millis()
 

library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/CountDown.git"
   },
-  "version":"0.2.3",
+  "version":"0.2.4",
   "frameworks": "arduino",
   "platforms": "*"
 }

library.properties

@@ -1,5 +1,5 @@
 name=CountDown
-version=0.2.3
+version=0.2.4
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library to implement a CountDown clock in SW.

test/unit_test_001.cpp

@@ -40,29 +40,45 @@ unittest_teardown()
 
 unittest(test_constructor)
 {
+  fprintf(stderr, "VERSION: %s\n", COUNTDOWN_LIB_VERSION);
+  
   CountDown a(CountDown::MINUTES);
   CountDown b(CountDown::SECONDS);
   CountDown c(CountDown::MILLIS);
   CountDown d(CountDown::MICROS);
+  CountDown e;  // default MILLIS
 
   assertEqual(CountDown::MINUTES, a.resolution());
   assertEqual(CountDown::SECONDS, b.resolution());
   assertEqual(CountDown::MILLIS,  c.resolution());
   assertEqual(CountDown::MICROS,  d.resolution());
+  assertEqual(CountDown::MILLIS,  e.resolution());
+
+  fprintf(stderr, "\nisRunning\n");
 
   assertFalse(a.isRunning());
   assertFalse(b.isRunning());
   assertFalse(c.isRunning());
   assertFalse(d.isRunning());
+  assertFalse(e.isRunning());
 
-  a.start(10);
+  fprintf(stderr, "\nbase\n");
+  
+  a.setResolution(CountDown::SECONDS);
+  assertTrue(a.start(10));
   assertTrue(a.isRunning());
+
   a.stop();
   assertFalse(a.isRunning());
+
   a.cont();
   assertTrue(a.isRunning());
+
   a.stop();
   assertFalse(a.isRunning());
+
+  assertTrue(a.start(0));
+  assertFalse(a.isRunning());
 }
 
 
@@ -87,6 +103,25 @@ unittest(test_run)
 
 }
 
+
+unittest(test_overflow)
+{
+  CountDown cd;
+  assertEqual(CountDown::MILLIS,  cd.resolution());
+
+  assertFalse(cd.isRunning());
+  assertFalse(cd.start(50, 0, 0));
+  assertFalse(cd.start(50, 0, 0, 0));
+
+  assertFalse(cd.start(0, 1200, 0));
+  assertFalse(cd.start(0, 1200, 0, 0));
+
+  assertFalse(cd.start(0, 0, 72000));
+  assertFalse(cd.start(0, 0, 72000, 0));
+
+  assertFalse(cd.start(0, 0, 0, 4320000));
+}
+
 unittest_main()
 
 // --------