Convert.ToInt32 Method (Double)

<#
.SYNOPSIS
    This script is a re-write of an MSDN sample which
    demonstrates rouding done by .NET (and therefore
    by PowerShell)
.DESCRIPTION
    This script creates an array of values then tries to convert them to
    a [double], catching errors. I've added two values from the MSDN
    C# sample. I also adjusted the formatting to line the numbers up 
    better.
.NOTES 
    File Name  : .\Show-Roundijng.ps1 
    Author     : Thomas Lee - tfl@psp.co.uk 
    Requires   : PowerShell Version 2.0 
.LINK 
    This script posted to:
        http://pshscripts.blogspot.com
    MSDN sample posted to: 
         http://msdn.microsoft.com/en-us/library/ffdk7eyz.aspxcl   
.EXAMPLE  
     An example of using the command
     PSH>: .\show-rounding.ps1
    -1.79769313486232E+308 is outside the range of the Int32 type
    -13800000000 is outside the range of the Int32 type
    Converted the Double value '  -1023.299' to the Int32 value  -1023
    Converted the Double value '     -12.98' to the Int32 value    -13
    Converted the Double value '          0' to the Int32 value      0
    Converted the Double value '  9.113E-16' to the Int32 value      0
    Converted the Double value '        4.5' to the Int32 value      4
    Converted the Double value '        5.5' to the Int32 value      6
    Converted the Double value '    103.919' to the Int32 value    104
    Converted the Double value '  17834.191' to the Int32 value  17834
    1.79769313486232E+308 is outside the range of the Int32 type
#>

[double[]] $values= ([system.Double]::MinValue, -1.38e10, -1023.299, -12.98,
                   0, 9.113e-16,4.5, 5.5, 103.919, 17834.191, [System.Double]::MaxValue)

foreach ($value in $values) {
   try {
      $result = [System.Convert]::ToInt32($value);
      "Converted the {0} value '{1,11}' to the {2} value {3,6}" -f $value.GetType().Name, $value,
                        $result.GetType().Name,$result
   }
  catch {
           "{0} is outside the range of the Int32 type" -f  $value
         }
 }

"value, rounded to the nearest 32-bit signed integer. If value is halfway between two whole numbers, the even number is returned; that is, 4.5 is converted to 4, and 5.5 is converted to 6."

4.5 == 5 BUT 5.5 == 6????

The documentation is correct

I'm not certain whether you believe that the documentation is in error, or whether you don't like the method implementation.

The documentation is correct. Midpoint values of exactly .5 are rounded to the nearest even integer, so 4.5 rounds to 4, and 5.5 rounds to 6. This method of rounding (which is termed banker's rounding in the documentation) aims to avoid a statistical bias by consistently rounding midpoint values upward. The following example illustrates this behavior:

      double[] values = { 4.5, 5.5 };
      foreach (var value in values)
         Console.WriteLine("{0} --> {1}", value, Convert.ToInt32(value));
      // The code displays the following output:   
      // 4.5 -->; 4
      // 5.5 --> 6

In some cases, it may appear that a midpoint value is not rounded to the nearest even number. This typically occurs when a Double value results from intermediate calculations and there is a loss of precision. For example, in the following example, 11.5 rounds to 12, but if a Double value of 11.0 is incremented by .1 five time, the resulting value of 11.5 rounds to 11 rather than 12. This occurs because the addition operation results in a loss of precision, as displaying the value with the "r" standard format specifier illustrates.

      double value = 11.5;
      Console.WriteLine("{0:#.0} -> {1}\n", value, Convert.ToInt32(value));
      value = 11.0;
      do {
         Console.WriteLine("{0:#.0} ({0:r}) -> {1}", 
                           value, Convert.ToInt32(value));
         value += .1;
      } while (value <= 12.0);

      // The example displays the following output:
      //       11.5 -> 12
      //       
      //       11.0 (11)   -> 11
      //       11.1 (11.1) -> 11
      //       11.2 (11.2) -> 11
      //       11.3 (11.299999999999999) -> 11
      //       11.4 (11.399999999999999) -> 11
      //       11.5 (11.499999999999998) -> 11
      //       11.6 (11.599999999999998) -> 12
      //       11.7 (11.699999999999998) -> 12
      //       11.8 (11.799999999999997) -> 12
      //       11.9 (11.899999999999997) -> 12
      //       12.0 (11.999999999999996) -> 12          

If you would prefer to use common symmetric rounding (rounding of midpoint values always occurs in a single direction), you can call the Math.Round(Double, MidpointRounding) method and supply of value of MidpointRounding.AwayFromZero to the second argument.

I hope that this helps.

--Ron Petrusha
Common Language Runtime Developer Content
Microsoft Corporation