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 reused from other Arduino libraries in my collection.

All functions and classes are accessible through a single include file <AceCommon.h> and the ace_common namespace:

#include <AceCommon.h>
using namespace ace_common;

The src/AceCommon.h header file includes the following sub-header files automatically:

• src/arithmetic/arithmetic.h
  • void incrementMod(T& c, T m)
  • void incrementModOffset(T&c, T m, T offset)
  • uint8_t decToBcd(uint8_t)
  • uint8_t bcdToDec(uint8_t)
  • unsigned long udiv1000(unsigned long)
• src/pstrings/pstrings.h
  • int strcmp_PP(const char* a, const char* b)
  • const char* strchr_P(const char* s, char c) (ESP8266 and ESP32 only)
  • const char* strrchr_P(const char* s, char c) (ESP8266 and ESP32 only)
• src/print_str/PrintStr.h
  • src/print_str/README.md
    • Provides classes that implement the Print interface so that values can be printed into in-memory buffers. The string can then be extracted as a normal c-string (const char*).
    • Alternative to the Arduino String class to avoid or reduce heap fragmentation.
  • class PrintStrBase
  • class PrintStr<uint16_t SIZE> (buffer on stack)
  • class PrintStrN(uint16_t size) (buffer on heap)
• src/print_utils/printPadTo.h
  • src/print_utils/README.md
  • void printPad2To(Print& printer, uint16_t val, char pad = ' ')
  • 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/README.md
    • Provides a primitive printf() functionality to an instance of Print (e.g. Serial) for those Arduino boards without a Print.printf() function.
  • void printfTo(Print& printer, const char* fmt, ...)
• src/timing_stats/TimingStats.h
  • src/timing_stats/README.md
    • Helper class to collect data (often durations in milliseconds) and then print out various statistics such as min, max, average, and count.
  • class TimingStats
• src/url_encoding/url_encoding.h
  • src/url_encoding/README.md
    • Encodes and decodes strings using "form URL encoding" which converts spaces ' ' into '+', and non-alphnumerics into percent-hex digits.
  • void formUrlEncode(Print& output, const char* str)
  • void formUrlDecode(Print& output, const char* str)
• src/fstrings/FCString.h
  • class FCString
  • An object that can hold either a C-string (const char*) or an F-string (const __FlashStringHelper*).
• src/hash/djb2.h
  • The djb2 hash algorithm as described in https://stackoverflow.com/questions/7666509 and http://www.cse.yorku.ca/~oz/hash.html.
  • uint32_t hashDjb2(const char* s)
  • uint32_t hashDjb2(const __FlashStringHelper* fs)
• src/kstrings/KString.h
  • Wrapper around a c-string or an f-string which supports compression using keyword substitution from a dictionary. Up to 31 keywords supported.
  • class KString
• src/algorithms/binarySearch.h
  • src/algorithms/README.md
  • size_t binarySearchByKey(size_t size, const X& x, K&& key)
  • size_t binarySearch(const X list[], size_t size, const X& x)
    • Templatized binary search of array of records or array of elements.
• src/algorithms/linearSearch.h
  • src/algorithms/README.md
  • size_t linearSearchByKey(size_t size, const X& x, K&& key)
  • size_t linearSearch(const X list[], size_t size, const X& x)
    • Templatized linear search of array of records or array of elements.
• src/algorithms/isSorted.h
  • src/algorithms/README.md
  • size_t isSortedByKey(size_t size, K&& key)
  • size_t isSorted(const X list[], size_t size)
    • Determine if array is sorted or not.
• 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
  • 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/README.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.3 (2021-02-18)

Changelog: CHANGELOG.md

The latest stable release is available in the Arduino IDE Library Manager. Search for "AceCommon". Click install.

The development version can be installed by cloning the GitHub repository (https://github.com/bxparks/AceCommon), checking out the develop branch, then manually copying over the contents to the ./libraries directory used by the Arduino IDE. (The result is a directory named ./libraries/AceCommon.)

The master branch contains the tagged stable releases.

The core of this library will never depend on any external dependencies so that it can be easily reused by other libraries (e.g. AceTime, AceButton, AceRoutine, etc).

The unit tests under tests/ depend on:

• AUnit (https://github.com/bxparks/AUnit)

The unit tests can be executed on Linux or MacOS using:

• EpoxyDuino (https://github.com/bxparks/EpoxyDuino)

The source files are organized as follows:

• src/AceCommon.h - main header file
• src/*/ - implementation files
• tests/ - unit tests which require 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

• README.md - this file
• Doxygen docs published on GitHub Pages

The library has been extensively tested on the following boards:

• Arduino Nano clone (16 MHz ATmega328P)
• SparkFun Pro Micro clone (16 MHz ATmega32U4)
• SAMD21 M0 Mini (48 MHz ARM Cortex-M0+)
• STM32 Blue Pill (STM32F103C8, 72 MHz ARM Cortex-M3)
• NodeMCU 1.0 (ESP-12E module, 80MHz ESP8266)
• WeMos D1 Mini (ESP-12E module, 80 MHz ESP8266)
• ESP32 Dev Module (ESP-WROOM-32 module, 240MHz dual core Tensilica LX6)
• Teensy 3.2 (96 MHz ARM Cortex-M4)

I will occasionally test on the following boards as a sanity check:

• Arduino Pro Mini clone (16 MHz ATmega328P)
• 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)

This library was developed and tested using:

• Arduino IDE 1.8.13
• Arduino CLI 0.14.0
• Arduino AVR Boards 1.8.3
• Arduino SAMD Boards 1.8.9
• SparkFun AVR Boards 1.1.13
• SparkFun SAMD Boards 1.8.1
• STM32duino 1.9.0
• ESP8266 Arduino Core 2.7.4
• ESP32 Arduino Core 1.0.4
• Teensyduino 1.53

It should work with PlatformIO but I have not tested it.

The library works on Linux or MacOS (using both g++ and clang++ compilers) using the EpoxyDuino emulation layer.

I use Ubuntu Linux 18.04 and 20.04 for most of my development.

MIT License

If you find this library useful, consider starring this project on GitHub. The stars will let me prioritize the more popular libraries over the less popular ones.

If you have any questions, comments, bug reports, or feature requests, please file a GitHub ticket instead of emailing me unless the content is sensitive. (The problem with email is that I cannot reference the email conversation when other people ask similar questions later.) I'd love to hear about how this software and its documentation can be improved. I can't promise that I will incorporate everything, but I will give your ideas serious consideration.

Created by Brian T. Park ([email protected]).