Enhancement: add log based 2 and log base n builtin functions

[lcn2]

Add log2(x [,eps]) builtin function for log base 2.

When x is an intger power of 2, including a negative power of 2, be sure that log2(x) returns an exact integer. Otherwise compute and return the equivalent of the expression ln(x) / ln(2).

The code that implements the builtin function ilog2() will assist in detecting when n x is an intger power of 2.

Add logn(x, n, [,eps]) builtin function for log base n.

When x is an integer power of n, including a negative power of n, be sure that logn(x, n) returns an exact integer. Otherwise compute and return the equivalent of the expression ln(x) / ln(n).

The code that implements the builtin function ilog() will assist in detecting when n x is an intger power of n.

Of course, check for bogus/invalid values of x and n and raise an error if given.

[lcn2]

The following would be invalid and raise an error:

; log2(0);
; logn(0,n);
; logn(x,0);

The values x and n must be numeric or an error will be raised:

; log2("fred");
; logn("curds", 7);
; logn("curds", "whey");

[lcn2]

No doubt, some people will have already implemented their own log2() and logn() user defined functions. Adding these builtin functions will break that code. Therefore we would need to release them under calc version 2.15. See help release for details as to why. Nevertheless this new "version x.y" should not be a major impediment to adding these builtin functions.

We will need to write help files help/log2 and help/logn.

We will need to update the regression test suite cal/regress.cal with various checks and sanity tests for these 2 new builtin functions.

[lcn2]

For the new builtin function log2(x [,eps]), the x will be allowed to be a nonzero real or complex value.

For the new builtin function logn(x, n [,eps]), the x and the n will be allowed to be a nonzero real or complex values.

So, this will work:

; log2(3.456);
; log2(4.5i + 6);
; logn(3.456, 5);
; logn(2.7i, ln(5));
; logn(2i, 4i);
; log2(4.5, 1e-50);
; logn(27, 3.6, 1e-75);
; log2(pi(1e-100), 1e-100);
; logn(pi(1e-100), pi(1e-100), 1e-100);
; logn(pi(1e-100), exp(1, 1e-100), 1e-100);
... etc.

[lcn2]

With commit 5a117d542aa38c14bcab3da93a7535fa19ac1513 we added help in advance for new log2 and logn builtins

NOTE: The log2(x [,eps]) and logn(x, n [,eps]) builtin functions are NOT yet implemented.

It is our general practice to write the documentation first. :-)

[lcn2]

When x is an integer power of n, including a negative power of n, be sure that logn(x, n) returns an exact integer. Otherwise compute and return the equivalent of the expression ln(x) / ln(n).

The above requirement is proving a big tricky, especially when the log base n is non-integer or even a complex number.

We can mange this when n is a power of 2 just fine. We might, for other values if n simply rely on epsilon and approximate as best as calc can.

Comments and/or suggestions on this matter are welcome.

[lcn2]

With commit 4dbc4dfe9a7f078ac00814487d6d1113117ed0e9 we have added a new bulletin function log2(x [,eps]).

Added log2(x [,eps]) builtin function.  When x is an integer
power of 2, log2(x) will return an integer, otherwise it will
return the equivalent of ln(x)/ln(2).

Next we will work on the logn(x, n [,eps]) function.

[lcn2]

FYI: With commit 1c839dfedec07f70d5ce07a21028c3517ec94a30, the log2(x) and logn(x, n) builtin functions have been added, @jrom99

We expect to release calc version 2.15.x with this code in the near future.