Merge pull request #26 from bxparks/develop

merge v1.0.0 into master

CHANGELOG.md

@@ -1,6 +1,58 @@
 # Changelog
 
 - Unreleased
+- 1.0.0 (2024-07-19)
+    - Documentation
+        - add "Troubleshooting" section to `USER_GUIDE.md`
+    - User Interface
+        - `CLEAR` button clears only to the end of the line if the cursor is in
+          the interior of the input buffer
+            - if the cursor is at the beginning or the end of the input buffer,
+              the entire buffer is cleared
+            - identical to the CLEAR button on the TI-89/92+/Voyage 200
+            - similar to 2ND CLEAR on HP-50g in Algebraic mode (but not in RPN
+              mode)
+    - Variables
+        - print 'Err: Archived' error message if `STO` or `RCL` acts on
+          a variable (A-Z,Theta) that is archived
+    - TVM
+        - Change the criteria for using the small-i approximation to the
+          following: N*i <~ 6e-5.
+    - Improve performance of `PRIM` by 2.4X
+        - convert `modOP1ByBC()` to use the `IX` register instead of the stack
+          `(SP)`: 43-67% faster
+        - use DEIX instead of HLIX: ~12% faster
+        - process using in 8-bit chunks instead of 1-bit: ~18% faster
+        - use `A` register instead of `D` register for chunks: ~5% faster
+        - use nonrestoring division algorithm: ~11% faster
+        - unroll the 8-bit division loop 8 times: ~11% faster
+        - thanks go to the responders of [this Cemetech
+          thread](https://www.cemetech.net/forum/viewtopic.php?p=307636) for
+          improving the `modHLIXByBC()` algorithm
+    - MODE
+        - set Trig, Floating Display, and Display Digits settings to a known
+          state if the restoration of RPN83SAV fails, instead of inheriting the
+          modes from the TI-OS
+            - trig mode: RAD
+            - floating display: FIX
+            - display digits: floating
+    - CLR folder
+        - add `CLD` (clear display) menu item
+            - clear the display and re-render everything
+            - should almost never be needed, except during debugging
+            - analogous to the `CLD` command on the HP-42S
+    - UNIT
+        - car fuel consumption
+            - add `>Lkm`: convert mpg (miles per US gallon) to L/100km (liters
+              per 100 km)
+            - add `>mpg`: convert L/100km to mpg
+        - car tire pressure
+            - add `>kPa`: convert psi (pounds per square inch) to kPa
+              (kiloPascal)
+            - add `>psi`: convert kPa to psi
+        - land area
+            - add `>ha`: convert acre to hectare
+            - add `>acr`: convert hectare to acre
 - 0.12.0 (2024-06-24)
     - **Bug Fix**: update logic that determines when the comma `,` character can
       be inserted into the input buffer

README.md

@@ -23,7 +23,7 @@ bytes), `RPN83SAV` (140 byte), `RPN83STA` (272 bytes), and `RPN83STK` (120 to
 Summary of features:
 
 - traditional RPN stack (`X`, `Y`, `Z`, `T`), with `LASTX` register
-    - configurable stack levels between 4 and 8: `SSIZ`, `SIZ?`
+    - configurable stack levels between 4 and 8: `SSIZ`, `SSZ?`
 - input edit line with scrollable cursor using arrow keys
     - `LEFT`, `RIGHT`, `2ND LEFT`, `2ND RIGHT`
 - 8-line display showing 4 stack registers
@@ -56,7 +56,8 @@ Summary of features:
     - angle conversions: `>DEG`, `>RAD`, `>HR`, `>HMS`, `>REC`, `>POL`
     - unit conversions: `>C`, `>F`, `>hPa`, `>inHg`, `>km`, `>mi`, `>m`, `>ft`,
       `>cm`, `>in`, `>um`, `>mil`, `>kg`, `>lbs`, `>g`, `>oz`, `>L`, `>gal`,
-      `>mL`, `>floz`, `>kJ`, `>cal`, `>kW`, `>hp`
+      `>mL`, `>floz`, `>kJ`, `>cal`, `>kW`, `>hp`, `>Lkm`, `>mpg`, `>kPa`,
+      `>psi`, `>ha`, `>acr`
 - statistics and curve fitting, inspired by HP-42S
     - statistics: `Σ+`, `Σ-`, `SUM`, `MEAN`, `WMN` (weighted mean),
       `SDEV` (sample standard deviation), `SCOV` (sample covariance),
@@ -76,7 +77,8 @@ Summary of features:
     - carry flag and bit masks: `CCF`, `SCF`, `CF?`, `CB`, `SB`, `B?`
     - word sizes: `WSIZ`, `WSZ?`: 8, 16, 24, 32 bits
 - time value of money (TVM), inspired by HP-12C, HP-17B, and HP-30b
-    - `N`, `I%YR`, `PV`, `PMT`, `FV`, `P/YR`, `BEG`, `END`, `CLTV` (clear TVM)
+    - `N`, `I%YR`, `PV`, `PMT`, `FV`
+    - `P/YR`, `C/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-R99`
@@ -113,7 +115,7 @@ Missing features (partial list):
 - vectors and matrices
 - keystroke programming
 
-**Version**: 0.12.0 (2024-06-24)
+**Version**: 1.0.0 (2024-07-19)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -331,26 +333,26 @@ the 4 ways that complex numbers can be entered into RPN83P:
 
 - `100 - i/(2*pi*60*(1e-5))` using `2ND LINK`
 - `100 + 250i` using `2ND i`
-- `200 e^(i 10deg)` using `2ND ANGLE`
-- `300 e^(i 0.1)` using `2ND ANGLE 2ND ANGLE`
+- `200 ∠ 10°` using `2ND ANGLE`
+- `300 ∠ 0.1` using `2ND ANGLE 2ND ANGLE`
 
 The keystrokes are:
 
 - (optional) Press `CLEAR CLEAR CLEAR` to clear the RPN stack.
 - Press `MODE` button, `downarrow`,  `RECT`:
   ![MODE MenuRow 2](docs/images/menu-root-mode-2.png)
 - Press `100` `ENTER`
-- Press `2` `PI` `*` `60` `*` `1 EE 5` `(-)` `*` `1/X` `(-)` (-265.26)
-- Press `2ND LINK` (100-265.26i)
-- Press `100` `2ND i` `250` `+` (200-15.26i)
-- Press `200` `2ND ANGLE` `10` `+` (396.96+19.47i)
-- Press `300` `2ND ANGLE` `2ND ANGLE` `0.1` `+` (695.46+49.42i)
-- Press `4` `/` (173.89+12.35i)
-- Press `PRAD` (174.30 e^(i 0.07)
-- Press `PDEG` (174.30 e^(i 4.04deg))
+- Press `2` `PI` `*` `60` `*` `1 EE 5` `(-)` `*` `1/X` `(-)` (X: -265.26)
+- Press `2ND LINK` (X: 100 i -265.26)
+- Press `100` `2ND i` `250` `+` (X: 200 i -15.26)
+- Press `200` `2ND ANGLE` `10` `+` (X: 396.96 i 19.47)
+- Press `300` `2ND ANGLE` `2ND ANGLE` `0.1` `+` (X: 695.46 i 49.42)
+- Press `4` `/` (X: 173.89 i 12.35)
+- Press `PRAD` (X: 174.30 ∠ 0.07)
+- Press `PDEG` (X: 174.30 ∠° 4.04)
 - Press `MATH` button `CPLX`:
   ![CPLX MenuRow 1](docs/images/menu-root-cplx-1.png)
-- Press `CABS` (174.30)
+- Press `CABS` (X: 174.30)
 
 ![RPN83P Example 4 GIF](docs/images/rpn83p-example4.gif)
 

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.12.0 (2024-06-24)
+**Version**: 1.0.0 (2024-07-19)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 
@@ -134,7 +134,7 @@ Here are some notes about how the `PRIM` algorithm works:
   implement a custom `mod(u32, u16)` function which is about 25% faster than the
   full `div(u32, u16)` function.
 - In v0.10, the inner loop of the `mod(u32,u16)` function was made 40-50% faster
-  using the following observations:
+  through the `modHLSPByBC()` function using the following observations:
     - The Z80 has only 16-bit registers, so the `u32` type must typically be
       stored in 4 bytes of RAM, and the `u32` operations must work against the 4
       bytes of RAM.
@@ -149,10 +149,25 @@ Here are some notes about how the `PRIM` algorithm works:
       `ex (sp), hl` instruction of the Z80 to swap the 2 halves back and forth.
       This made the `mod(u32,u16)` function about 40-50% faster compared to
       v0.9.0.
-
-I can think of one additional optimization that *may* give us a 10-20% speed
-increase, but it would come at the cost of code that would be significantly
-harder to maintain, so I don't think it's worth it.
+- In v0.13.0-dev, the inner loop `mod(u32,u16)` became another ~42% faster:
+    - discovered that the Z80 supports `add ix, ix` instruction
+    - replacing `ex (sp), hl; add hl, hl` combo with `add ix, ix`: ~29% faster
+    - replacing `rl e; rl d` combo with `adc hl, hl`: ~4% faster
+    - deleting an unnecessary `or a` instruction: ~5% faster
+    - rearranging some code to eliminate a branch in the common case, and
+      selecting `jr` or `jp` judiciously: 1-2% faster
+- In v1.0.0, the `mod(u32,u16)` became another 140-160% (i.e. 2.4X to 2.6X)
+  faster, based on the ideas from [this Cemetech
+  thread](https://www.cemetech.net/forum/viewtopic.php?t=19790):
+    - initial benchmark: 20.5 s
+    - chunking using 8-bit registers, instead of shifting the entire 32-bit
+      dividend: 18% faster
+    - using DEIX instead of HLIX, eliminating a bunch of 'ex de, hl': 12% faster
+    - using a nonrestoring division: 9-13% faster
+    - using register A instead of register D for each 8-bit chunk: 5% faster
+    - unrolling the 8-bit division loop eight times: 11-15% faster
+    - end result: 11.8 s or 74% faster, i.e. 1.74X faster
+    - total improvement from v0.12: 2.4X (83+/84+) to 2.6X (Nspire) faster
 
 ### Prime Factor Improvements
 

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.12.0 (2024-06-24)
+**Version**: 1.0.0 (2024-07-19)
 
 **Parent Document**: [USER_GUIDE.md](USER_GUIDE.md)
 
@@ -219,7 +219,7 @@ These are features which are unlikely to be implemented for various reasons:
     - 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.
+      or complex Lists, which are not currently 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