Updating the generic math design doc to account for additional changes

[tannergooding]

This namely covers usage of DIMs and gives additional sample code showing how DIMs might be used in various functions. This helps show the layering is "sound" and gives some examples of how future changes might be implemented when that becomes relevant.

[tannergooding]

I'd recommend reviewing the doc "as a whole", rather than only looking at the changes in this PR.

Noting this is also not "complete" and will build up some more changes (several APIs need to move down to INumberBase still) before the API review on May 10th

[tannergooding]

FYI. @stephentoub that this includes the changes necessary for LINQ Min/Max.

[dakersnar]

I read through the file and skimmed the code parts. I really like the "Scenarios" section. Seems like there is more to do but your additions in this PR look mostly mechanical. Out of curiosity, when you make updates like this, are you copy pasting code into this file, or is it auto generated somehow?

Couple spelling mistakes I happened to spot:

"...Jeff is trying to compute the standard deviation of a list of numbers. They are surprised to find that such a function isn't built into .NET. After searching the web, Jeff finds a blog post with the following method..."

• Change "they" to "he" to be consistent with later pronouns, I think.

"…that allow Jeff to implement the desired method without requiring users types to take a dependency on types they…"

• Add a ' after "users"?

"we need to strike a balance between expressiveness, exxtensibility, and cost."

• Typo: "exxtensibility"

[terrajobst]

• long GetSignificandShortestBitLength() should return int
• Let's bias towards explicit implementations on the primitives, especially for concepts that generally only make in the generic context (or already exist under a different name)
• Char, CLong, CULong should probably implement everything explicitly
• We don't plan to implement these interfaces outside the BCL (e.g. the core types and types in System.Numerics)
  • For example, the SQL types
• INumberConverter<T, U>
  • Should have three methods, ConvertChecked, ConvertUnchecked, ConvertTruncated
  • No try versions

[tannergooding]

Will update the design doc according to the feedback to ensure it stays up to date/correct and then will merge

[tannergooding]

Updated doc according to the feedback. Noting that that the Parse methods aren't DIM because TryParse only returns bool and that isn't enough to disambiguate between overflow and format failures

[govert]

@tannergooding
It would be very helpful to add a member like IFloatingPoint.MachineEpsilon or IFloatingPoint.EpsilonUnitRoundoff into these interfaces. This will help address a very common error when porting numerical code to .NET. I think a mistake was made when the .NET BCL defined double.Epsilon, float.Epsilon etc. as ‘the smallest representable value that is greater than zero’. In other languages and most computation arithmetic, the value of ‘epsilon’ is given by the ‘Machine Epsilon’ as the difference between 1 and the next larger floating point number. See https://en.wikipedia.org/wiki/Machine_epsilon . Also compare the definition of std:numeric_limits::epsilon in C++ https://en.cppreference.com/w/cpp/types/numeric_limits/epsilon Similar for FORTRAN: https://gcc.gnu.org/onlinedocs/gfortran/EPSILON.html

So the name ‘epsilon’ is used for a crucial constant that has a different value in most numerical algorithm settings than in the .NET CLR. It's not easy to discover this difference and it may have significant impact in an algorithm.

Obviously one can’t go back to fix this 'mistake' in the .NET BCL, but the numerical interfaces seem like a good opportunity to help mitigate this issue a bit. One question might relate to the naming – it would be nice to have a name that points in the right direction, yet is easy to discover in a member list, e.g. if it starts with ‘Epsilon’ as the prefix.