You put this in the correct place. This isn’t really a documentation problem, though there is a documentation component to it.
The question is, what should be done about this at this point in time? If starting from scratch, there could be a function called eulersnumber(, and another function called eulersconstant(. That would be mathematically correct.
However, I think doing that now might be a bad idea. There maybe users that have used the eulersconstant( function in their code, based on that fact that it actually returns eulers number. Like myself, they may not have been aware of these two different, confusingly named, values. If the eulersconstant( function is changed to the correct value, their existing code would calculate the wrong results. They would have no warning, it would just be wrong.
I see two possibilities:
Rename the function as eulersnumber(, but also allow eulersconstant( to continue to work as it does now. So either would work. The documentation would have a note added to mention this.
Same as #1, but completely remove the eulersconstant( function. If this is done, existing code would have to be changed, but there would be an error, rather than silently performing the wrong calculation. Again, the documentation would note this.
Either way, there would be no built in convenience function that would return Euler’s constant. I think this is ok. Apple has a list of common constant values built into macOS, including pi and eulers number. Euler’s constant is not provided by Apple. I think Euler’s constant is much less commonly used, so if anyone needed it, they could just enter the value manually.
My instinct is to go for option #1, but does anyone have any thoughts on this?
That said, you still could have a correct Euler’s constant by changing the constant’s function name. And documenting it as usual.
I agree that it is likely seldom used. I discovered the problem by serendipity. When I saw it I just wondered what is was since I knew Euler’s Number. I just checked to see if it was synonymous with Euler’s Number.
Most of the languages I have used provide at least two mathematical constants via either pseudovariables or functions — the ratio of the circumference of a circle to its diameter (π) and the base of natural logarithms (e) — but usually named using a representation in the Latin alphabet of the letter conventionally used, i.e., PI, pi or pi() and E, e or e(). And Panorama X already has a function named pi() rather than, say, circumferenceoverdiameter().
I would suggest retaining the existing function eulersconstant() for backward compatibility, but explain in the documentation the error (or at least ambiguity) of nomenclature and mark it as deprecated. And then introduce two new functions, e() for the base of natural logarithms (Euler’s number, e) and gamma() for Euler’s constant (ɣ).
This is Constance Mayer. I’m submitting her photo as a potential graphic for this Euler’s value issue;
I can see how these things happen. Maybe she was Euler’s girlfriend and when he’d take her to a party, people would say, “There’s Euler’s Constance.” and others would remark, “She’s quite a number.”
From her posture in the graphic, you can see she’s had to deal with this for a long time. Maybe the graphic can be assigned to the help topic.
I’ve added a eulersnumber( function. The eulersconstant( function still exists and still returns eulers number, but is no longer documented except for a note on the eulersnumber( page, which you can read here.
I am not going to use gamma( to return Euler’s constant. Gamma has too many other meanings, I don’t think it should be used for this. Its use for the Euler-Mascheroni constant is only the 8th listed in this Wikipedia page for gamma.
Panorama has long allowed use of the π symbol for pi, and a pi( function. When implementing Panorama X I noticed that Apple’s headers defined the value for E, so I thought why not include that also.
/* Even though these might be more useful as long doubles, POSIX requires
that they be double-precision literals. */
#define M_E 2.71828182845904523536028747135266250 /* e */
Note that this header file just calls this value E. Until George mentioned it 3 days ago I had never heard of Euler’s number vs. Euler’s constant, so I just assumed it was “constant”.
There are dozens or maybe even hundreds of possible constants that could be included in Panorama, but I think that is outside Panorama’s core mission, and at this point I would simply view them as hundreds of opportunities for new bugs. Apple includes only definitions for pi and Euler’s number (and I think they inherited that from UNIX/POSIX), so I think that’s good enough for Panorama also. Any other constants will need to be manually typed in as you need them. Or you could set up your own custom function.
I think gamma( is not a great idea, just because gamma is used in various other domains (like image processing) and that would just confuse image processing-type people like myself. All one of us, possibly
