Merge pull request #8 from bxparks/develop

merge 0.4.0 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
 - Unreleased
+    - More `BASE` menu functions:
+        - `SL` (shift left), `SR` (shift right)`, `RL` (rotate left circular),
+        `RR` (rotate right circular).
+        - `B+`, `B-`, `B*`, `B/`
+        - `BDIV` (division with remainder)
+    - Map `+`, `-`, `*`, and `/` buttons to their bitwise counterparts when in
+      `HEX`, `OCT`, or `BIN` modes.
+        - Too confusing to have floating point operations bound to the
+          easy-to-reach buttons while in HEX, OCT or BIN modes.
+        - This is consistent with the HP-42S.
+    - `PRIM` (isPrime)
+        - change result values:
+            - 1 if the number is a prime, or
+            - smallest prime factor (always greater than 1) if not prime.
+        - preserve the original `X`, and push it up to `Y`
+            - allows the `/` button to be chained with additional `PRIM` to
+              calculate all prime factors
+            - see [Prime Factors](#USER_GUIDE.md#prime-factors]) for details
+        - improve speed by 7X using u32 integer routines instead of floating
+          point routines
 - 0.3.3 (2023-08-14)
     - Add `Makefile` targets for converting GitHub markdown files to PDF files.
     - Update some sections in `README.md` and `USER_GUIDE.md`.

README.md

@@ -41,14 +41,15 @@ Here the quick summary of its features:
     - angle conversions: `>DEG`, `>RAD`, `>HR`, `>HMS`, `P>R`, `R>P`
     - unit conversions: `>C`, `>F`, `>km`, `>mi`, etc
     - base conversions: `DEC`, `HEX`, `OCT`, `BIN`
-    - bitwise operations: `AND`, `OR`, `XOR`, `NOT`, `NEG`
+    - bitwise operations: `AND`, `OR`, `XOR`, `NOT`, `NEG`, `SL`, `SR`, `RL`,
+      `RR`, `B+`, `B-`, `B*`, `B/`, `BDIV`
 - various display modes
     - `RAD`, `DEG`
     - `FIX` (fixed point 0-9 digits)
     - `SCI` (scientific 0-9 digits)
     - `ENG` (engineering 0-9 digits)
 
-**Version**: 0.3.3 (2023-08-14)
+**Version**: 0.4.0-dev (2023-08-16)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

USER_GUIDE.md

@@ -2,7 +2,7 @@
 
 RPN calculator app for the TI-83 Plus and TI-84 Plus inspired by the HP-42S.
 
-**Version**: 0.3.3 (2023-08-14)
+**Version**: 0.4.0-dev (2023-08-16)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 
@@ -34,11 +34,12 @@ RPN calculator app for the TI-83 Plus and TI-84 Plus inspired by the HP-42S.
     - [Auto-start](#auto-start)
     - [Floating Point Display Modes](#floating-point-display-modes)
     - [Trigonometric Modes](#trig-modes)
-    - [Base Functions](#base-functions)
-        - [Base Modes](#base-modes)
-        - [Base Rendering](#base-rendering)
-        - [Base Integers](#base-integers)
+    - [BASE Functions](#base-functions)
+        - [BASE Modes](#base-modes)
+        - [BASE Arithmetic](#base-arithmetic)
+        - [BASE Integer Size](#base-integer-size)
     - [Storage Registers](#storage-registers)
+    - [Prime Factors](#prime-factors)
 - [Future Enhancements](#future-enhancements)
     - [Near Future](#near-future)
     - [Medium Future](#medium-future)
@@ -86,7 +87,8 @@ Here the quick summary of its features:
     - angle conversions: `>DEG`, `>RAD`, `>HR`, `>HMS`, `P>R`, `R>P`
     - unit conversions: `>C`, `>F`, `>km`, `>mi`, etc
     - base conversions: `DEC`, `HEX`, `OCT`, `BIN`
-    - bitwise operations: `AND`, `OR`, `XOR`, `NOT`, `NEG`
+    - bitwise operations: `AND`, `OR`, `XOR`, `NOT`, `NEG`, `SL`, `SR`, `RL`,
+      `RR`, `B+`, `B-`, `B*`, `B/`, `BDIV`
 - various display modes
     - `RAD`, `DEG`
     - `FIX` (fixed point 0-9 digits)
@@ -573,7 +575,10 @@ buttons just under the LCD screen. Use the `UP`, `DOWN`, `ON` (back), and `MATH`
     - `%CH`: percent change from `Y` to `X`, leaving `Y` unchanged
     - `GCD`: greatest common divisor of `X` and `Y`
     - `LCM`: lowest common multiple of `X` and `Y`
-    - `PRIM`: determine if `X` is a prime, returning 1 if prime, 0 otherwise
+    - `PRIM`: determine if `X` is a prime
+        - returns 1 if prime
+        - returns the smallest prime factor otherwise
+        - See [Prime Factors](#prime-factors) section below.
     - `IP`: integer part of `X`, truncating towards 0, preserving sign
     - `FP`: fractional part of `X`, preserving sign
     - `FLR`: the floor of `X`, the largest integer <= `X`
@@ -662,6 +667,8 @@ buttons just under the LCD screen. Use the `UP`, `DOWN`, `ON` (back), and `MATH`
 - `ROOT` > `BASE`
     - ![BASE MenuStrip 1](docs/rpn83p-screenshot-menu-root-base-1.png)
     - ![BASE MenuStrip 2](docs/rpn83p-screenshot-menu-root-base-2.png)
+    - ![BASE MenuStrip 3](docs/rpn83p-screenshot-menu-root-base-3.png)
+    - ![BASE MenuStrip 4](docs/rpn83p-screenshot-menu-root-base-4.png)
     - `DEC`: use decimal base 10, set base indicator to `DEC`
     - `HEX`: use hexadecimal base 16, set base indicator to `HEX`
         - display all register values as 32-bit unsigned integer
@@ -675,6 +682,16 @@ buttons just under the LCD screen. Use the `UP`, `DOWN`, `ON` (back), and `MATH`
     - `XOR`: `X` `bit-xor` `Y`
     - `NOT`: one's complement of `X`
     - `NEG`: two's complement of `X`
+    - `SL`: shift left one bit
+    - `SR`: shift right one bit
+    - `RL`: rotate left circular one bit
+    - `RR`: rotate right circular one bit
+    - `B+`: add `X` and `Y` using unsigned 32-bit integer math
+    - `B-`: subtract `X` from `Y` using unsigned 32-bit integer math
+    - `B*`: multiply `X` and `Y` using unsigned 32-bit integer math
+    - `B/`: divide `X` into `Y` using unsigned 32-bit integer math
+    - `BDIV`: divide `X` into `Y` with remainder, placing the quotient in `Y`
+      and the remainder in `X`
 - `ROOT` > `STK`
     - ![STK MenuStrip 1](docs/rpn83p-screenshot-menu-root-stk-1.png)
     - `R(up)`: rotate stack up
@@ -820,6 +837,8 @@ The `BASE` functions are available through the `ROOT` > `BASE` hierarchy:
 - ![ROOT MenuStrip 2](docs/rpn83p-screenshot-menu-root-2.png)
     - ![BASE MenuStrip 1](docs/rpn83p-screenshot-menu-root-base-1.png)
     - ![BASE MenuStrip 2](docs/rpn83p-screenshot-menu-root-base-2.png)
+    - ![BASE MenuStrip 3](docs/rpn83p-screenshot-menu-root-base-3.png)
+    - ![BASE MenuStrip 4](docs/rpn83p-screenshot-menu-root-base-4.png)
 
 These functions allow conversion of integers into different bases (10, 16, 8,
 2), as well as performing bitwise functions on those integers (bit-and, bit-or,
@@ -887,14 +906,23 @@ disabled.
 
 > ![Numbers in Binary Mode](docs/rpn83p-screenshot-base-bin.png)
 
-#### Base Rendering
+#### Base Arithmetic
 
-Unlike the HP-42S, the `HEX`, `OCT` and `BIN` modes are simply *display* modes
-that only affect how the numbers are rendered. These modes do not affect any
-arithmetic or mathematical operations. In particular, the arithmetic buttons
-`/`, `*`, `-`, and `+` do not change their behavior in the `HEX`, `OCT`, `BIN`
-modes, in contrast to the HP-42S which remaps those buttons to the `BASE/`,
-`BASE*`, `BASE-`, and `BASE+` functions instead.
+Similar to the HP-42S, the `HEX`, `OCT` and `BIN` modes change how some
+arithmetic functions behave. Specifically, the keyboard buttons `+`, `-`, `*`,
+`/` are re-bound to their bitwise counterparts `B+`, `B-`, `B*`, `B/` which
+perform 32-bit unsigned arithmetic operations instead of floating point
+operations. The numbers in the `X` and `Y` registers are converted into 32-bit
+unsigned integers before the integer subroutines are called.
+
+**HP-42S Compatibility Note**: The HP-42S calls these integer functions `BASE+`,
+`BASE-`, `BASE*`, and `BASE/`. The RPN83P can only display 4-characters in the
+menu bar so I needed to use shorter names. The HP-42S function called `B+/-` is
+called `NEG` on the RPN83P. Early versions of the RPN83P retained the keyboard
+arithmetic buttons bound to their floating point operations, but it became too
+confusing to see hex, octal, or binary digits on the display, but get floating
+point results when performing an arithmetic operation such as `/`. The RPN83P
+follows the lead of the HP-42S for the arithmetic operations.
 
 For example, suppose the following numbers are in the RPN stack in `DEC` mode:
 
@@ -904,24 +932,29 @@ Changing to `HEX` mode shows this:
 
 > ![Base Arithmetic Part 2](docs/rpn83p-screenshot-base-arithmetic-2-hex.png)
 
-Pressing the `+` button adds the `X` and `Y` registers, with no change in
-behavior from the `DEC` mode, including the hidden fractional part:
+Pressing the `+` button adds the `X` and `Y` registers, converting the
+values to 32-bit unsigned integers before the addition:
 
 > ![Base Arithmetic Part 3](docs/rpn83p-screenshot-base-arithmetic-3-plus.png)
 
-Changing back to `DEC` mode shows that the numbers were added normally:
+Changing back to `DEC` mode shows that the numbers were added using integer
+functions, and the fractional digits were truncated:
 
 > ![Base Arithmetic Part 4](docs/rpn83p-screenshot-base-arithmetic-4-dec.png)
 
-#### Base Integers
+You can perform integer arithmetic even in `DEC` mode, by using the `B+`, `B-`,
+`B*`, and `B/` menu functions, instead of the `+`, `-`, `*` and `/` keyboard
+buttons.
+
+#### Base Integer Size
 
 The HP-42S uses a 36-bit *signed* integer for BASE rendering and operations. To
 be honest, I have never been able to fully understand and become comfortable
 with the HP-42S implementation of the BASE operations. First, 36 bits is a
 strange number, it is not an integer size used by modern microprocessors (8, 16,
 32, 64 bits). Second, the HP-42S does not display leading zeros in `HEX` `OCT`,
 or `BIN` modes. While this is consistent with the decimal mode, I find it
-confusing to see the number of rendered bits change depending on its value.
+confusing to see the number of rendered digits change depending on its value.
 
 The RPN83P deviates from the HP-42S by using a 32-bit *unsigned* integer
 internally, and rendering the various HEX, OCT, and BIN numbers using the same
@@ -948,7 +981,7 @@ the negative sign.
 Currently, the integer size for base conversions and functions is hardcoded to
 be 32 bits. I hope to add the ability to change the integer size in the future.
 
-#### Storage Registers
+### Storage Registers
 
 Similar to the HP-42S, the RPN83P provides **25** storage registers labeled
 `R00` to `R24`. They are accessed using the `STO` and `2ND` `RCL` keys. To store
@@ -970,6 +1003,47 @@ get to:
 
 The message `REGS cleared` will be displayed on the screen.
 
+### Prime Factors
+
+The `PRIM` function calculates the lowest prime factor of the number in `X`. The
+result will be `1` if the number is a prime. Unlike almost all other functions
+implemented by RPN83P, the `PRIM` function does not replace the original `X`.
+Instead it pushes the prime factor onto the stack, causing the original `X` to
+move to the `Y` register. This behavior was implemented to allow easier
+calculation of all prime factors of a number as follows.
+
+After the first prime factor is calculated, the `/` can be pressed to calculate
+the remaining factor in the `X` register. We can now press `PRIM` again to
+calculate the next prime factor. Since the `PRIM` preserves the original number
+in the `Y` register, this process can be repeated multiple times to calculate
+all prime factors of the original number.
+
+For example, let's find the prime factors of `119886 = 2 * 3 * 13 * 29 * 53`:
+
+- Press `119886` `ENTER`
+- Press `PRIM` to get `2`
+- Press `/` to divide down to `59943`
+- Press `PRIM` to get `3`
+- Press `/` to divide down to `19981`
+- Press `PRIM` to get `13`
+- Press `/` to divide down to `1537`
+- Press `PRIM` to get `29`
+- Press `/` to divide down to `53`
+- Press `PRIM` to get `1`, which makes `53` the last prime factor.
+
+For computational efficiency, `PRIM` supports only integers between `2` and
+`2^32-1` (4 294 967 295). This allows `PRIM` to use integer arithmetic, making
+it about 7X faster than the equivalent algorithm using floating point routines.
+Any number outside of this range produces an `Err: Domain` message. (The number
+`1` is not considered a prime number.)
+
+If the input number is a very large prime, the calculation may take a long time.
+However, testing has verified that the `PRIM` algorithm will always finish in
+less than about 30 seconds on a TI-83 Plus or TI-84 Plus calculator, no matter
+how large the input number. During the calculation, the "run" indicator on the
+upper-right corner will be active. You press `ON` key to break from loop, and
+the function will exit the function with an `Err: Break` message.
+
 ## Future Enhancements
 
 There seems to be almost an endless number of features that could go into a
@@ -978,18 +1052,6 @@ limited:
 
 ### Near Future
 
-- bit shift and rotation operators
-    - shift left
-    - shift right
-    - rotate left
-    - rotate right
-    - arithmetic shift right (preserve sign bit)
-- `PRIM` (isPrime) is quite slow, about as slow as a TI-BASIC program.
-    - Uses the TI-OS floating numbers and subroutines, which works pretty
-      well for smallish integers.
-    - Can probably make this significantly faster by implementing the algorithm
-      using native Z80 integer operations.
-    - (Need to write a `div(u32, u16) -> u32` function).
 - `PROB` and `COMB` arguments are limited to `< 256`
     - Maybe extend this to `< 2^16` or `<2^32`.
 - `GCD` and `LCM` functions are slow

docs/rpn83p-screenshot-base-arithmetic-3-plus.png

@@ -26,27 +26,31 @@ rpn83p.zip: $(TARGETS)
 	zip -r $@ $^
 
 # Convert markdown to PDF.
-README.pdf: README.md Makefile
-	pandoc -V geometry:margin=1in -V fontsize=12pt -f gfm -s -o $@ $<
+README.pdf: ../README.md Makefile
+	(cd ..; \
+	pandoc -V geometry:margin=1in -V fontsize=12pt -f gfm -s -o $@ README.md; \
+	mv -f $@ release)
 
 # Convert markdown to PDF.
-USER_GUIDE.pdf: USER_GUIDE.md Makefile
-	pandoc -V geometry:margin=1in -V fontsize=12pt -f gfm -s -o $@ $<
+USER_GUIDE.pdf: ../USER_GUIDE.md Makefile
+	(cd ..; \
+	pandoc -V geometry:margin=1in -V fontsize=12pt -f gfm -s -o $@ USER_GUIDE.md; \
+	mv -f $@ release)
 
 # Copy to local directory to place it at top level in the zip file.
-rpn83p.8xk: src/rpn83p.8xk
+rpn83p.8xk: ../src/rpn83p.8xk
 	cp -f $< $@
 
 # Compile the binary if needed.
-src/rpn83p.8xk: src/*.asm
-	$(MAKE) -C src rpn83p.8xk
+../src/rpn83p.8xk: ../src/*.asm
+	$(MAKE) -C ../src rpn83p.8xk
 
 # Copy the animated GIF as a sample screenshot.
-rpn83p-example1.gif: docs/rpn83p-example1.gif
+rpn83p-example1.gif: ../docs/rpn83p-example1.gif
 	cp -f $< $@
 
 # Copy the animated GIF as a sample screenshot.
-rpn83p-example2.gif: docs/rpn83p-example2.gif
+rpn83p-example2.gif: ../docs/rpn83p-example2.gif
 	cp -f $< $@
 
 clean:

docs/rpn83p-screenshot-base-arithmetic-4-dec.png

@@ -13,10 +13,12 @@ SRCS := \
 	handlers.asm \
 	handlertab.asm \
 	input.asm \
+	integer.asm \
 	menu.asm \
 	menudef.asm \
 	menuhandlers.asm \
 	pstring.asm \
+	prime.asm \
 	rpn83p.asm \
 	vars.asm