Merge pull request #2493 from corob-msft/cr-float-control-contract

float_control update clarifies scope

Author: v-albemi

docs/preprocessor/fenv-access.md

@@ -1,6 +1,7 @@
 ---
 title: "fenv_access pragma"
-ms.date: "08/29/2019"
+description: "Describes the usage and effects of the fenv_access pragma directive. The fenv_access directive controls access to the floating-point environment at runtime."
+ms.date: "11/19/2019"
 f1_keywords: ["vc-pragma.fenv_access", "fenv_access_CPP"]
 helpviewer_keywords: ["pragmas, fenv_access", "fenv_access pragma"]
 ms.assetid: 2ccea292-0ae4-42ce-9c67-cc189299857b
@@ -15,9 +16,17 @@ Disables (**on**) or enables (**off**) optimizations that could change floating-
 
 ## Remarks
 
-By default, **fenv_access** is **off**. If the compiler can assume that your code does not access or manipulate the floating-point environment, then it can perform many floating-point code optimizations. Set **fenv_access**  to **on** to inform the compiler that your code accesses the floating-point environment to test status flags, exceptions, or to set control mode flags. The compiler disables these optimizations so that your code can access the floating-point environment consistently.
+By default, **fenv_access** is **off**. The compiler assumes your code doesn't access or manipulate the floating-point environment. If environment access isn't required, the compiler can do more to optimize your floating-point code.
 
-For more information on floating-point behavior, see [/fp (Specify Floating-Point Behavior)](../build/reference/fp-specify-floating-point-behavior.md).
+Enable **fenv_access** if your code tests floating-point status flags, exceptions, or sets control mode flags. The compiler disables floating-point optimizations, so your code can access the floating-point environment consistently.
+
+The [/fp:strict] command-line option automatically enables **fenv_access**. For more information on this and other floating-point behavior, see [/fp (Specify Floating-Point Behavior)](../build/reference/fp-specify-floating-point-behavior.md).
+
+There are restrictions on the ways you can use the **fenv_access** pragma in combination with other floating-point settings:
+
+- You can't enable **fenv_access** unless precise semantics are enabled. Precise semantics can be enabled either by the [float_control](float-control.md) pragma, or by using the [/fp:precise](../build/reference/fp-specify-floating-point-behavior.md) or [/fp:strict](../build/reference/fp-specify-floating-point-behavior.md) compiler options. The compiler defaults to **/fp:precise** if no other floating-point command-line option is specified.
+
+- You can't use **float_control** to disable precise semantics when **fenv_access(on)** is set.
 
 The kinds of optimizations that are subject to **fenv_access** are:
 
@@ -65,7 +74,7 @@ int main() {
 out=9.999999776482582e-03
 ```
 
-If you comment out `#pragma fenv_access (on)` from the previous sample, note that the output is different because the compiler does compile-time evaluation, which does not use the control mode.
+If you comment out `#pragma fenv_access (on)` from the previous sample, the output is different. It's because the compiler does compile-time evaluation, which doesn't use the control mode.
 
 ```cpp
 // pragma_directive_fenv_access_2.cpp

docs/preprocessor/float-control.md

@@ -1,6 +1,7 @@
 ---
 title: "float_control pragma"
-ms.date: "08/29/2019"
+description: "Describes the usage and effects of the float_control pragma directive. The float_control directive controls the state of floating-point precise semantics and exception semantics at runtime."
+ms.date: "11/18/2019"
 f1_keywords: ["vc-pragma.float_control", "float_control_CPP"]
 helpviewer_keywords: ["float_control pragma", "pragmas, float_control"]
 ms.assetid: 4f4ba5cf-3707-413e-927d-5ecdbc0a9a43
@@ -12,50 +13,70 @@ Specifies floating-point behavior for a function.
 ## Syntax
 
 > **#pragma float_control**\
-> **#pragma float_control(** { **precise** | **strict** | **except** } **,** { **on** | **off** } [ **, push** ] **)**\
+> **#pragma float_control( precise,** { **on** | **off** } [ **, push** ] **)**\
+> **#pragma float_control( except,** { **on** | **off** } [ **, push** ] **)**\
 > **#pragma float_control(** { **push** | **pop** } **)**
 
 ## Options
 
-**precise** | **strict** | **except**, **on** | **off**, **push**\
-Specifies floating-point behavior, which can be **precise**, **strict**, or **except**. For more information, see [/fp (Specify Floating-Point Behavior)](../build/reference/fp-specify-floating-point-behavior.md). The setting can either be **on** or **off**.
+**precise**, **on** | **off**, **push**\
+Specifies whether to enable (**on**) or disable (**off**) precise floating-point semantics. For information on how this option differs from the similarly named **/fp:precise** compiler option, see the Remarks section. The optional **push** token tells the compiler to push the current setting for **float_control** on the internal compiler stack.
 
-When **strict**, the settings for both **strict** and **except** are specified by the **on** or **off** setting. **except** can only be set to **on** when **precise** or **strict** is also set to **on**.
+**except**, **on** | **off**, **push**\
+Specifies whether to enable (**on**) or disable (**off**) floating-point exception semantics. For information on how this option differs from the similarly named **/fp:except** compiler option, see the Remarks section. The optional **push** token tells the compiler to push the current setting for **float_control** on the internal compiler stack.
 
-If the optional **push** token is added, the current setting for **float_control** is pushed on to the internal compiler stack.
+**except** can only be set to **on** when **precise** is also set to **on**.
 
 **push**\
-Push the current **float_control** setting on to the internal compiler stack
+Pushes the current **float_control** setting on to the internal compiler stack.
 
 **pop**\
-Removes the **float_control** setting from the top of the internal compiler stack and makes that the new **float_control** setting.
+Removes the **float_control** setting from the top of the internal compiler stack, and makes that the new **float_control** setting.
 
 ## Remarks
 
-You cannot use **float_control** to turn **precise** off when **except** is on. Similarly, **precise** cannot be turned off when [fenv_access](../preprocessor/fenv-access.md) is on. To go from strict model to a fast model by using the **float_control** pragma, use the following code:
+The **precise** and **except** options don't have exactly the same behavior as the [/fp](../build/reference/fp-specify-floating-point-behavior.md) compiler options of the same names. The **float_control** pragma only governs part of the floating-point behavior. It must be combined with [fp_contract](../preprocessor/fp-contract.md) and [fenv_access](../preprocessor/fenv-access.md) pragmas to recreate the **/fp** compiler options. The following table shows the equivalent pragma settings for each compiler option:
+
+| | float_control(precise, \*) | float_control(except, \*) | fp_contract(\*) | fenv_access(\*) |
+|-|-|-|-|-|
+| /fp:strict             | on  | on  | off | on  |
+| /fp:strict /fp:except- | on  | off | off | on  |
+| /fp:precise            | on  | off | on  | off |
+| /fp:precise /fp:except | on  | on  | on  | off |
+| /fp:fast               | off | off | on  | off |
+
+In other words, you must use several pragmas in combination to emulate the **/fp:fast**, **/fp:precise**, **/fp:strict**, and **/fp:except** command-line options.
+
+There are restrictions on the ways you can use the **float_control** and **fenv_access** floating-point pragmas in combination:
+
+- You can only use **float_control** to set **except** to **on** if precise semantics are enabled. Precise semantics can be enabled either by the **float_control** pragma, or by using the **/fp:precise** or **/fp:strict** compiler options.
+
+- You can't use **float_control** to turn **precise** off when exception semantics are enabled, whether by a **float_control** pragma or a **/fp:except** compiler option.
+
+- You can't enable **fenv_access** unless precise semantics are enabled, whether by a **float_control** pragma or a compiler option.
+
+- You can't use **float_control** to turn **precise** off when **fenv_access** is enabled.
+
+These restrictions mean the order of some floating-point pragmas is significant. To go from a fast model to a strict model using the **float_control** and related pragmas, use the following code:
 
 ```cpp
-#pragma float_control(except, off)
-#pragma fenv_access(off)
-#pragma float_control(precise, off)
+#pragma float_control(precise, on)  // enable precise semantics
+#pragma fenv_access(on)             // enable environment sensitivity
+#pragma float_control(except, on)   // enable exception semantics
+#pragma fp_contract(off)            // disable contractions
 ```
 
-To go from fast model to a strict model with the **float_control** pragma, use the following code:
+To go from a strict model to a fast model by using the **float_control** pragma, use the following code:
 
 ```cpp
-#pragma float_control(precise, on)
-#pragma fenv_access(on)
-#pragma float_control(except, on)
+#pragma float_control(except, off)  // disable exception semantics
+#pragma fenv_access(off)            // disable environment sensitivity
+#pragma float_control(precise, off) // disable precise semantics
+#pragma fp_contract(on)             // ensable contractions
 ```
 
 If no options are specified, **float_control** has no effect.
 
-Other floating-point pragmas include:
-
-- [fenv_access](../preprocessor/fenv-access.md)
-
-- [fp_contract](../preprocessor/fp-contract.md)
-
 ## Example
 
 The following sample shows how to catch an overflow floating-point exception by using pragma **float_control**.
@@ -100,4 +121,6 @@ Pass
 
 ## See also
 
-[Pragma directives and the __pragma keyword](../preprocessor/pragma-directives-and-the-pragma-keyword.md)
+[Pragma directives and the __pragma keyword](../preprocessor/pragma-directives-and-the-pragma-keyword.md)\
+[fenv_access](../preprocessor/fenv-access.md)\
+[fp_contract](../preprocessor/fp-contract.md)