Merge pull request #16 from bxparks/develop

merge v1.4.4 into master

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
 * Unreleased
+* 1.4.4
+    * Add `copyReplaceChar()` and `copyReplaceString()` functions. Extracted
+      from AceTime library.
+    * Add `printReplaceCharTo()` and `printReplaceStringTo()` functions.
+    * Add [examples/MemoryBenchmark](examples/MemoryBenchmark) to track the
+      flash sizes of various components within this library.
+    * Add `FlashString` class which is a very thin-wrapper around a
+      `const __FlashStringHelper*` pointer, to make it look and act like a
+      normal `const char*` pointer.
+        * Solves code duplication problem when writing functions that need to
+          support both c-strings and f-strings.
+        * First write the function against a generic `T` type that is
+          assumed to be a type that acts like a `const char*`. Use this for a
+          c-string.
+        * Second write a template specialization that takes a `const
+          __FlashStringHelper*`, wraps the pointer into a `FlashString`,
+          and then forwards the call to the generic template function.
 * 1.4.3 (2021-02-18)
     * Add `linearSearch()` and `linearSearchByKey()`. Analogs to the
       corresponding binary search functions.

README.md

@@ -1,6 +1,6 @@
 # AceCommon
 
-![AUnit Tests](https://github.com/bxparks/AceCommon/workflows/AUnit%20Tests/badge.svg)
+[![AUnit Tests](https://github.com/bxparks/AceCommon/actions/workflows/aunit_tests.yml/badge.svg)](https://github.com/bxparks/AceCommon/actions/workflows/aunit_tests.yml)
 
 An Arduino library containing small, low-level functions and routines which have
 no dependencies to any other external libraries so that they can be easily
@@ -43,7 +43,7 @@ automatically:
     * `void printPad3To(Print& printer, uint16_t val, char pad = ' ')`
     * `void printPad4To(Print& printer, uint16_t val, char pad = ' ')`
     * `void printPad5To(Print& printer, uint16_t val, char pad = ' ')`
-* [src/print_utils.printfTo.h](src/print_utils.printfTo.h)
+* [src/print_utils/printfTo.h](src/print_utils/printfTo.h)
     * [src/print_utils/README.md](src/print_utils/README.md)
         * Provides a primitive `printf()` functionality to an instance of
           `Print` (e.g. `Serial`) for those Arduino boards without a
@@ -90,8 +90,35 @@ automatically:
     * `size_t isSortedByKey(size_t size, K&& key)`
     * `size_t isSorted(const X list[], size_t size)`
         * Determine if array is sorted or not.
-
-**Version**: 1.4.3 (2021-02-18)
+* [src/cstrings/copyReplace.h](src/cstrings/copyReplace.h)
+    * Replace a character with another character or string and copy result to
+      destination.
+    * `void copyReplaceChar(char* dst, size_t dstSize, const char* src,
+      char oldChar, char newChar)`
+    * `void copyReplaceString(char* dst, size_t dstSize, const char* src,
+      char oldChar, const char* newString)`
+* [src/print_utils/printReplaceTo.h](src/print_utils/printReplaceTo.h)
+    * Print a string while replace a character with another character or another
+      string.
+    * `void printReplaceCharTo(
+      Print& printer, const char* src, char oldChar, char newChar)`
+    * `void printReplaceCharTo(
+      Print& printer, const __FlashStringHelper* src, char oldChar,
+      char newChar)`
+    * `void printReplaceStringTo(
+      Print& printer, const char* src, char oldChar, const char* newString)`
+    * `void printReplaceStringTo(
+      Print& printer, const __FlashStringHelper* src, char oldChar,
+      const char* newString)`
+* [src/fstrings/FlashString.h](src/fstrings/FlashString.h)
+    * [src/fstrings/README.md](src/fstrings/EADDME.md)
+    * `class FlashString`
+    * Wraps a `const __FlashStringHelper*` into an object that looks and acts
+      like a normal c-string pointer `const char*`.
+    * Allows template functions to be written once, then reused for a flash
+      string pointer `const __FlashStringHelper*`.
+
+**Version**: 1.4.4 (2021-04-02)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -130,6 +157,11 @@ The source files are organized as follows:
 * `src/*/` - implementation files
 * `tests/` - unit tests which require [AUnit](https://github.com/bxparks/AUnit)
 * `examples/` - example sketches
+* `examples/MemoryBenchmark`
+    * to gather the flash and static memory consumption of various functions
+      and classes
+    * to validate my intuition of memory consumption of these routines
+    * to detect unexpected changes in memory consumption
 
 ### Documentation
 
@@ -159,6 +191,11 @@ I will occasionally test on the following boards as a sanity check:
 * Mini Mega 2560 (Arduino Mega 2560 compatible, 16 MHz ATmega2560)
 * Teensy LC (48 MHz ARM Cortex-M0+)
 
+The following boards are *not* supported:
+
+* megaAVR (e.g. Nano Every)
+* SAMD21 boards w/ `arduino:samd` version >= 1.8.10 (e.g. MKRZero)
+
 ### Tool Chain
 
 This library was developed and tested using:

docs/doxygen.cfg

@@ -38,7 +38,7 @@ PROJECT_NAME           = "AceCommon"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.4.3
+PROJECT_NUMBER         = 1.4.4
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/html/AceCommon_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceCommon
-   &#160;<span id="projectnumber">1.4.3</span>
+   &#160;<span id="projectnumber">1.4.4</span>
    </div>
    <div id="projectbrief">Arduino library for low-level common functions and features with no external dependencies</div>
   </td>
@@ -120,12 +120,15 @@
 <div class="line"><a name="l00058"></a><span class="lineno">   58</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="binarySearch_8h.html">algorithms/binarySearch.h</a>&quot;</span></div>
 <div class="line"><a name="l00059"></a><span class="lineno">   59</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="isSorted_8h.html">algorithms/isSorted.h</a>&quot;</span></div>
 <div class="line"><a name="l00060"></a><span class="lineno">   60</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="linearSearch_8h.html">algorithms/linearSearch.h</a>&quot;</span></div>
-<div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160; </div>
-<div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;<span class="comment">// Version format: &quot;xx.yy.zz&quot; =&gt; xxyyzz (without leading 0)</span></div>
-<div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="preprocessor">#define ACE_COMMON_VERSION 10403</span></div>
-<div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;<span class="preprocessor">#define ACE_COMMON_VERSION_STRING &quot;1.4.3&quot;</span></div>
-<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160; </div>
-<div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;<span class="preprocessor">#endif</span></div>
+<div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="copyReplace_8h.html">cstrings/copyReplace.h</a>&quot;</span></div>
+<div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;<span class="preprocessor">#include &quot;<a class="code" href="printReplaceTo_8h.html">print_utils/printReplaceTo.h</a>&quot;</span></div>
+<div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;<span class="preprocessor">#include &quot;fstrings/FlashString.h&quot;</span></div>
+<div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160; </div>
+<div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;<span class="comment">// Version format: &quot;xx.yy.zz&quot; =&gt; xxyyzz (without leading 0)</span></div>
+<div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;<span class="preprocessor">#define ACE_COMMON_VERSION 10404</span></div>
+<div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;<span class="preprocessor">#define ACE_COMMON_VERSION_STRING &quot;1.4.4&quot;</span></div>
+<div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160; </div>
+<div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->
 <div class="ttc" id="abinarySearch_8h_html"><div class="ttname"><a href="binarySearch_8h.html">binarySearch.h</a></div></div>
 <div class="ttc" id="alinearSearch_8h_html"><div class="ttname"><a href="linearSearch_8h.html">linearSearch.h</a></div></div>
@@ -136,6 +139,8 @@
 <div class="ttc" id="aisSorted_8h_html"><div class="ttname"><a href="isSorted_8h.html">isSorted.h</a></div></div>
 <div class="ttc" id="aprintPadTo_8h_html"><div class="ttname"><a href="printPadTo_8h.html">printPadTo.h</a></div></div>
 <div class="ttc" id="aarithmetic_8h_html"><div class="ttname"><a href="arithmetic_8h.html">arithmetic.h</a></div></div>
+<div class="ttc" id="aprintReplaceTo_8h_html"><div class="ttname"><a href="printReplaceTo_8h.html">printReplaceTo.h</a></div></div>
+<div class="ttc" id="acopyReplace_8h_html"><div class="ttname"><a href="copyReplace_8h.html">copyReplace.h</a></div></div>
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated by &#160;<a href="http://www.doxygen.org/index.html">

docs/html/FCString_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceCommon
-   &#160;<span id="projectnumber">1.4.3</span>
+   &#160;<span id="projectnumber">1.4.4</span>
    </div>
    <div id="projectbrief">Arduino library for low-level common functions and features with no external dependencies</div>
   </td>

docs/html/FCString_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceCommon
-   &#160;<span id="projectnumber">1.4.3</span>
+   &#160;<span id="projectnumber">1.4.4</span>
    </div>
    <div id="projectbrief">Arduino library for low-level common functions and features with no external dependencies</div>
   </td>
@@ -95,8 +95,8 @@
 <div class="line"><a name="l00022"></a><span class="lineno">   22</span>&#160;<span class="comment">SOFTWARE.</span></div>
 <div class="line"><a name="l00023"></a><span class="lineno">   23</span>&#160;<span class="comment">*/</span></div>
 <div class="line"><a name="l00024"></a><span class="lineno">   24</span>&#160; </div>
-<div class="line"><a name="l00025"></a><span class="lineno">   25</span>&#160;<span class="preprocessor">#ifndef FSTRINGS_FCSTRING_H</span></div>
-<div class="line"><a name="l00026"></a><span class="lineno">   26</span>&#160;<span class="preprocessor">#define FSTRINGS_FCSTRING_H</span></div>
+<div class="line"><a name="l00025"></a><span class="lineno">   25</span>&#160;<span class="preprocessor">#ifndef ACE_COMMON_FCSTRING_H</span></div>
+<div class="line"><a name="l00026"></a><span class="lineno">   26</span>&#160;<span class="preprocessor">#define ACE_COMMON_FCSTRING_H</span></div>
 <div class="line"><a name="l00027"></a><span class="lineno">   27</span>&#160; </div>
 <div class="line"><a name="l00028"></a><span class="lineno">   28</span>&#160;<span class="comment">// Much of this copied from AUnit/src/aunit/FCString.h and Compare.h.</span></div>
 <div class="line"><a name="l00029"></a><span class="lineno">   29</span>&#160; </div>