Skip to content

Commit 8f1416b

Browse files
gewarrengewarren
authored
Update return value tables for Math.Pow (dotnet#9732)
1 parent 4bc7070 commit 8f1416b

File tree

2 files changed

+544
-529
lines changed

2 files changed

+544
-529
lines changed

‎xml/System/Math.xml

+47-43
Original file line numberDiff line numberDiff line change
@@ -6126,42 +6126,46 @@ The following example demonstrates how to use the <xref:System.Math.Min%2A> meth
61266126
<remarks>
61276127
<format type="text/markdown"><![CDATA[
61286128
6129-
## Remarks
6130-
The following table indicates the return value when various values or ranges of values are specified for the `x` and `y` parameters. For more information, see <xref:System.Double.PositiveInfinity?displayProperty=nameWithType>, <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>, and <xref:System.Double.NaN?displayProperty=nameWithType>.
6131-
6132-
| x | y | Return value |
6133-
|--------------------------------|-----------------------------------------------------------|--------------------------------|
6134-
| `NaN` | Any value except 0 | `NaN` |
6135-
| `NaN` | 0 | 1 (`NaN` on .NET Framework) |
6136-
| Any value except `NaN` | 0 | 1 |
6137-
| 1 | Any value except `NaN` | 1 |
6138-
| 1 | `NaN` | 1 (`NaN` on .NET Framework) |
6139-
| Any value except 1 | `NaN` | `NaN` |
6140-
| `NegativeInfinity` | < 0 | 0 |
6141-
| `NegativeInfinity` | Positive odd integer | `NegativeInfinity` |
6142-
| `NegativeInfinity` | Positive but not an odd integer | `PositiveInfinity` |
6143-
| < 0 but not `NegativeInfinity` | Not an integer, `NegativeInfinity`, or `PositiveInfinity` | `NaN` |
6144-
| -1 | = `NegativeInfinity` or `PositiveInfinity` | `NaN` |
6145-
| -1 < x < 1 | `NegativeInfinity` | `PositiveInfinity` |
6146-
| -1 < x < 1 | `PositiveInfinity` | 0 |
6147-
| < -1 or > 1 | `NegativeInfinity` | 0 |
6148-
| < -1 or > 1 | `PositiveInfinity` | `PositiveInfinity` |
6149-
| 0 | < 0 | `PositiveInfinity` |
6150-
| 0 | > 0 | 0 |
6151-
| `PositiveInfinity` | < 0 | 0 |
6152-
| `PositiveInfinity` | > 0 | `PositiveInfinity` |
6153-
6154-
This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures.
6155-
6156-
6129+
The following table indicates the return value when various values or ranges of values are specified for the `x` and `y` parameters. For more information, see <xref:System.Double.PositiveInfinity?displayProperty=nameWithType>, <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>, and <xref:System.Double.NaN?displayProperty=nameWithType>.
6130+
6131+
| x | y | Return value |
6132+
| ------------------------------ | ---------------------------------------- | ---------------------------------------- |
6133+
| Any value except `NaN` | ±0 | 1 |
6134+
| `NaN` | ±0 | 1 (`NaN` on .NET Framework)\* |
6135+
| `NaN` | Any value except 0 | `NaN`\* |
6136+
| ±0 | < 0 and an odd integer | `NegativeInfinity` or `PositiveInfinity` |
6137+
| ±0 | `NegativeInfinity` | `PositiveInfinity` |
6138+
| ±0 | `PositiveInfinity` | +0 |
6139+
| ±0 | > 0 and an odd integer | ±0 |
6140+
| -1 | `NegativeInfinity` or `PositiveInfinity` | 1 |
6141+
| +1 | Any value except `NaN` | 1 |
6142+
| +1 | `NaN` | 1 (`NaN` on .NET Framework)\* |
6143+
| Any value except 1 | `NaN` | `NaN`\* |
6144+
| -1 < x < 1 | `PositiveInfinity` | +0 |
6145+
| < -1 or > 1 | `PositiveInfinity` | `PositiveInfinity` |
6146+
| -1 < x < 1 | `NegativeInfinity` | `PositiveInfinity` |
6147+
| < -1 or > 1 | `NegativeInfinity` | +0 |
6148+
| `PositiveInfinity` | < 0 | +0 |
6149+
| `PositiveInfinity` | > 0 | `PositiveInfinity` |
6150+
| `NegativeInfinity` | < 0 and finite and odd integer | -0 |
6151+
| `NegativeInfinity` | > 0 and finite and odd integer | `NegativeInfinity` |
6152+
| `NegativeInfinity` | < 0 and finite and not an odd integer | +0 |
6153+
| `NegativeInfinity` | > 0 and finite and not an odd integer | `PositiveInfinity` |
6154+
| ±0 | < 0 and finite and not an odd integer | `PositiveInfinity` |
6155+
| ±0 | > 0 and finite and not an odd integer | +0 |
6156+
| < 0 but not `NegativeInfinity` | Finite non-integer | `NaN` |
6157+
6158+
\* These rows don't appear in the full set of rules for `pow` as defined by the [IEEE Standard for Floating-Point Arithmetic](https://standards.ieee.org/ieee/754/6210/). They're included here because .NET disables IEEE 754 floating-point exceptions and thus doesn't differentiate between `qNaN` (quiet NaN) and `sNaN` (signalling NaN). The [IEEE 754](https://standards.ieee.org/ieee/754/6210/) specification allows this exception disablement.
6159+
6160+
This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures.
61576161
61586162
## Examples
61596163
6160-
The following example uses the <xref:System.Math.Pow%2A> method to calculate the value that results from raising 2 to a power ranging from 0 to 32.
6164+
The following example uses the <xref:System.Math.Pow%2A> method to calculate the value that results from raising 2 to a power ranging from 0 to 32.
61616165
6162-
:::code language="csharp" source="~/snippets/csharp/System/Math/Pow/pow1.cs" interactive="try-dotnet-method" id="Snippet1":::
6163-
:::code language="fsharp" source="~/snippets/fsharp/System/Math/Pow/pow1.fs" id="Snippet1":::
6164-
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.pow/vb/pow1.vb" id="Snippet1":::
6166+
:::code language="csharp" source="~/snippets/csharp/System/Math/Pow/pow1.cs" interactive="try-dotnet-method" id="Snippet1":::
6167+
:::code language="fsharp" source="~/snippets/fsharp/System/Math/Pow/pow1.fs" id="Snippet1":::
6168+
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.pow/vb/pow1.vb" id="Snippet1":::
61656169
61666170
]]></format>
61676171
</remarks>
@@ -6293,7 +6297,7 @@ In this section:
62936297
62946298
You can use the following table to select an appropriate rounding method. In addition to the `Math.Round` methods, it also includes <xref:System.Math.Ceiling%2A?displayProperty=nameWithType> and <xref:System.Math.Floor%2A?displayProperty=nameWithType>.
62956299
6296-
|To|Call|
6300+
| To | Call |
62976301
|--------|----------|
62986302
|Round a number to an integer by using the rounding-to-nearest convention.|<xref:System.Math.Round%28System.Decimal%29><br />-or-<br /><xref:System.Math.Round%28System.Double%29>|
62996303
|Round a number to an integer by using a specified rounding convention.|<xref:System.Math.Round%28System.Decimal%2CSystem.MidpointRounding%29><br />-or-<br /><xref:System.Math.Round%28System.Double%2CSystem.MidpointRounding%29>|
@@ -6333,16 +6337,16 @@ The following example illustrates the bias that can result from consistently rou
63336337
63346338
By default, the <xref:System.Math.Round%2A> method uses the round to nearest even convention. The following table lists the overloads of the <xref:System.Math.Round%2A> method and the rounding convention that each uses.
63356339
6336-
|Overload|Rounding convention|
6337-
|--------------|-------------------------|
6338-
|<xref:System.Math.Round%28System.Decimal%29>|<xref:System.MidpointRounding.ToEven>|
6339-
|<xref:System.Math.Round%28System.Double%29>|<xref:System.MidpointRounding.ToEven>|
6340-
|<xref:System.Math.Round%28System.Decimal%2CSystem.Int32%29>|<xref:System.MidpointRounding.ToEven>|
6341-
|<xref:System.Math.Round%28System.Double%2CSystem.Int32%29>|<xref:System.MidpointRounding.ToEven>|
6342-
|<xref:System.Math.Round%28System.Decimal%2CSystem.MidpointRounding%29>|Determined by `mode` parameter.|
6343-
|<xref:System.Math.Round%28System.Double%2CSystem.MidpointRounding%29>|Determined by `mode` parameter|
6344-
|<xref:System.Math.Round%28System.Decimal%2CSystem.Int32%2CSystem.MidpointRounding%29>|Determined by `mode` parameter|
6345-
|<xref:System.Math.Round%28System.Double%2CSystem.Int32%2CSystem.MidpointRounding%29>|Determined by `mode` parameter|
6340+
| Overload | Rounding convention |
6341+
| ------------------------------------------------------------------------------------- | ------------------------------------- |
6342+
| <xref:System.Math.Round%28System.Decimal%29> | <xref:System.MidpointRounding.ToEven> |
6343+
| <xref:System.Math.Round%28System.Double%29> | <xref:System.MidpointRounding.ToEven> |
6344+
| <xref:System.Math.Round%28System.Decimal%2CSystem.Int32%29> | <xref:System.MidpointRounding.ToEven> |
6345+
| <xref:System.Math.Round%28System.Double%2CSystem.Int32%29> | <xref:System.MidpointRounding.ToEven> |
6346+
| <xref:System.Math.Round%28System.Decimal%2CSystem.MidpointRounding%29> | Determined by `mode` parameter. |
6347+
| <xref:System.Math.Round%28System.Double%2CSystem.MidpointRounding%29> | Determined by `mode` parameter |
6348+
| <xref:System.Math.Round%28System.Decimal%2CSystem.Int32%2CSystem.MidpointRounding%29> | Determined by `mode` parameter |
6349+
| <xref:System.Math.Round%28System.Double%2CSystem.Int32%2CSystem.MidpointRounding%29> | Determined by `mode` parameter |
63466350
63476351
<a name="precision"></a>
63486352
### Rounding and precision

0 commit comments

Comments
 (0)