add csi() - add comma separated integers (#18)

- added **csi()** comma separated integers for readability e.g. 123,458,654
- update readme.md.
- update examples

CHANGELOG.md

@@ -6,11 +6,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.3] - 2023-11-15
+- added **csi()** comma separated integers for readability e.g. 123,458,654
+- update readme.md.
+- update examples
+
+
 ## [0.4.2] - 2023-11-15
 - update readme.md
 - update keywords.txt
 
-
 ## [0.4.1] - 2023-07-13
 - fix #16  signed/unsigned warning
 - update example **print_toRoman.ino** to print 1..5000

README.md

@@ -29,8 +29,9 @@ data in a way not possible in the standard print library of the Arduino.
 - **toRoman()** generates a ROMAN representation of a (positive) number.
 - **printInch(float inch, uint16_t step)** experimental.
 - **printFeet(float feet)** experimental.
+- **csi()** generates a comma separated integer for readability.
 
-Details, see below.
+For the details, see sections below.
 
 If a (generic) print format is missing, please open an issue.
 
@@ -220,6 +221,35 @@ The parameter step must be a power of 2 == 2, 4, 8, 16, 32, 64, 128.
 ``` a'b"``` e.g. 4.5 feet prints as ```4'6"```
 
 
+#### Comma Separated Integer
+
+Experimental 0.4.3
+
+When you are working with large numbers, more than lets say 6 digits.
+With these numbers it is often difficult to see if it is 2 million something or 20 million something. 
+A proven way to solve this is to print those large numbers in groups of 3 digits separated by comma's.
+This improves the readability a lot and yes the price is more room needed on a display.
+The comma is chosen as it is default thousands separator in Excel.
+
+In the first version the separator is hardcoded a ",", in future it might be configurable.
+This new printHelper function can work with both signed and unsigned up to 64 bit numbers.
+Like all printHelper functions it uses a shared print buffer to keep memory usage low.
+
+Example 192837465 becomes 192,837,465.
+
+signed
+- **char \* csi(int64_t n)** 
+- **char \* csi(int32_t n)** 
+- **char \* csi(int16_t n)** 
+- **char \* csi(int8_t n)**
+
+unsigned
+- **char \* csi(uint64_t n)** 
+- **char \* csi(uint32_t n)** 
+- **char \* csi(uint16_t n)** 
+- **char \* csi(uint8_t n)**
+
+
 ## Shared print buffer
 
 The implementation of the function all use a shared buffer to hold the 
@@ -271,6 +301,10 @@ When functions are added, the recommended minimum size might increase.
 - optimize **char \* hex(uint8_t / uint16_t ...)**
 - make this library a .h file only?
 - PRINTHELPERS_LIB_VERSION
+- is there need for Scientific or Engineering integers
+  - 23.457e3 only positive powers
+  - could be without float math
+  - 4 versions (un)signed 32/64 ?
 
 #### Wont
 

examples/print64/print64.ino

@@ -18,6 +18,10 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
+
   delay(100);
 
   Serial.println("BASE\tTIME  base < 10 support depends on internal buffer size");

examples/print_comma_separated_integers/print_comma_separated_integers.ino

@@ -0,0 +1,44 @@
+//    FILE: print_comma_separated_integers.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+//    DATE: 2023-12-20
+// PURPOSE: demo readability
+//     URL: https://github.com/RobTillaart/printHelpers
+
+#include "Arduino.h"
+#include "printHelpers.h"
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial);
+  Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+
+  Serial.println((int32_t)123456789);
+  Serial.println(csi((int32_t)123456789));
+  Serial.println(csi((int32_t)-123456789));
+  Serial.println(csi((int32_t)12345678));
+  Serial.println(csi((uint32_t)1234567));
+  Serial.println(csi((int16_t)-12345));
+  Serial.println(csi((int16_t)1234));
+  Serial.println(csi((uint8_t)123));
+  Serial.println(csi((int8_t)12));
+  Serial.println(csi((int32_t)-1));
+
+  int64_t big = 123456789012345678;
+  Serial.println(csi(big));
+}
+
+void loop()
+{
+  uint64_t large = 0;
+  for (int i = 0; i < 64; i++)
+  {
+    large += random(2);
+    large *= 2;
+  }
+}
+
+// -- END OF FILE --

examples/print_hex_bin/print_hex_bin.ino

@@ -13,6 +13,9 @@ void setup()
   Serial.begin(115200);
   Serial.println();
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   Serial.println();
   uint8_t  a = 111;

examples/print_inch_feet/print_inch_feet.ino

@@ -12,6 +12,7 @@ void setup()
   Serial.println(__FILE__);
   Serial.print("PRINTHELPERS_VERSION: ");
   Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   //  test some random values
   for (float inch = 0; inch < 100; inch += 5.43)

examples/print_performance/performance_0.4.3.txt

@@ -0,0 +1,67 @@
+
+Arduino UNO
+IDE 1.8.19
+
+print_performance.ino
+D:\Rob\WORK\Arduino\libraries\printHelpers\examples\print_performance\print_performance.ino
+PRINTHELPERS_VERSION: 0.4.3
+
+4
+4
+
+     Mass moon M = 7.34767309E+20
+Speed of light c = 2.99792458E+8
+         Print E = Mc^2 = 6.6037592413026551656653076E+37 
+
+
+
+print64
+TIME: 22476
+660375892052148224
+
+SCI
+TIME: 9236
+6.603759288787841E+17
+
+ENG
+TIME: 7388
+660.375976562500000E+15
+
+dtostrf
+TIME: 2468
+660375890000000000.000000000000000
+
+dtostre
+TIME: 1452
+6.6037589e+17
+
+toBytes
+TIME: 1976
+586.531 PB
+
+hex
+TIME: 1308
+092A206000000000
+
+bin
+TIME: 2464
+0000100100101010001000000110000000000000000000000000000000000000
+
+toRoman
+TIME: 89352
+CMXCIX
+
+printInch
+TIME: 177312
+999 0/16
+
+printFeet
+TIME: 137448
+999"0'
+
+CSI
+TIME: 3015752
+1,234,567,890,987,654,321
+1234567890987654321
+
+done...

examples/print_performance/print_performance.ino

@@ -15,6 +15,7 @@ void setup()
   Serial.println(__FILE__);
   Serial.print("PRINTHELPERS_VERSION: ");
   Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   Serial.println(sizeof(float));
   Serial.println(sizeof(double));
@@ -192,6 +193,24 @@ void setup()
   Serial.println(b);
   delay(100);
 
+
+  Serial.println();
+  Serial.println("CSI");
+  volatile uint64_t big = 1234567890987654321;
+  delay(100);
+  start = micros();
+  for (int i = 0; i < 1000; i++)
+  {
+    b = csi(big);
+  }
+  stop = micros();
+  Serial.print("TIME: ");
+  Serial.println(stop - start);
+  Serial.println(csi(big));
+  Serial.println(print64(big));
+  delay(100);
+
+
   Serial.println();
   Serial.println("done...");
 }

examples/print_sci/print_sci.ino

@@ -10,6 +10,9 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   Serial.println(sizeof(float));
   Serial.println(sizeof(double));

examples/print_sci_experimental/print_sci_experimental.ino

@@ -11,6 +11,9 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   Serial.println(sizeof(float));
   Serial.println(sizeof(double));

examples/print_toRoman/print_toRoman.ino

@@ -11,6 +11,9 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   Serial.println(sizeof(float));
   Serial.println(sizeof(double));

examples/sci_test/sci_test.ino

@@ -13,6 +13,9 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
 
   test1();
   test2();

examples/toBytes/toBytes.ino

@@ -13,7 +13,11 @@ void setup()
 {
   Serial.begin(115200);
   Serial.println(__FILE__);
-  delay(10);
+  Serial.print("PRINTHELPERS_VERSION: ");
+  Serial.println(PRINTHELPERS_VERSION);
+  Serial.println();
+
+  delay(100);
 
   Serial.println("20 random() values");
   for (uint8_t i = 0; i < 20; i++)

keywords.txt

@@ -20,6 +20,8 @@ toRoman	KEYWORD2
 printInch	KEYWORD2
 printFeet	KEYWORD2
 
+csi	KEYWORD2
+
 
 # Constants (LITERAL1)
 PRINTHELPERS_VERSION	LITERAL1

library.json

@@ -1,7 +1,7 @@
 {
   "name": "printHelpers",
   "keywords": "Convert,int64,uint64,print,scientific,notation,toBytes,HEX,BIN,Roman",
-  "description": "Arduino library to help printing. int64 and uint64 support base 10 (DEC) and 16 (HEX). Scientific notation of floats. Feet and inch.",
+  "description": "Arduino library to help printing. int64 and uint64 support base 10 (DEC) and 16 (HEX). Scientific notation of floats. Feet and inch. Comma separated integers.",
   "authors":
   [
     {
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/printHelpers"
   },
-  "version": "0.4.2",
+  "version": "0.4.3",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

library.properties

@@ -1,9 +1,9 @@
 name=printHelpers
-version=0.4.2
+version=0.4.3
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library to help formatting data for printing. 64 bit integers (base 10 and 16). Engineering and scientific notation.
-paragraph=Supports 64 bit integers (base 10 and 16). Engineering and scientific notation. toBytes() for KB MB, HEX and BIN, Roman numbers. Feet and inch.
+paragraph=Supports 64 bit integers (base 10 and 16). Engineering and scientific notation. toBytes() for KB MB, HEX and BIN, Roman numbers. Feet and inch. Comma separated integers.
 category=Other
 url=https://github.com/RobTillaart/printHelpers
 architectures=*