[phobos] Proposed changes to std.math + introduce std.mathspecial

[Don Clugston]

>> (1) Add two necessary functions to std.math:
>>
>> // Rounds x to the nearest int or long using the currently selected
>> rounding mode
>> // (MUCH faster than cast(int)).
>
> Why isn't this the default, i.e. why doesn't cast(int) do this?

Because C stuffed up in a major way, and we have to live with it.
Intel has tried THREE TIMES to fix C's mistake, by making hardware
changes and adding new instructions to their CPUs.

> Please use full words when abbr is not absolutely obvious and/or the gain in typing is small (esp for rarely used functions).
>  (also sgngamma --> signgamma)

I didn't invent the name. sgn is the signum function. See, for example,
http://en.wikipedia.org/wiki/Sign_function

>To an uninitiated reader this may look like "random int" and "random long".

Ugh, you're right.

>Could we define this instead?
> N roundTo(N)(real x) if (isIntegral!N);

That sounds a bit too formal. I would expect that to perform some
exact form of rounding (certainly not round-to-nearest, which seems
irrational to our uninitiated reader). I would also expect it to do
something sensible when the value is > int.max.
This function should really be an intrinsic, and it only makes sense
for int and long.

fastRoundInt(real x)
fastRoundLong(real x)
?
A bit clumsy, but should be unambiguous.

>Is there a particular reason not to just put them all in std.math? It at least
>seems like it would be simpler to do that - particularly from a usage
> standpoint. I take it that there's some reason why that's undesirable?

Three reasons.
1. std.math includes some very simple, well known stuff like sqrt()
and abs(). It's extremely daunting for a casual user to be hit with
advanced mathematics.
2. The "Special Functions" are a well-defined group of functions. They
form a very natural common namespace.
Even for people (like me) who use them, they're typically only
imported into one or two modules in the whole project. By contrast,
std.math is imported into nearly module I have.
3. If you put them into std.math, you then have to ask, why isn't
everything else in std.math too? Linear algebra? Where do you stop?
Creating mathspecial sends a clear message: std.math is just for
elementary functions and low-level functions.

>"Special"... what's special about these functions? I'm not sure why they can't be in std.math, but if we have this module I don't feel >"special" is an appropriate term for it. Supplement, Advanced, Extra might be better terms.

They are called "Special Functions" in mathematics.
eg, http://eqworld.ipmnet.ru/en/auxiliary/aux-specfunc.htm