Merge pull request #12 from bxparks/develop

merge 0.7.0 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,79 @@
 # Changelog
 
 - Unreleased
+- 0.7.0 (2023-11-20)
+    - `STAT`
+        - fix broken `Sigma+` and `Sigma-` when `Y==0`
+        - use alternate equation for `SLOP` (slope) which works when the `Y`
+          data points are the same
+        - fix "stack lift disable" feature of `Sigma+` and `Sigma-` which
+          probably got broken during an earlier refactoring
+        - check for division by zero when calculating weighted mean `WMN`, and
+          show `9.9999999999999E99` to indicate error, allowing weightedX (or
+          weightedY) to be evaluated even if the other is undefined
+    - `BASE`
+        - implement `WSIZ` (set word size) restricted to 8, 16, 24, and 32
+          (inspired by HP-16C and Free42)
+        - display appropriate number of digits for various `WSIZ` values, for
+          various base modes (`HEX`, `OCT`, `BIN`)
+        - display ellipsis character on left most digit in `BIN` mode if
+          the binary number cannot be fully displayed using 14 digits on the
+          screen
+        - **Breaking Change**: change order of `BDIV` results in `X` and `Y`
+          registers
+            - now `X=quotient=Y/X` and `Y=remainder=Y%X`
+            - allows easier recovery of original `X` using `LastX` `*`
+    - `MATH`: add `LN1+`, `E^X-`
+        - implement `log(1+x)` and `e^x-1` respectively
+        - more accurate than their naive implementations when `x` is close to 0
+        - use mathematical identities involving hyperbolic `sinh()` and
+          `asinh()` functions to avoid roundoff errors
+    - `TVM`
+        - add TVM (time value of money) submenu hierarchy (inspired by HP-12C
+          and HP-30b)
+        - implement relatively simple Newton-Secant root solver to calculate
+          the `I%YR` from the other 4 TVM variables
+        - significant performance and robustness improvements can probably be
+          made in the future
+    - add storage register arithmetic operations
+        - `STO+`, `STO-`, `STO*`, `STO/`
+        - `RCL+`, `RCL-`, `RCL*`, `RCL/`
+    - convert to multi-page flash application
+        - now consumes 2 flash pages (2 x 16 kiB)
+    - `CLEAR` multiple times to clear RPN stack
+        - If `CLEAR` is pressed on an empty edit line (just a `_` cursor), then
+          the message "CLEAR Again to Clear Stack" will be displayed.
+        - If `CLEAR` is pressed again right after this message, the RPN stack is
+          cleared, invoking the `ROOT > CLR > CLST` menu function.
+        - Provides a quick shortcut to the `CLST` function which can be
+          difficult to reach when the current menu item is deeply nested in
+          another part of the menu hierarchy.
+        - The TI-OS does not support `2ND CLEAR`, it returns the same keycode as
+          `CLEAR`. So invoking `CLST` on multiple `CLEAR` presses seemed like
+          the most reasonable workaround.
+    - implement jumpBack for `MODE` button shortcut
+        - When `ROOT > MODE` is reached through the hierchical menu, the
+          `ON/EXIT/ESC` button goes back up the menu hierarchy to the parent,
+          the `ROOT`.
+        - When `ROOT > MODE` is invoked through the `MODE` button on the
+          keyboard, the `ON/EXIT/ESC` button jumps back to the previous menu
+          location, instead of going back up the menu tree.
+        - This allows quick changes to the `FIX`, `SCI`, and `ENG` display
+          modes, without losing one's place in the menu hierarchy.
+    - fix incorrect handling of `DEL` after a `FIX`, `SCI`, or `ENG` mode
+        - when the `DEL` (backspace) button is pressed after a 2-digit argument
+          of a `FIX` (or `SCI` etc), one of the digits of the 2-digit argument
+          remained in the input buffer
+        - the fix now correctly clears the input buffer when transitioning into
+          edit mode from a normal mode
+    - **Potential Breaking Change**: `STO`, `RCL`, `FIX`, `SCI`, `ENG` argument
+      prompt is no longer saved and restored on QUIT or OFF
+        - a new Command Arg parser was required to support storage register
+          arithmetics
+        - it uses a secondary `GetKey()` parsing loop which implements its own
+          `2ND QUIT` and `2ND OFF` handlers
+        - the state of the secondary `GetKey()` parsing loop is not saved and
+          restored
 - 0.6.0 (2023-09-22)
     - save application state
         - preserve app state into an appvar named `RPN83SAV` upon exit

DEVELOPER.md

@@ -0,0 +1,25 @@
+# Developer Notes
+
+Notes for the developers of the RPN83P app, likely myself in 6 months when I
+cannot remember how the code works.
+
+## DRAW Mode
+
+The secret `DRAW` (maybe call it "Debug") modes are activated by the `2ND DRAW`
+command. It prompts the user for a number, like the `FIX` or `STO` command.
+Currently 4 modes defined:
+
+- 0 (drawNodeNormal): Normal rendering, this is the default.
+- 1 (drawModeTvmSolverI): Single step through the `I%YR` TVM Solver
+  calculations, and show the iteration counter (`tvmSolverCount`), and the
+  internal interest rate variables (`tvmI0`, `tvmI1`) in place of the RPN stack
+  variables (T,Z,Y,X). The program waits for a key before executing the next
+  iteration.
+- 2 (drawModeTvmSolverF): Same as (1), except show the values of the function
+  whose roots we are trying to solve at `tvmI0` and `tvmI1`, in other words,
+  show the variables `tvmNPMT0` and `tvmNPMT1`.
+- 3 (drawModeInputBuf): Show the `inputBuf` (the edit buffer when entering
+  digits) in the Debug line just below the Status line. The `X` register is now
+  always shown, instead of being overwritten by the `inputBuf` in Edit mode.
+  This helps debugging the complex interaction between the input buffer and the
+  X register.

README.md

@@ -7,16 +7,15 @@ calculator app for the [TI-83 Plus](https://en.wikipedia.org/wiki/TI-83_series)
 (including the Silver Edition) and the [TI-84
 Plus](https://en.wikipedia.org/wiki/TI-84_Plus_series) (including the Silver
 Edition). The app is inspired mostly by the
-[HP-42S](https://en.wikipedia.org/wiki/HP-42S) calculator, with some sprinkles
-of older HP calculators like the
-[HP-12C](https://en.wikipedia.org/wiki/HP-12C), the
-[HP-15C](https://en.wikipedia.org/wiki/HP-15C), and the
+[HP-42S](https://en.wikipedia.org/wiki/HP-42S) calculator, with some significant
+features from the
+[HP-12C](https://en.wikipedia.org/wiki/HP-12C) and the
 [HP-16C](https://en.wikipedia.org/wiki/HP-16C).
 
 
-The RPN83P is a flash application that consumes one page (16 kB) of flash
+The RPN83P is a flash application that consumes 2 pages (32 kiB) of flash
 memory. Since it is stored in flash, it is preserved if the RAM is cleared. It
-consumes about 375 bytes of TI-OS RAM: 2 list variables named `REGS` and `STK`,
+consumes about 400 bytes of TI-OS RAM: 2 list variables named `REGS` and `STK`,
 and an appVar named `RPN83SAV`.
 
 Here is a quick summary of its features:
@@ -25,7 +24,7 @@ Here is a quick summary of its features:
 - support for `lastX` register
 - 8-line display showing all stack registers
 - 25 storage registers (`STO 00`, `RCL 00`, ..., `STO 24`, `RCL 24`)
-- hierarchical menu system, inspired by the HP-42S
+- hierarchical menu system similar to HP-42S
 - support for all math functions with dedicated buttons on the TI-83 Plus and
   TI-84 Plus
     - arithmetic: `/`, `*`, `-`, `+`
@@ -35,7 +34,7 @@ Here is a quick summary of its features:
     - `LOG`, `10^X`, `LN`, `e^X`
     - constants: `pi` and `e`
 - additional menu functions:
-    - `X^3`, `CBRT`, `XRootY`, `ATN2`, `2^X`, `LOG2`, `LOGB`
+    - `X^3`, `3RootX`, `XRootY`, `ATN2`, `2^X`, `LOG2`, `LOGB`
     - `%`, `%CH`, `GCD`, `LCM`, `PRIM` (is prime)
     - `IP` (integer part), `FP` (fractional part), `FLR` (floor), `CEIL`
       (ceiling), `NEAR` (nearest integer)
@@ -44,6 +43,16 @@ Here is a quick summary of its features:
     - hyperbolic: `SINH`, `COSH`, `TANH`, `ASNH`, `ACSH`, `ATNH`
     - angle conversions: `>DEG`, `>RAD`, `>HR`, `>HMS`, `>REC`, `>POL`
     - unit conversions: `>C`, `>F`, `>km`, `>mi`, etc
+- features inspired by HP-42S
+    - `E^X-` (e^x-1), `LN1+` (log(1+x))
+    - statistics: `Sigma+`, `Sigma-`, `SUM`, `MEAN`, `WMN` (weighted mean),
+      `SDEV` (sample standard deviation), `SCOV` (sample covariance),
+      `PDEV` (population standard deviation), `PCOV` (population covariance)
+    - curve fitting: `Y>X`, `X>Y`, `SLOP` (slope), `YINT` (y intercept), `CORR`
+      (correlation coefficent)
+    - curve fit models: `LINF` (linear), `LOGF` (logarithmic), `EXPF`
+      (exponential), `PWRF` (power)
+- features inspired by HP-16C and HP-42S
     - base conversions: `DEC`, `HEX`, `OCT`, `BIN`
     - bitwise operations: `AND`, `OR`, `XOR`, `NOT`, `NEG`, `REVB` (reverse
       bits), `CNTB` (count bits)
@@ -52,13 +61,9 @@ Here is a quick summary of its features:
     - shift and rotate: `SL`, `SR`, `ASR`, `RL`, `RR`, `RLC`, `RRC`,
       `SLn`, `SRn`, `RLn`, `RRn`, `RLCn`, `RRCn`
     - carry flag and bit masks: `CCF`, `SCF`, `CF?`, `CB`, `SB`, `B?`
-    - statistics: `Sigma+`, `Sigma-`, `SUM`, `MEAN`, `WMN` (weighted mean),
-      `SDEV` (sample standard deviation), `SCOV` (sample covariance),
-      `PDEV` (population standard deviation), `PCOV` (population covariance)
-    - curve fitting: `Y>X`, `X>Y`, `SLOP` (slope), `YINT` (y intercept), `CORR`
-      (correlation coefficent)
-    - curve fit models: `LINF` (linear), `LOGF` (logarithmic), `EXPF`
-      (exponential), `PWRF` (power)
+- features inspired by HP-12C and HP-30b
+    - time value of money (TVM): `N`, `I%YR`, `PV`, `PMT`, `FV`, `P/YR`, `BEG`,
+      `END`, `CLTV` (clear TVM)
 - various display modes
     - `RAD`, `DEG`
     - `FIX` (fixed point 0-9 digits)
@@ -71,7 +76,7 @@ Here are some missing features which may be added in the future:
 - complex numbers
 - keystroke programming
 
-**Version**: 0.6.0 (2023-09-22)
+**Version**: 0.7.0 (2023-11-20)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -86,6 +91,7 @@ Here are some missing features which may be added in the future:
 - [Quick Examples](#quick-examples)
     - [Example 1](#example-1)
     - [Example 2](#example-2)
+    - [Example 3](#example-3)
 - [User Guide](#user-guide)
 - [Compiling from Source](#compiling-from-source)
 - [Tools and Resources](#tools-and-resources)
@@ -115,7 +121,7 @@ Guide](USER_GUIDE.md), but here is the quick version:
 
 The RPN83P app starts directly into the calculator mode, like this:
 
-> ![RPN83P Hello 1](docs/rpn83p-screenshot-initial.png)
+![RPN83P Hello 1](docs/rpn83p-screenshot-initial.png)
 
 Since the RPN83P is a flash app, it is preserved when the RAM is cleared. It
 consumes about 300 bytes of RAM space for its internal RPN and storage
@@ -162,18 +168,22 @@ outwards. Enter the following keystrokes:
 
 Here is an animated GIF that shows this calculation:
 
-> ![RPN83P Example 1 GIF](docs/rpn83p-example1.gif)
+![RPN83P Example 1 GIF](docs/rpn83p-example1.gif)
 
 (Note that the RPN83P provides a `X^3` menu function that could have been used
 for this formula, but I used the `LastX` feature to demonstrate its use.)
 
 ### Example 2
 
+The RPN83P supports most of the base conversion and logical operators found on
+the HP-42S and the HP-16C calculators.
+
 Let's calculate the bitwise-and operator between the hexadecimal numbers `B6`
 and `65`, then see the result as an octal number (base-8), a binary number
 (base-2), then right shift the result 3 bits which sets the Carry Flag, then
 view the final result as a decimal number:
 
+- Press `MATH` to reset the menu to the home row.
 - Navigate the menu with the DOWN arrow to get to
   ![ROOT MenuRow 2](docs/rpn83p-screenshot-menu-root-2.png)
 - Press `BASE` menu to get to
@@ -205,14 +215,57 @@ view the final result as a decimal number:
 
 Here is the animated GIF that shows this calculation:
 
-> ![RPN83P Example 2 GIF](docs/rpn83p-example2.gif)
+![RPN83P Example 2 GIF](docs/rpn83p-example2.gif)
+
+### Example 3
+
+The RPN83P supports the Time Value of Money functionality of the HP-12C
+calculator.
+
+In this example:
+- We calculate the monthly payment of a $500,000 mortgage over 30 years at 8%,
+  then,
+- We recalculate the payment at 7%, then,
+- We fix the monthly payment at $3000/month and calculate the interest rate
+  that is needed for that monthly payment.
+
+Here are the steps:
+
+- Press `MATH` to reset the menu to the home row.
+- Navigate the menu with the DOWN arrow to get to
+  ![ROOT MenuRow 2](docs/rpn83p-screenshot-menu-root-2.png)
+- Press the `TVM` menu to get to
+  ![TVM MenuRow 1](docs/rpn83p-screenshot-menu-root-tvm-1.png)
+- Press the DOWN arrow to get to
+  ![TVM MenuRow 2](docs/rpn83p-screenshot-menu-root-tvm-2.png)
+- Press the `CLTV` button to clear the TVM variables.
+- Press the UP arrow to get back to
+  ![TVM MenuRow 1](docs/rpn83p-screenshot-menu-root-tvm-1.png)
+- Press `360` `N` (30 years * 12 months = 360 payments)
+- Press `8` `I%YR` (interest percent per year)
+- Press `500000` `PV` (present value)
+- Press `0` `FV` (future value)
+- Press `PMT` (payments)
+    - You should see `-3668.822869` ($3668.82)
+- Press `7` `I%YR`
+- Press `PMT`
+    - You should see `-3326.512476` ($3326.51)
+- Press `-3000` `PMT`
+- Press `I%YR`
+    - After a couple of seconds, you should see 6.006990008 (6%).
+
+Here is the animated GIF that shows this calculation:
+
+![RPN83P Example 3 GIF](docs/rpn83p-example3.gif)
+
+### Exiting the Menu
 
 Press:
 
 - `ON` button (`ESC/EXIT`) multiple times to back to the home menu, or
 - `MATH` button (`HOME`) to go back directly.
 
-> ![ROOT MenuRow 1](docs/rpn83p-screenshot-menu-root-1.png)
+![ROOT MenuRow 1](docs/rpn83p-screenshot-menu-root-1.png)
 
 ## User Guide