ustd provides minimal and highly portable implementations of the following classes:

ustd::array, a lightweight c++11 array implementation (ustd_array.h).
ustd::queue, a lightweight c++11 queue implementation (ustd_queue.h).
ustd::map, a lightweight c++11 map implementation (ustd_map.h).

The libraries are header-only and should work with any c++11 compiler and support platforms starting with 8k attiny, avr, arduinos, up to esp8266, esp32 and mac and linux.

ustd_functional.h provides a drop-in replacement for std::function<> for AVRs: ustd::function<> for low-resource AVRs (see project functional-avr)

Documentation: ustd:: documentation

Platform defines

Make sure to use the appropriate platform define before including from ustd.

Platform	`#define` (by user)	Comment
ATtiny	`__ATTINY__`	For very low resource ATMELs
Arduino	`__UNO__`	Should work with low resource arduinos
Arduino	`__ATMEGA__`	Should work with most arduinos
FeatherM0	`__FEATHER_M0__`	Adafruit feather M0 (Wifi)
RP PICO	`__RP2040__`	Raspberry Pi PICO RP2040
FeatherM4	`__FEATHER_M4__`	Adafruit feather M4 (Wifi)
STM32	`__BLUEPILL__`	STM32F103C8T6 ARM Cortex-M3
STM32	`__BLACKPILL__`	STM32F411 ARM Cortex-M4
NRF52	`__NRF52__`	Feather NRF52832 Cortex-M4
Teensy40	`__TEENSY40__`	Teensy 4.0 Cortex-M7
Nano33BLE	`__NANOBLE__`	Arduino Nano 33 BLE (Sense) nRF52840
ESP8266	`__ESP__`	For ESP8266 and ESP32
ESP32	`__ESP32__`	ESP32
ESP32-C3	`__ESP32_RISC_`	ESP32-C3 (RISC-V)
ESP32DEV	`__ESP32DEV__`	ESP32 git head
Maix Bit	`__MAIXBIT__`	Sipeed Maix Bit RISC-V
Mac	`__APPLE__`	Should be defined already
Linux	`__linux__`	Should be defined already

Note: If the desired MCU is not in that list, select one with similar characteristics, these platform defines are used to generate feature-lists that are used by muwerk's modules.

Additional selectable options

Option	Comment
`USTD_OPTION_FS_FORCE_SPIFFS`	to continue to use old SPIFFS instead of LittleFS. New default for ESP8266 is LittleFS.
`USTD_OPTION_FS_FORCE_NO_FS`	Disable all filesystem related functionality
`USTD_OPTION_FS_FORCE_LITTLEFS`	switch to LittleFS on ESP32 (currently SPIFFS is still used as default for tensilica-based ESPs for compatibility reasons). New ESP32 cores have LittleFS support. For ESP32_RISC cores (e.g. ESP32-C3), LITTLEFS is ALWAYS used, since there is no legacy.

Defines generated by `ustd_platform.h` depending on the platform define above

Note: All defines below are automatically generated, they are derived from the platform define above:

Family defines

Platform define	Automatically defined family	Comment
`__UNO__`	`__ARDUINO__`	8-bit Atmel Arduinos
`__MEGA__`	`__ARDUINO__`	"
`__FEATHER_MO__`	`__ARM__`	ARM cortex
`__RP2040__`	`__ARM__`, `__RP_PICO__`	"
`__FEATHER_M4__`	`__ARM__`	"
`__BLUEPILL__`	`__ARM__`	"
`__BLACKPILL__`	`__ARM__`	"
`__NRF52__`	`__ARM__`	"
`__TEENSY40__`	`__ARM__`	"
`__NANOBLE__`	`__ARM__`	"
`__ESP__`	`__TENSILICA__`	Espressif Tensilica
`__ESP32__`	`__TENSILICA__`	"
`__ESPDEV__`	`__TENSILICA__`	"
`__ESP32_RISC__`	`__RISC_V__`	RISC-V ESP32-C3
`__MAIXBIT__`	`__RISC_V__`	RISC-V based MCUs
`__APPLE__`	`__UNIXOID__`	macOS computer
`__linux__`	`__UNIXOID__`	Linux computer

Features

Define	Comment
`USTD_FEATURE_MEMORY`	This is set to a class of available memory, see below for possible values.
`USTD_FEATURE_FILESYSTEM`	The system has a filesystem, muwerk APIs defined in `filesystem.h` and `jsonfile.h` are available.
`USTD_FEATURE_FS_SPIFFS`	Filesystem is SPIFFS format (legacy ESP8266 and all ESP32 with tensilica cores)
`USTD_FEATURE_FS_LITTLEFS`	Filesystem is LittleFS (standard for ESP8266 and ESP32C3 RISC-V)
`USTD_FEATURE_FS_SD`	Future: SD Filesystem
`USTD_FEATURE_EEPROM`	Platform has EEPROM storage
`USTD_FEATURE_SYSTEMCLOCK`	System has a clock
`USTD_FEATURE_CLK_READ`	Time can be read
`USTD_FEATURE_CLK_SET`	Time can be set
`USTD_FEATURE_NETWORK`	Network access available
`USTD_FEATURE_FREE_MEMORY`	freeMemory() is available
`USTD_FEATURE_SUPPORTS_NEW_OPERATOR`	Platform SDK has it's own `new` operator

Possible values for `USTD_FEATURE_MEMORY`

(Automatically derived by ustd_platform.h from platform define __xxx__)

Value	Example platform
`USTD_FEATURE_MEM_512B`	ATtiny85
`USTD_FEATURE_MEM_2K`	Arduino UNO, ATtiny1614, AT328P
`USTD_FEATURE_MEM_8K`	Arduino MEGA
`USTD_FEATURE_MEM_32K`	ESP8266, Bluepill, Cortex M0, M3, M4F
`USTD_FEATURE_MEM_128K`	Blackpill, ESP32
`USTD_FEATURE_MEM_512K`
`USTD_FEATURE_MEM_1M`	Unixoids & RISC-V

To make code dependent on a memory-class, use something like:

 {c++}
#if USTD_FEATURE_MEMORY >= USTD_FEATURE_MEM_2K
// Feature that requires at least 2k RAM
#endif

Example

 {c++}
// first a platform define (see table above):
#define __ESP32__
#include "ustd_array.h"
 
const int ci[]={1,2,3,4,5};
ustd::array<int> ia(ci,5);
for (auto i : ia) {
    printf("%d\n",i);
}

Installation

ustd is available via Arduino library manager or platformio:

Arduino ustd
Platformio ustd, library ID 5710.

Complete example

See Examples for a complete build example with ustd and linux, Arduino-IDE or platformio.

Related projects

ustd is used by muwerk to implement a portable cooperative scheduler with MQTT-like communication queues.

History

0.7.4 (2022-10-17) Support for ESP32-C3 (RISC-V), tested with Adafruit QTPY ESP32-C3, platform define __ESP32_RISC__. 'Legacy' ESPs automatically define family __TENSILICA__, whereas the new RISC-V based chip defines family __RISC_V__. Note: __ESP32_RISC__ always uses LittleFS!
0.7.3 (2022-08-26) Minimal doc fixes.
0.7.2 (2022-08-04) New option USTD_OPTION_FORCE_LITTLEFS for ESP32. Switches to LittleFS for new cores. For compatibility reasons currently default file system for ESP32 is still SPIFFS.
0.7.1 (2022-05-03) Teensy 4.0 support (#20, thanks @SteveEisner).
0.7.0 (2021-10-19) Slight breaking change in array-read handling: Earlier versions allowed read-operations to grow (thus mutating) the array, if the array was initialized as growing. Changed via #17, thanks @mzanetti.
0.6.2 (2021-06-07) Support multiple inclusion of global operators / functions in one submodule (Thanks @mo22, #13)
0.6.1 (2021-02-26) Initial Raspberry PICO rp2040 support.
0.6.0 (2021-02-09) New platforms, iterator and copy-constructor support.
- Support for iterators and copy-constructors in ustd::array, ustd::queue, and ustd::map. (Thanks proddy for iterator sample implementation.)
- Platforms: Feather M4 added: __FEATHER_M4__
- Blackpill STM32F411 added.
- Arduino Nano 33 BLE added. Note: requires platformio's lib_ldf_mode = chain+ definition in platform.ini, otherwise platformio will get confused about including WiFi.h, because of faulty #ifdef parsing of ustd_platformio.h.
- ASSERT() macros removed due to clashes.
0.5.0 (2021-01-30) BREAKING CHANGE: In order to prevent name-clashes for include-files for Arduino-IDE users, all ustd include files now have an ustd_ prefix. Compatibility-versions without ustd_ that include the ustd_ versions are provided, with exception of queue.h (clash with ESP8266-Wifi) and platform.h (clash with RISC-V sdk).
CI (2021-01-28) Use Github actions to test build for all platform defines.
0.4.4 (2021-01-25) Missing USTD_FEATURE_FILESYSTEM defines for ESPs added.
0.4.2 (2021-01-24) New platforms __FEATHER_M0__ (ARM Cortex M0), __BLUEPILL__ (ARM Cortex M3), __NRF42__ (ARM Cortex M4F), __MAIXBIT__ (RISC-V). Bugfix for zero-initialisation of array, map, and queue (no longer uses memset).
0.4.1 (2021-01-22) Bugfix for USTD_FEATURE_MEMORY handling. ATtiny no longer supports ustd::function<>.
0.4.0 (2021-01-19) Feature defines in ustd_platform.h for better hardware specific adaptations.
0.3.6 (2021-01-12) Support for UNO and MEGA in functional.h via __ARDUINO__ define.
0.3.5 (2021-01-12) New function freeMemory(), new platform define __UNO__. (Both __UNO__ and __ATMEGA__ implicitly define __ARDUINO__)
0.3.4 (2021-01-11) Small documentation fixes.
0.3.3 (2021-01-08) ustd::array::resize() did not correctly update the array size, which would lead to memory corrupts (tuxpoldo). Improvements for debug macros.
0.3.2 (2021-01-07) More consistent debug interface using DBG() macros (see ustd_platform.h), fixes to USTD_ASSERT macro that was inconsistently named ASSERT*S*.
0.3.1 (2020-12-25) More SPIFFS vs LittleFS preparations
0.3.0 (2020-10-26) Cleanup ustd_platform.h: ESP32 continues to use SPIFFS by default, ESP8266 LittleFS (since SPIFFS is deprecated for ESP8266, and LittleFS is not (yet) available for ESP32). This is a breaking change for ESP8266 installations that require the filesystem, since an upgrade from SPIFFS to LittleFS is required, see munet Readme for additional information.
0.2.2 (2020-09-27) Support for LittleFS as successor of ESP8266/ESP32 filesystem
0.2.1 (2019-09-19) Functional support for AVRs added (from project functional-avr by winterscar).

References

ustd_functional.h is taken from project functional-avr by winterscar
ustd and muwerk are derivatives and lightweight versions of Meisterwerk.