Merge pull request #25 from bxparks/develop

merge v0.12.0 into master

CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
 - Unreleased
+- 0.12.0 (2024-06-24)
+    - **Bug Fix**: update logic that determines when the comma `,` character can
+      be inserted into the input buffer
+        - some internal routines were still looking at the last character in the
+          input buffer, instead of the character to the left of the current
+          cursor
+            - prevented comma insertion when the cursor was scrolled into the
+              middle of the input buffer
+            - updated to look at the char to the left of cursor
+        - update logic that handles left and right braces `{ }`
+            - comma now allowed only inside an open left-brace `{`
+            - comma no longer allowed after the last closing right-brace `}`
+    - TVM
+        - reduce rounding errors when `PYR==CYR`, the most common case in the US
+          at least
+        - improve logic for appending the "overridden" dot after the `IYR1`,
+          `IYR2`, and `TMAX` menu items
+        - add `C/YR` menu (number of compoundings per year)
+            - uses the same variable as the `C/Y` variable of the "Finance" app
+              in TI-OS
+            - supports `2ND C/YR` to retrieve its value, just like `2ND P/YR`
+            - setting `P/YR` also sets `C/YR` (consistent with the behavior of
+              the "Finance" app in TI-OS
+            - setting `C/YR` does *not* change `P/YR` (same as "Finance" app)
+        - add a dot to `P/YR` and `C/YR` if they differ from their default value
+          of 12, allows users to quickly see if those values are different from
+          the default
+        - make TVM Solver more robust under certain edge cases, especially near
+          `I%YR ~ 0%`
+        - change initial guess of `IYR1` to `-50%` to support negative interest
+          rates by default
+            - keep default value of `IYR2` at `100%`
+        - synchronize the `BEG`/`END` flag of RPN83P with the `BEGIN`/`END`
+          flag of the "Finance" app provided by TI-OS
+        - display status message 'TVM Calculated (Multiple)' if the TVM equation
+          has 2 solutions, but only one of them was found
+    - docs
+        - simplify pandoc processing pipeline
+        - change PDF font to FreeSerif and FreeMono to render the U+2220 (angle)
+          symbol properly
 - 0.11.0 (2024-05-28)
     - **Warning**: Previously saved RPN stack and storage registers are
       incompatible and are lost when upgrading to this version.

README.md

@@ -17,7 +17,7 @@ RPN83P is a flash application written in Z80 assembly language that consumes 3
 pages (48 kiB) of flash memory. Since it is stored in flash, it is preserved if
 the RAM is cleared. It consumes about 1025 to 2535 bytes of TI-OS RAM through 4
 AppVars, depending on the number of storage registers: `RPN83REG` (500 to 1925
-bytes), `RPN83SAV` (142 byte), `RPN83STA` (272 bytes), and `RPN83STK` (120 to
+bytes), `RPN83SAV` (140 byte), `RPN83STA` (272 bytes), and `RPN83STK` (120 to
 196 bytes).
 
 Summary of features:
@@ -58,7 +58,7 @@ Summary of features:
       `>cm`, `>in`, `>um`, `>mil`, `>kg`, `>lbs`, `>g`, `>oz`, `>L`, `>gal`,
       `>mL`, `>floz`, `>kJ`, `>cal`, `>kW`, `>hp`
 - statistics and curve fitting, inspired by HP-42S
-    - statistics: `Sigma+`, `Sigma-`, `SUM`, `MEAN`, `WMN` (weighted mean),
+    - statistics: `Σ+`, `Σ-`, `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`
@@ -79,21 +79,22 @@ Summary of features:
     - `N`, `I%YR`, `PV`, `PMT`, `FV`, `P/YR`, `BEG`, `END`, `CLTV` (clear TVM)
 - complex numbers, inspired by HP-42S and HP-35s
     - stored in RPN stack registers (`X`, `Y`, `Z`, `T`, `LASTX`) and storage
-      registers `R00-R24`
+      registers `R00-R99`
     - result modes: `RRES` (real results), `CRES` (complex results)
     - display modes: `RECT`, `PRAD` (polar radians), `PDEG` (polar degrees)
     - linking/unlinking: `2ND LINK` (convert 2 reals to 1 complex, same as
       `COMPLEX` on HP-42S)
     - number entry: `2ND i` (rectangular), `2ND ANGLE` (polar degrees), `2ND
       ANGLE 2ND ANGLE` (polar radians)
     - extended regular functions: `+`, `-`, `*`, `/`, `1/X`, `X^2`, `SQRT`,
-      `Y^X`, `X^3`, `3ROOTY`, `XROOTY`, `LOG`, `LN`, `10^X`, `E^X`, `2^X`,
+      `Y^X`, `X^3`, `3ROOTX`, `XROOTY`, `LOG`, `LN`, `10^X`, `E^X`, `2^X`,
       `LOG2`, `LOGB`
     - complex specific functions: `REAL`, `IMAG`, `CONJ`, `CABS`, `CANG`
     - unsupported: trigonometric and hyperbolic functions (not supported by
       TI-OS)
 - date functions
     - date, time, datetime, timezone, and hardware clock
+    - proleptic Gregorian calendar from year 0001 to 9999
     - add or subtract dates, times, datetimes
     - convert datetime to different timezones
     - convert between datetime and epochseconds
@@ -112,7 +113,7 @@ Missing features (partial list):
 - vectors and matrices
 - keystroke programming
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0 (2024-06-24)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -198,6 +199,7 @@ Community members have verified that it works on the following variants:
 The following calculators are *not* supported because their internal hardware
 and firmware are too different:
 
+- TI-73, 80, 81, 82, 85, 86
 - TI-83 (without Plus)
 - TI-84 Plus C Silver Edition
 - TI-84 Plus CE

docs/DEVELOPER.md

@@ -3,7 +3,7 @@
 Notes for the developers of the RPN83P app, likely myself in 6 months when I
 cannot remember how the code works.
 
-**Version**: 0.9.0 (2024-01-06)
+**Version**: 0.12.0 (2024-06-24)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 
@@ -81,22 +81,20 @@ the application code to change.
 ## DRAW Mode
 
 The secret `DRAW` 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:
+user for a number, like the `FIX` or `STO` command. Currently 3 modes defined:
 
 - 0 (drawModeNormal): 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
+- 1 (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.
+- 2 (drawModeTvmSolver): Single step through the `I%YR` TVM Solver calculations,
+  waiting for a key before executing the next iteration. Show the following
+  parameters:
+    - iteration counter (`tvmSolverCount`)
+    - internal interest rate variables `tvmI0` and `tvmI1`
+    - the `NPMT(i, N)` function evaluated at `tvmI0` and `tvmI1`
 
 Any other value is treated to be the same as 0 (drawModeNormal).
 
@@ -172,8 +170,7 @@ factoring algorithm:
    returned *all* prime factors of a number `N` . It could be more efficient
    by restarting the loop at the previous prime factor. However, this new
    function would need support for vectors or arrays so that it can return
-   multiple numbers as the result. Vectors or arrays are not currently (v0.9.0)
-   supported.
+   multiple numbers as the result. Vectors or arrays are not supported.
 1. The [Prime Number
    Theorem](https://en.wikipedia.org/wiki/Prime_number_theorem) tells us that
    the number of prime numbers less than `n` is roughly `n/ln(n)`. Since we
@@ -194,10 +191,11 @@ factoring algorithm:
    the app flash memory size by at least 13084 bytes (most likely another flash
    page, so 16 kiB).
 
-   I'm not sure if the increase in flash size is worth it, but the `PRIM`
-   function could be made blindingly fast, finishing the toughest prime factor
-   problem (of less than `2^32`) in about 4 seconds (13.0/3.3) on a TI-84+
-   calculator.
+   As far as I know, using a precalculated table of prime numbers would be the
+   fastest algorithm, and no further improvements can be made. That means that
+   the toughest prime factor problem (factorizing `65521*65521`) could be done
+   in about 2.9s (9.5/3.3) on a TI-84+ calculator. However, I don't think the
+   difference between 9.5s and 2.9s is worth the extra 16kiB of flash memory.
 
 ## TVM Algorithms
 

docs/FUTURE.md

@@ -14,7 +14,7 @@ because it is faster and easier to use compared to a web app, especially for
 small features that can be described in a few sentences. Usually only the larger
 and more complicated features will get their own GitHub tickets.
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0 (2024-06-24)
 
 **Parent Document**: [USER_GUIDE.md](USER_GUIDE.md)
 
@@ -30,26 +30,6 @@ and more complicated features will get their own GitHub tickets.
 
 ## Near Future
 
-- `TVM` (time value of money)
-    - improve TVM Solver for `I%YR`
-        - The current default initial guess is 0% and 100% so that positive
-          interest rates are required (because a sign change over the initial
-          guesses are required). If there is a rounding error, the actual
-          numerical solution could be slighlty negative, which would cause an
-          `TVM Not Fount` error message because a sign-change is currently
-          required over the 2 initial guesses.
-        - One solution could be use something like `-1%` for the lower guess,
-          and then check for a sign change over 2 sub-intervals: `[-1%,0%]` and
-          `[0%,100%]`. We also have to careful to detect cases where expected
-          solution is exactly `0%`.
-        - The terminating tolerance could be selectable or more intelligent.
-        - Maybe change the root solving algorithm from Secant method to Newton's
-          method for faster convergence.
-    - support `C/YR` (compounding periods per year) as a separate parameter
-        - currently `C/YR` is set to be the same as `P/YR` (payments per year)
-          for ease of implementation
-        - there are apparently jurisdictions (Canada, UK) where it is common for
-          `C/YR` to be different from `P/YR`
 - add a `ROOT > CLR > CLAL` (Clear All) menu function
     - becomes useful as more features and configuration options are added
 - allow numbers in any base to be entered regardless of the BASE mode
@@ -59,6 +39,8 @@ and more complicated features will get their own GitHub tickets.
 
 ## Medium Future
 
+- bulk view registers and variables
+    - see [Issue#24](https://github.com/bxparks/rpn83p/issues/24)
 - custom button bindings
     - a significant number of buttons on the TI-83/TI-84 keyboard are not used
       by RPN83P
@@ -99,10 +81,12 @@ and more complicated features will get their own GitHub tickets.
     - I estimate that this feature will take about 1000-2000 hours of
       programming.
 - polynomial solvers
-    - Quadratic, cubic, and quartic equations have analytical solutions so
-      should be relatively straightforward... Except that they need complex
-      number support. And we need to work around numerical cancellation or
-      roundoff errors.
+    - Quadratic has an relatively easy, well-understood analytical solutions.
+    - Cubic and quartic have analytic solutions but they are quite complex
+      (particularly the quartic) and their numerical stability behaviors
+      are not straightforward. It may be easier to use iterative methods for
+      cubic and quartic equations.
+    - Anything higher than 4th degree requires numerical solutions.
 - `UNIT` conversions
     - support imperial (not just US) units
         - several places assume US customary units (e.g. US gallons) instead of
@@ -174,8 +158,8 @@ and more complicated features will get their own GitHub tickets.
     - If a TI-BASIC program can be called from RPN83P, and a stable data conduit
       (i.e. an API) can be defined between RPN83P and TI-BASIC, then some of the
       need for keystroke programming within RPN83P may be satisfied.
-    - Single-letter variables `A` to `Z` and `Theta` are now (v0.10.0) available
-      through `STO` and `RCL`, so be conduits between RPN83P and TI-BASIC.
+    - Single-letter variables `A` to `Z` and `Theta` are available through `STO`
+      and `RCL`, so be conduits between RPN83P and TI-BASIC.
     - Other types may be useful: List, Matrix, and String types.
     - See [Issue #22](https://github.com/bxparks/rpn83p/issues/22)
 - indirect `STO` and `RCL` operators
@@ -232,15 +216,16 @@ and more complicated features will get their own GitHub tickets.
 These are features which are unlikely to be implemented for various reasons:
 
 - user-defined alphanumeric variables
-    - TI-OS supports only single-letter variables for real or complex types.
-      Access to these are provided in v0.10.0. Multi-letter user-defined names
-      are available only for real or complex Lists.
-    - The HP-42S allows multi-letter user-defined variables which are accessible
-      through the menu system.
-    - We would have to write our own symbol management and garage collection
-      subsystem to handle user-defined variables, which does not seem worth it.
-    - We would also require substantial refactoring of the current menu system
-      code.
+    - The TI-OS supports only single-letter variables for real or complex types
+      and access to these from RPN83P are provided through the `STO` and `RCL`
+      commands. The TI-OS supports multi-letter user-defined names only for real
+      or complex Lists, which are not currently (v0.12.0) supported in RPN83P.
+    - On the other hand, the HP-42S allows multi-letter user-defined variables
+      for all types, and they which are accessible through the menu system.
+    - To support multi-letter variables in RPN83P, we would have to write our
+      own symbol management and garage collection subsystems to handle these
+      user-defined variables. We would also require substantial refactoring of
+      the current menu system code.
     - Overall, it doesn't seem worth the effort.
 - matrices
     - I don't know how much matrix functionality is provided by TI-OS SDK.