Streaming

Library Information

Name

Streaming

Version

6.2.4

License

GNU LGPL 2.1 or later

URL

https://github.com/janelia-arduino/Streaming

Authors

Mikal Hart, gazoodle, victorh800, sebdelsol, Peter Polidoro

Maintainer

Peter Polidoro

Email

peter@polidoro.io

Description

Header-only Arduino streaming helpers for Print-derived outputs such as Serial. The library adds C++-style << output plus helper wrappers for base conversion, padding, width control, float formatting, lightweight format-string replacement, and comma-separated values.

See CHANGELOG.md for recent repository and workflow updates.

Quick Start

#include <Streaming.h>

void setup() {
  Serial.begin(115200);

  int day = 17;
  int month = 4;
  int year = 2009;

  Serial << "The current date is " << _WIDTHZ(day, 2) << "-"
         << _WIDTHZ(month, 2) << "-" << year << endl;
}

Stream Helpers

Available helpers:

• _DEC(value)
• _BIN(value)
• _HEX(value)
• _OCT(value)
• _BYTE(value)
• _FLOAT(value, digits)
• _PAD(width, fill)
• _WIDTH(value, width)
• _WIDTHZ(value, width)
• _FLOATW(value, digits, width)
• _FMT(format, ...)
• endl

Representative usage:

const int lettera = 'A';
const int month = 4, day = 17, year = 2009;
const int hour = 8, minute = 20, second = 3;
const float pi = 3.14159;

Serial << "This is an example of the new streaming" << endl;
Serial << "library.  This allows you to print variables" << endl;
Serial << "and strings without having to type line after" << endl;
Serial << "line of Serial.print() calls.  Examples: " << endl;

Serial << "A is " << lettera << "." << endl;
Serial << "The current date is " << day << "-" << month << "-" << year << "."
       << endl;

Serial << "You can use modifiers too, for example:" << endl;
Serial << _BYTE(lettera) << " is " << _HEX(lettera) << " in hex. " << endl;
Serial << endl;

Serial << "In library v6, you also get" << endl;
Serial << "Padding [" << _PAD(10, '*') << "]" << endl;
Serial << "Width specification [" << _WIDTH(10, 5) << "]" << endl;
Serial << "Leading zeros [" << _WIDTHZ(month, 2) << "]" << endl;
Serial << _FMT("Format strings for stuff like dates and times %/%/% %:%:%",
               _WIDTHZ(day, 2), _WIDTHZ(month, 2), year, _WIDTHZ(hour, 2),
               _WIDTHZ(minute, 2), _WIDTHZ(second, 2))
       << endl;
Serial << _FMT(F("To reduce your % size, these % can be in %"), F("sketch"),
               F("constants"), F("PROGMEM"))
       << endl;
Serial << endl;

Serial << "pi to 3 digits = " << _FLOAT(pi, 3) << endl;

// comma separator
int f = 11;
Serial << "Data: " << 1, 3, 5, 7, 9, f;
Serial << endl;
Serial << "comma separator works!" << endl;

Examples

• examples/StreamingExample/StreamingExample.ino
• examples/StreamingTests/StreamingTests.ino
• examples/FormattingHelpers/FormattingHelpers.ino

Build and Test

Preferred local workflow with Pixi:

pixi install
pixi run pio-version
pixi run check-format
pixi run test
pixi run build examples/StreamingExample teensy41
pixi run build examples/StreamingTests teensy41
pixi run build examples/FormattingHelpers teensy41
pixi run release-check

Pixi keeps the pio CLI and its Python runtime local to the repository. The build, upload, flash, and rebuild tasks select examples without editing platformio.ini.

Useful commands:

pixi run ports
pixi run format
pixi run build examples/StreamingExample uno
pixi run build examples/FormattingHelpers teensy41
pixi run upload examples/StreamingExample teensy41 /dev/ttyACM0
pixi run monitor /dev/ttyACM0 115200
pixi run set-version -- 6.2.3

Equivalent direct commands without Pixi:

make native-test
python3 tools/clang_format.py check
python3 tools/version_sync.py check
python3 tools/pio_task.py build --example examples/StreamingExample --env teensy41
python3 tools/pio_task.py build --example examples/StreamingTests --env teensy41
python3 tools/pio_task.py build --example examples/FormattingHelpers --env teensy41
python3 tools/pio_task.py upload --example examples/StreamingExample --env teensy41 --port /dev/ttyACM0

Release Checklist

Before tagging a release:

• Update CHANGELOG.md.
• Sync version metadata with python3 tools/version_sync.py set X.Y.Z.
• Run pixi run check-format.
• Run make native-test.
• Run pixi run release-check.
• Commit, tag, and push the release.

Caveats

• There may be issues using this library with some STL features.
• The esp8266 Arduino core declares several “Stream& operator <<” in StreamDev.h and defines them in StreamSend.cpp. If you wish to use this library with the esp8266, you may need to comment out those lines in StreamDev.h and StreamSend.cpp.

Original Source by Mikal Hart

http://arduiniana.org/libraries/streaming/