ALCALC - Al Weiner's Calculator

Version 0.0.117, 16 Sept 97


--- generic "hello" message ---


Thanks for trying AlCalc!

AlCalc is a high precision calculator for the US Robotics Pilot.

AlCalc is a work-in-progress; I'm constantly improving it and adding
new capabilities (and given the number of suggestions and features
people have suggested, I think it's turned into lifetime work!)  :)

As a few features are still unimplemented (like the percent key -
it's there, but hasn't been "hooked up" yet) I'm still calling this a
"beta" version.


This document is a rough draft to cover some of the features and
capabilities, historical and development information, and additional
information about AlCalc.
I will be updating this document (and AlCalc itself) frequently.

Please check at my web site (http://www.ajw.com) for the most recent
version.

I'm also very interested in what you like and dislike about AlCalc -
if you'd like to see different features or enhancements, please email
me!  Send comments, suggestions, questions, and praise to alan@ajw.com

- Al Weiner -

email:  alan@ajw.com
web:    http://www.ajw.com



--- specific "hello" message for this release ---

This version fixes a number of little problems that have been nagging
at me.  I completely rewrote the display routine - it's shorter,
faster, and fixes the bugs and adds features - what more could I have
asked for!  :)
Both the floating-decimal and engineering modes now work properly.

Another convenience feature, the menu now drops down if you tap the
upper-left corner of the display.  Tap and hold; the menu drops down,
and then you can drag down to select the menu item you'd like.

At this point, almost all of the intended-for-first-release features
are working (and a bunch of other features too) so I've decided it's
time to bump AlCalc from "alpha" to "beta"

I've got a long list of features to be implemented; don't worry that
I won't be working on improvements!


Enjoy!

- Al -


---------------
AlCalc Features
---------------

High precision - up to 38 decimal digits.  AlCalc uses a 128-bit
signed mantissa and a 16-bit signed exponent

Scrolling display - the display can scroll left and right to show all
the digits.  It can be configured to display a fixed or floating
decimal point.

Multiple number bases - In addition to the floating-point mode,
AlCalc provides an Integer Mode which can be set for non-decimal
number bases.  It supports base 2 (binary) through base 36.

Memory keys - AlCalc provides 24 memory keys

Programmer's functionality - being a programmer myself, I wanted the
functions I use every day while programming.  In addition to
non-decimal number bases, AlCalc handles boolean operations - AND,
OR, XOR, NOT, and shifts (logical and arithmetic)



--------------------------------
Disclaimer and legal mumbo-jumbo
--------------------------------

I've taken great effort to avoid releasing software with bugs. 
(there are unimplemented functions, but that's a different story - my
list of features to be added is quite long - and I (and other users)
keep coming up with new ideas!)

However, there is some chance that there is a problem.  (this is true
of any software - if it's bug-free, it just means there are only
*unknown* bugs...)

Therefore, AlCalc is provided "as-is" and without warranty of any
kind, express or implied.  I can accept no liability for data loss or
any other problems caused directly or indirectly by the use of
AlCalc.

AlCalc is copyright 1997 by Alan Jay Weiner.
It is shareware; this means that you may try it for a time, and if
you decide to continue using it you should register it.  (see the
registration section for the details)  If you decide not to register
it, you really should stop using it.

You may give unregistered copies to others under the same terms -
they may try it and then either register or remove it.  Please do NOT
give out the registration code number.

AlCalc (and this document) may be included on any disk or CDROM of
shareware sold by non-profit organizations.  If you wish to include
it in a commercial software collection, please contact me at
alan@ajw.com



---------------
KNOWN PROBLEMS:
---------------

As far as I know, this version is stable - it doesn't crash nor give
wrong answers.

PLEASE let me know if you find otherwise.

Not all functions are implimented, and there are several dead keys
and dead options.


----------------------
description of screen:
----------------------

The top gray box is the entry and totals display

To the right of the display are two arrows (normally they aren't
displayed)  They scroll the display left and right; when either or
both are displayed, it means there are more digits "off the screen"
in that direction.  Press the arrow to scroll the display toward that
direction.

Three fields are underneath the display box; from left to right they
are:

The current number base (or 'float' for floating-point [decimal]
mode) is shown in a drop-down list.  Press this field to drop down a
scrollable list of number bases.  AlCalc supports bases 2 through 36. 
The most commonly used bases are float (decimal), binary, octal, decimal
(integer mode), and hex (base 16); these are at the start of the
list, in addition to within the scrollable list at the appropriate
points.

To the right of the number-base list is a "section" symbol.  (this
looks like a little circle with curved lines off of it, or like a
"whirling wind" symbol meterologists use)
This "button" flips between the current number base and the
last-selected base.  This makes it easy to convert numbers from
decimal to hex, for example.

The current function (add sub mul, etc) is displayed on the far
right.  This was originally just for my debugging; enough people
liked it, it's staying as a feature.   (note:  currently it shows '+'
after clearing the display; soon I'll change that so it doesn't show
anything after clearing; it'll show the function when you press a
function key)


Below these are the number pad and operations keys.

--- Operation Keys ---

The main display shows the digits 0..9, period, and equals, and the
following operations:

+ - x /	  addition, subtraction, multiplication, division

x10^	press to start entering the exponent  (e.g., 12.345x10^20)

+ / -	during entry, switches positive to negative and vice-versa.
	if pressed prior to x10^ key, switches the mantissa.  if
	pressed after the x10^ key, switches the exponent.
	(note:  currently a digit must be entered before the +/- key
	will take effect; I'll be changing this to allow " +/- 123"
	to enter "-123")

clr	when lower case ("clr") clears the entry value (the number
	being entered.)  then it changes to CLR.  Pressing it when
	it's showing CLR clears the calculator  (the accumulated
	value)

bsp	backspaces during entry.  deletes the rightmost character.

%	(note:  the percent key is not yet implemented)
	adds, subtracts, or calculates a percentage

sqrt	calculates the square root of the value displayed

mem	enters memory mode - memory mode displays the memory keys and
	the operations which may be performed on them

key	changes the operations keys to the next set.  (currently
	there are two sets - the main display and the alternate
	"programmer's" set)


-----------
Known bugs:
-----------


Enter 0 0 0 0 0 .
at decimal point, only 4 digits displayed

Enter .000000  (continue entering zeros - about 150 of them)
Eventually causes a fatal exception

Can't enter decimal point after 'e'   (to indicate a fractional
decimal point - e.g., 123e.25   --->  123 x 10 ^ .25)


--------------------------------------
Unimplimented (planned) functionality:
--------------------------------------

% key does nothing

no bit-rotation  (just shifts)

only single-bit shifts  (I want both single and multiple-bit shifts
and rotates)

display formatting isn't complete
	- no 'digits' seperator (in integer mode)

display the memory-location's value while the memory button is held
down.

integer-mode displays don't properly handle sign bits; displays
signed if 128 bits, unsigned otherwise

scroll-button management; always uses scroll buttons on right side of
display, regardless of preferences



-------------------------
Registration information:
-------------------------

AlCalc is shareware.  This allows you to try it out and see that it's
something you wish to continue using.  If you don't like it, you
don't have to pay for it.
If you do like it, please register.

AlCalc will remind you to register the first time you use it each day. 
After 25 days, it will nag (uh, I mean "remind") :)  you each time
you use it.

When you register, I will send you a registration code to turn off
the reminders.
  
	registration fee:	$15 (US dollars)
  
	payment methods:	Pilotgear
				First Virtual
				Check

--- PILOTGEAR ---

Pilotgear is the easiest - you can register on the web by buying a
copy of AlCalc from their web site by credit-card using their secure
web page.
Pilotgear's main page is:
	http://www.pilotgear.com

or go to my web site at:
	http://www.ajw.com/
and click on the "Buy it at Pilotgear" button, then click the "I want
it!" button on Pilotgear's AlCalc page.

You can call Pilotgear at 817-461-3480 (or fax at 817-461-3480).
While you're on their site or talking to them, check out some of the
other Pilot software and hardware!


--- FIRST VIRTUAL ---

First Virtual is also easy; it's basically an identification number
that you email me.  (they call it a PIN, but I wish they didn't;
usually we keep PINs confidential.)

I send that number to First Virtual, telling them you wish to charge
$15 to purchase AlCalc.

They will email you telling you that I wish to charge your First
Virtual account for that $15.

You then email them back saying "yes" (you accept the charge) or "no"
(you don't want to pay after all) or "fraud" (this is not a charge
you initiated).

This last part - "fraud" - along with the email charge confirmation
helps to prevent fraudulent use of your PIN.  If someone else gets
ahold of it, when they use it, you'll get an email before the charge
goes through - when you respond "fraud" the account is immediately
canceled. (Your email account is tied to the PIN, you'll get the
confirmation email regardless of where they email the PIN from.)

For more information about First Virtual, or to set up an account,
see the First Virtual web site at http://www.fv.com

Eventually I'll set up an on-line registration form, but for now you
can email me:

	Your email address 
	Your First Virtual buyer's PIN 
	How many copies of AlCalc you wish to register 
	If you want, you can send your snail-mail address; I don't
	have any need or use for it right now, but I am curious what
	part of the world you're in. (being an international businessman
	will inflate my ego!) :) 

	Send this to alan@ajw.com

	I will hold all information strictly confidential and will not
	send you any junk mail or email, nor give or sell it to anyone.
	(except for sending your PIN to First Virtual for the charge,
	of course!)

If you want to register by snail-mail, you can send a check or money
order (in US dollars, please) to:

	Alan Weiner
	1409 Great Plain Avenue
	Needham, MA 02192

Please send your email address too, so I can send you a confirmation
of receipt and the registration code. (if you don't have an email
address, please send a snail-mail address so I can send it to you.)




=====================================================================

			HISTORY - List of changes

			(newest changes first)

=====================================================================


----------------------------------
BETA version 0.0.117	16 Sept 97
----------------------------------

changed from "alpha" to "beta"  (and it's about time!)

tapping the top line above the display drops the menu down.

completely rewrote the display routine - this fixes:
  "Engineering" display - this forces scientific display and
  adjusts so the exponent is a multiple of three.

  floating-decimal display; now shows up to the number of digits
  selected to the right of the decimal point.

  commas inserted to the left of the decimal point  (or periods, as
  set in the system preferences)

added preference option (display settings) to enable or disable the
commas (or periods) to the left of the decimal point.
It's titled "enable 1000s separators"

added help screen to Display Settings dialog


---------------------------------
ALPHA version 0.0.116a	16 July 97
---------------------------------

changed preferences to allow 1-bit integers  (integers were required
to be 2..<mantissa size>; now allows 1..)  Why anyone would want
single-bit integers is beyond me, but AlCalc allows it now.


---------------------------------
ALPHA version 0.0.115j	10 July 97
---------------------------------

fixed problem with square-roots with large mantissas - should now
work correctly with all numbers.
It's still slow, but I'm going to work on enhancing functionality
more than speed for now.


---------------------------------
ALPHA version 0.0.115i	9 July 97
---------------------------------

square-root functionality is almost complete.  only known problem is
if the mantissa is very close to "full"  (all bits set except the
sign bit)
(actually, the other known problem is it's too slow)

changed post-calculation handling for unary operators ! (factorial)
and Sqrt - for convenience (mine) it was doing a ficticious "=" after
the calculation (this forced the value to display as if it were a
result instead of a just-entered number)
Now displays the value as a result (using display preferences)
without doing the ficticious "="
So if you did:
	123 + 100 SQRT =
you get "133" when you press the =


added "working" display to square-root calculation  (displays
"working" in the result-display area while calculating the square
root)


---------------------------------
ALPHA version 0.0.115e	3 July 97
---------------------------------

first version with square root key.
Square root function is not complete; should work for values 0 and
up; no testing yet for negative numbers.  Large numbers (exponents
larger than around 15 or 20) will take a long time.  (30-60 seconds
and up)

---------------------------------
ALPHA version 0.0.115a	17 June 97
---------------------------------

optimizations to division

---------------------------------
ALPHA version 0.0.115	13 June 97
---------------------------------

fixed bug where changing any configuration settings would
cause a "Object not in form" error on some systems.

(other changes in progress not included in version 115)


---------------------------------
ALPHA version 0.0.114	3 June 97
---------------------------------

various optimizations to math package

"last base" selection wasn't initialized; now is.  (this could cause
a "string error" the first time "last base" is selected after a new
installation.

initial implementation of Exp()  (e^X)   (disabled temporarily)


---------------------------------
ALPHA version 0.0.113	28 May 97
---------------------------------

fixed bug in entering negative exponents - entering too many digits
would change it to a positive exponent

changed my email and web addresses in the About screen

fixed bug in backspace (when backspacing over a negative exponent,
gave wrong result)

fixed bug in entered-value display  (displayed ".0002e3" with an
incorrect exponent.  occurred when the number of digits entered to
the right of the decimal point was greater than the exponent)

fixed spurious delay when using large negative exponents

changed wording of overflow and underflow alerts.

completed underflow and overflow handling

number entry won't overflow anymore.  digits that will cause overflow
are ignored.

minor changes to number-entry; slightly smaller, slightly faster

preferences option to allow/disallow leading zero display when
entering floating-point numbers (leading zeros always displayed in
integer mode)

fix to size of display area; if using comma as decimal point the
display would fail to clear the bottom pixel of the comma when
clearing the display area.

several optimizations to math package

optimizations to math package


---------------------------------
ALPHA version 0.0.112a	16 May 97
---------------------------------

Detects changing the number base to the same as currently set (e.g., 
"float" to "float") and doesn't re-set the same base.  This
eliminates the annoying flash of the keys and preserves the
"last-base" toggle so it switches between the last two *different*
base settings.

additional overflow handling

changed Memory Recall to display numbers as totals - this causes it
the recalled value to be properly displayed, but prevents adding
digits - entering a digit will now clear the display (the recalled
value)

misc optimizations


---------------------------------
ALPHA version 0.0.112	14 May 97
---------------------------------

fixed exponent entry; permitted 32769  (should have stopped at 32767)

fixed display problem; now properly handles exponents over +/- 32767
(since there are 38 digits, exponent can reach 32767 + 38 = 32805, as
in 1.234...e32805)

fixed problem with negative exponents (introduced in version 111e I
think)

fixed problem entering "1.2345e3"  (entered incorrect garbage exponent)

changed "base" display and drop-down list to larger font size

changed so test builds use their own data; version 111e shared data
with the release build.  (this is slightly less convenient, but
safer)

made scroll buttons slightly larger  (arrows are same size; the
button itself covers more space, so it's a bit easier to tap)

fixed bug in multiplication of large numbers  (multiplying two large
numbers would sometimes return a negative number)

added 'swap with last base' button  (to right of base selection)
This button sets the base to the previous selection.  This makes it
easier when swapping between two bases.

changed the 'e' (for exponent) key to 'x10^' to (hopefully) better
indicate its meaning (that you'll enter the value's exponent

changes to math package to support overflow and underflow detection

added alert screen when overflow occurs - gives the option to cancel
any calculation or to continue, using the maximum possible value

fixed problem with (floating-point) multiplying and dividing with
negative numbers


---------------------------------
ALPHA version 0.0.111	19 Apr 97
---------------------------------

bugs fixed:
	factorials crashed (on PalmPilot Professionals only) with
	factorials larger than 33 - fixed.

	fixed bug in registration code


added detection of invalid factorial arguments; they now pop up a
message.  (cannot take factorials of non-integers or negative
numbers)

now correctly gives 0! as 1

floating-point mode only keys (like decimal point, %, n!) are now
redisplayed when switching from integer mode back to floating-point
mode.


---------------------------------
ALPHA version 0.0.110	17 Apr 97
---------------------------------

bugs fixed:
	addition and subtraction with negative numbers didn't always
	work correctly.  (introduced in version 106)

new install now uses the same preferences and display settings as the
"normal" buttons.

floating-point multiplication now handles mantissa overflow
(*exponent* overflow is still not handled)

added factorial key

made buttons larger

keys which are valid only in floating-point mode are now properly
disabled.  (there were some keys which would reappear after "mem"
or "key" keys were used)

changed CLR key to clear-entry; a second press clears the total. 
initially the key shows "clr" to indicate the clear-entry key. 
Pressing it the first time clears the entry value and changes the key
to show "CLR".  Pressing it a second time (when displaying "CLR")
clears the total,  Pressing any other key returns the key to the
clear-entry setting (and showing "clr").

changed registration codes (disabled debug codes)


---------------------------------
ALPHA version 0.0.106	11 Apr 97
---------------------------------

bug fix:  Memory Recall displayed correct value, but didn't use that
value in expression.  (regardless what memory is set to, 1 + MemX
gave 2)   (bug introduced in version 0.0.052)

added Preferences screen; configures:
	Large digits in floating-point mode  (checkbox)

	Complement:	1's, 2's, unsigned
	Binary Bits:	number field

	Sticky Memory mode (checkbox)

	buttons:
		ok	accepts changes
		cancel	ignores changes; leaves preferences unchanged
		normal	sets normal settings (then press Ok to accept)

	Normal settings are:	Decimal Only, 2's complement,
				Sticky Memory disabled, 128 bits


Memory mode recognizes sticky setting.  If sticky is disabled, then
after a memory operation (Mem +, Mem -, Mem Clr, Mem Rcl) the
keyboard returns to the main (numeric-keys) display.  If sticky is
enabled, then it stays showing the memory-location keys; press the
Mem key to return to normal.

Changed number-base selection to a drop-down list (where the base was
displayed; beneath the value display)

Now handles configurable number of bits in integer mode.

added floating-point number handling.  (E-notation doesn't display)

Added preferences option to use larger digits while in floating-point
mode.  Display changes as configured.

Added horizontal scrolling (currently with scroll buttons only on the
right)

Added Graffiti support - digits (0..9 and A..Z for higher bases),
period, backspace, return (does equals button)
(Graffiti is the only way to enter digits G..Z for higher bases)

Disables invalid keypad keys - digit keys which aren't valid for the
current number base, decimal key if not in floating-point mode

moved % key; added 'e' entry key for floating point

display now shows left-most digits after a calculation; rightmost
during value entry. (either may be scrolled left/right)

added nag screen (display once per day until 25 days, then
displays every time started)

added registration menu selection and screen


----------------------
ALPHA version 0.0.052
----------------------

Mem key now defaults to Mem A.
This allows hitting Mem then immediately selecting M + or M -

fixed problem where entering digits following M + or M - didn't start
a new entry value; they were treated as still inputting the initial
number.  (so 1 2 3 Mem M+ 4 5 6 M M+ M Mrcl now shows 579)

----------------------
ALPHA version 0.0.051
----------------------

added test for divide by zero; divide by zero displays an alert
dialog

memory recall now actually works


----------------------
ALPHA version 0.0.050
----------------------

memory keys now work
'mem' is a prefix.  press 'mem' and the left keys change to A..X (for
24 memory storage locations)  select the memory location; then the
following keys become available:
	M +	add displayed value to that memory
	M -	subtract displayed value from that memory
	Mclr	clear that memory storage
	Mrcl	recall that memory storage into the displayed value
You may select a different A..X location before doing any of the
memory functions.
You may cancel memory functions by hitting 'mem' again.

I feel that it needs a "sticky" memory prefix option; it's annoying
sometimes that you have to go through the 'mem' 'letter' business
every time you want to do something with the memories...
If you enable "sticky" it will stay in memory-mode until you hit
'mem' again. so if you want to do several calculations on the
memories it's a bit easier.

I also want to display the memory's value while you're holding the
button down.  (this allows you to be sure you're changing what you
*think* you're changing)



