0.2.0 Currency

Author: RobTillaart

libraries/Currency/.github/workflows/arduino-lint.yml

@@ -6,8 +6,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
-      - uses: arduino/arduino-lint-action@v1
+      - uses: actions/checkout@v5
+      - uses: arduino/arduino-lint-action@v2
         with:
           library-manager: update
           compliance: strict

libraries/Currency/.github/workflows/arduino_test_runner.yml

@@ -8,7 +8,7 @@ jobs:
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

libraries/Currency/.github/workflows/jsoncheck.yml

@@ -5,13 +5,15 @@ on:
     paths:
       - '**.json'
   pull_request:
+    paths:
+      - '**.json'
 
 jobs:
   test:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: json-syntax-check
         uses: limitusus/json-syntax-check@v2
         with:

libraries/Currency/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.0] - 2025-11-25
+- fix derived functions (symbols).
+- add "acronym"-wrappers e.g. USD(value) and USD64(value)
+- deprecated the float/double API
+- renamed CURRENCY_LIB_VERSION
+- update GitHub actions
+- minor edits
+
+----
+
 ## [0.1.9] - 2024-04-11
 - update GitHub actions
 - minor edits
@@ -32,7 +42,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - minor edits.
 
 ## [0.1.2] - 2021-10-20
-- update build-CI + badges 
+- update build-CI + badges
 - adde pound
 - rename roubles
 ## [0.1.1] - 2021-05-27

libraries/Currency/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2024 Rob Tillaart
+Copyright (c) 2021-2025 Rob Tillaart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

libraries/Currency/README.md

@@ -18,30 +18,60 @@ Arduino library to help formatting integers for printing as currency.
 
 **Experimental**
 
-The currency library contains a number of functions that help to print 
+The currency library contains a number of functions that help to print
 integers as currency.
 
 The currency functions assume you do the currency math in integer units.
-For dollars and euro's this would be cents. For numbers with more decimals 
-it is a smaller unit. 
+For dollars and euro's this would be cents. For numbers with more decimals
+it is a smaller unit.
 
 Using integers makes addition, subtraction and multiplication of currency exact.
 
-The library has experimental wrappers for float/double values. 
-Not tested extensively yet.
-
-Choosing int32_t as 'base' also means that there is a limit in terms 
-of minimum and maximum values. When large amounts are needed one can 
+Choosing int32_t as 'base' also means that there is a limit in terms
+of minimum and maximum values. When large amounts are needed one can
 use the currency64() or one of its derived formatters as this is based
 upon int64_t numbers.
 
+The 0.2.0 version added wrapper functions in the form of a TLA (Three Letter Acronym).
+The TLA's are international used acronyms for currency e.g. CNY(value) or GBP(value).
+
 There is a relation with the printHelpers class - https://github.com/RobTillaart/printHelpers
 When this currency library has matured it might be merged with printHelpers.
 
+As always feedback (or ideas for extensions) are welcome.
+
+
+### Breaking change 0.2.0 float/double
+
+The library 0.1.x had experimental wrappers for float/double values.
+Testing showed the limits of **float** => seven significant digits explicitly.
+As that caused the converted string to be incorrect (thus useless) this part
+of the API is deprecated.
+
+
+### Symbols
+
+Not all symbol codes work on all platforms, so you need to test for your platform.
+
+|  name              |  sign  |  code        |  Notes  |
+|:-------------------|:------:|:-------------|:--------|
+|  Euro              |   €    |  Alt + 0128  |
+|  Pound             |   £    |  Alt + 0163  |
+|  Dollar            |   $    |  Alt + 36    |
+|  Yen               |   ¥    |  Alt + 0165  |
+|  Cent              |   ¢    |  Alt + 0162  |
+|  Generic Currency  |   ¤    |  Alt + 0164  |
+|  Peseta            |   ₧    |  Alt + 158   |
+|  Frank / Florin    |   ƒ    |  Alt + 159   |
+
+More see e.g. https://www.webnots.com/alt-code-shortcuts-for-currency-symbols/
+
 
-#### Related
+### Related
 
 - https://github.com/RobTillaart/printHelpers
+- https://www.easymarkets.com/eu/learn-centre/discover-trading/currency-acronyms-and-abbreviations/
+
 
 ## Interface
 
@@ -51,13 +81,13 @@ When this currency library has matured it might be merged with printHelpers.
 
 The following functions are implemented:
 
-### Core function
+### Core functions
 
-- **char \* currency(int32_t value, uint8_t decimals, char decimalSeparator, char thousandSeparator, char symbol);** 
-- **char \* currency64(int64_t value, uint8_t decimals, char decimalSeparator, char thousandSeparator, char symbol);**
+- **char \* currency(int32_t value, uint8_t decimals, char decimalSeparator, char thousandSeparator, char symbol)**
+- **char \* currency64(int64_t value, uint8_t decimals, char decimalSeparator, char thousandSeparator, char symbol)**
 
 
-### int32 Wrapper functions
+### int32_t Wrapper functions
 
 - **char \* bitcoin(int32_t value)**
 - **char \* dollar(int32_t value)**
@@ -68,7 +98,7 @@ The following functions are implemented:
 - **char \* yuan(int32_t value)**
 
 
-### int64 Wrapper functions
+### int64_t Wrapper functions
 
 - **char \* bitcoin64(int64_t value)**
 - **char \* dollar64(int64_t value)**
@@ -79,11 +109,35 @@ The following functions are implemented:
 - **char \* yuan64(int64_t value)**
 
 
-### float Wrapper functions
+### int32_t TLA Wrapper functions
+
+- **char \* BTC(int32_t value)**
+- **char \* USD(int32_t value)**
+- **char \* EUR(int32_t value)**
+- **char \* GBP(int32_t value)**
+- **char \* RUB(int32_t value)**
+- **char \* JPY(int32_t value)**
+- **char \* CNY(int32_t value)**
+
+
+### int64_t TLA Wrapper functions
+
+- **char \* BTC64(int32_t value)**
+- **char \* USD64(int32_t value)**
+- **char \* EUR64(int32_t value)**
+- **char \* GBP64(int32_t value)**
+- **char \* RUB64(int32_t value)**
+- **char \* JPY64(int32_t value)**
+- **char \* CNY64(int32_t value)**
 
-Experimental - not tested
+
+### Deprecated float/double Wrapper functions
+
+Deprecated, has serious limitations, therefore commented in the library.
 
 All assumes 2 decimals except bitcoin which has 6.
+The accuracy of a float is just 7 digits.
+On some platforms (e.g. UNO R3) float == double so one gets errors.
 
 - **char \* bitcoinf(double value)**
 - **char \* dollarf(double value)**
@@ -101,8 +155,9 @@ See examples.
 
 ## Performance
 
-Performance is hard to optimize. Most time is spend in splitting 
-individual digits (div / mod 10).
+Performance is hard to optimize. 
+Most time is spend in splitting individual digits (div / mod 10).
+The **divmod10()** function from my fast_math library might be an option.
 
 
 ## Future
@@ -113,19 +168,19 @@ individual digits (div / mod 10).
 
 #### Should
 
+- investigate a better double/float API
+- investigate impact **divmod10()** for int32 and int64.
+
 #### Could
 
-- More wrapper functions?
-- test double parameters.
-  - should decimals be a parameter too?
-- add BTC, USD, EUR, GBP, RUB, JPY, CNY, etc. (3+1 chars)
-- https://www.easymarkets.com/eu/learn-centre/discover-trading/currency-acronyms-and-abbreviations/
+- add more TLA wrapper functions
+- consider .h library only as codebase is rather small?
 
 #### Won't
 
-- currency conversion?
-  - intern all in ???
-
+- currency conversion
+  - ratios change daily (or faster)
+  - intern in pecunia
 
 ## Support
 

libraries/Currency/currency.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: currency.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.9
+// VERSION: 0.2.0
 // PURPOSE: Currency library for Arduino
 //     URL: https://github.com/RobTillaart/Currency
 
@@ -59,7 +59,7 @@ char * currency64(int64_t value, int decimals, char decimalSeparator, char thous
 
   while ((pos < 1) || (v > 0))
   {
-    // separators
+    //  separators
     if ((pos == 0) && (decimals > 0) ) tmp[index++] = decimalSeparator;
     if ((pos > 0)  && (pos % 3 == 0) ) tmp[index++] = thousandSeparator;
     pos++;
@@ -86,29 +86,50 @@ char * currency64(int64_t value, int decimals, char decimalSeparator, char thous
 //
 //  DERIVED FUNCTIONS
 //
-char * bitcoin(int32_t value)   { return currency(value, 6,  '.',  ',',  'B'); }  
+char * bitcoin(int32_t value)   { return currency(value, 6,  '.',  ',',  'B'); }
 char * dollar(int32_t value)    { return currency(value, 2,  '.',  ',',  '$'); }
 char * euro(int32_t value)      { return currency(value, 2,  ',',  '.',  'E'); }
-char * pound(int32_t value)     { return currency(value, 2,  ',',  '.',  'L'); }
-char * roubles(int32_t value)   { return currency(value, 2,  ',',  '.',  'P'); }
+char * pound(int32_t value)     { return currency(value, 2,  ',',  '.',  'P'); }
+char * roubles(int32_t value)   { return currency(value, 2,  ',',  '.',  'R'); }
 char * yen(int32_t value)       { return currency(value, 2,  '.',  ',',  'Y'); }
-char * yuan(int32_t value)      { return currency(value, 2,  '.',  ',',  'R'); }
+char * yuan(int32_t value)      { return currency(value, 2,  '.',  ',',  'Y'); }
 
-char * bitcoin64(int64_t value) { return currency64(value, 6,  '.',  ',',  'B'); }  
+char * bitcoin64(int64_t value) { return currency64(value, 6,  '.',  ',',  'B'); }
 char * dollar64(int64_t value)  { return currency64(value, 2,  '.',  ',',  '$'); }
 char * euro64(int64_t value)    { return currency64(value, 2,  ',',  '.',  'E'); }
-char * pound64(int64_t value)   { return currency64(value, 2,  ',',  '.',  'L'); }
-char * roubles64(int64_t value) { return currency64(value, 2,  ',',  '.',  'P'); }
+char * pound64(int64_t value)   { return currency64(value, 2,  ',',  '.',  'P'); }
+char * roubles64(int64_t value) { return currency64(value, 2,  ',',  '.',  'R'); }
 char * yen64(int64_t value)     { return currency64(value, 2,  '.',  ',',  'Y'); }
-char * yuan64(int64_t value)    { return currency64(value, 2,  '.',  ',',  'R'); }
-
-char * bitcoinf(double value)   { return currency64(round(value * 1000000), 6,  '.',  ',',  'B'); }  
-char * dollarf(double value)    { return currency64(round(value * 100), 2,  '.',  ',',  '$'); }
-char * eurof(double value)      { return currency64(round(value * 100), 2,  ',',  '.',  'E'); }
-char * poundf(double value)     { return currency64(round(value * 100), 2,  ',',  '.',  'L'); }
-char * roublesf(double value)   { return currency64(round(value * 100), 2,  ',',  '.',  'P'); }
-char * yenf(double value)       { return currency64(round(value * 100), 2,  '.',  ',',  'Y'); }
-char * yuanf(double value)      { return currency64(round(value * 100), 2,  '.',  ',',  'R'); }
+char * yuan64(int64_t value)    { return currency64(value, 2,  '.',  ',',  'Y'); }
+
+//  deprecated
+//  char * bitcoinf(double value)   { return currency64(round(value * 1000000LL), 6,  '.',  ',',  'B'); }
+//  char * dollarf(double value)    { return currency64(round(value * 100LL), 2,  '.',  ',',  '$'); }
+//  char * eurof(double value)      { return currency64(round(value * 100LL), 2,  ',',  '.',  'E'); }
+//  char * poundf(double value)     { return currency64(round(value * 100LL), 2,  ',',  '.',  'P'); }
+//  char * roublesf(double value)   { return currency64(round(value * 100LL), 2,  ',',  '.',  'R'); }
+//  char * yenf(double value)       { return currency64(round(value * 100LL), 2,  '.',  ',',  'Y'); }
+//  char * yuanf(double value)      { return currency64(round(value * 100LL), 2,  '.',  ',',  'Y'); }
+
+
+//
+//  TLA - Three Letter Acronyms
+//
+char * BTC(int32_t value)       { return currency(value, 6,  '.',  ',',  'B'); }
+char * USD(int32_t value)       { return currency(value, 2,  '.',  ',',  '$'); }
+char * EUR(int32_t value)       { return currency(value, 2,  ',',  '.',  'E'); }
+char * GBP(int32_t value)       { return currency(value, 2,  ',',  '.',  'P'); }
+char * RUB(int32_t value)       { return currency(value, 2,  ',',  '.',  'R'); }
+char * JPY(int32_t value)       { return currency(value, 2,  '.',  ',',  'Y'); }
+char * CNY(int32_t value)       { return currency(value, 2,  '.',  ',',  'Y'); }
+
+char * BTC64(int64_t value)       { return currency64(value, 6,  '.',  ',',  'B'); }
+char * USD64(int64_t value)       { return currency64(value, 2,  '.',  ',',  '$'); }
+char * EUR64(int64_t value)       { return currency64(value, 2,  ',',  '.',  'E'); }
+char * GBP64(int64_t value)       { return currency64(value, 2,  ',',  '.',  'P'); }
+char * RUB64(int64_t value)       { return currency64(value, 2,  ',',  '.',  'R'); }
+char * JPY64(int64_t value)       { return currency64(value, 2,  '.',  ',',  'Y'); }
+char * CNY64(int64_t value)       { return currency64(value, 2,  '.',  ',',  'Y'); }
 
 
 //  -- END OF FILE --