Merge branch 'master' into mb-cmake2

Author: ghogen

docs/cpp-conformance-improvements-2017.md

@@ -231,6 +231,7 @@
 ## [Lambda Expressions in C++](lambda-expressions-in-cpp.md)
 ### [Lambda Expression Syntax](lambda-expression-syntax.md)
 ### [Examples of Lambda Expressions](examples-of-lambda-expressions.md)
+### [constexpr Lambda Expressions](lambda-expressions-constexpr.md)
 ## [Arrays (C++)](arrays-cpp.md)
 ### [Using Arrays (C++)](using-arrays-cpp.md)
 ### [Initializing Arrays](initializing-arrays.md)

docs/cpp/TOC.md

@@ -10,25 +10,54 @@ ms.assetid: 748340d9-8abf-4940-b0a0-91b6156a3ff8
 caps.latest.revision: 11
 manager: "ghogen"
 ---
-# C++ Standard Attributes
+# Attributes in C++
+ The C++ Standard defines a set of attributes and also allows compiler vendors to define their own attributes (within a vendor-specific namespace), but compilers are required to recognize only those attributes defined in the standard. 
+
+ In some cases, standard attributes overlap with compiler-specific declspec parameters. In Visual C++, you can use the `[[deprecated]]` attribute instead of using `declspec(deprecated)` and the attribute will be recognized by any conformant compiler. For all other declspec parameters such as dllimport and dllexport, there is as yet no attribute equivalent so you must continue to use declspec syntax. Attributes do not affect the type system, and they don’t change the meaning of a program. Compilers ignore attribute values they don't recognize.
+
+**Visual Studio 2017 version 15.3 and later**(available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)): In the scope of an attribute list, you can specify the namespace for all names with a single `using` introducer:
+
+```cpp
+void g() {
+[[ using rpr: kernel , target(cpu,gpu)]] // equivalent to [[ rpr::kernel, rpr::target(cpu,gpu) ]]
+do task();
+}
+```   
+
+## C++ Standard Attributes
 In C++11, attributes provide a standardized way to annotate C++ constructs (including but not limited to classes, functions, variables, and blocks) with additional information that may or may not be vendor-specific. A compiler can use this information to generate informational messages, or to apply special logic when compiling the attributed code. The compiler ignores any attributes that it does not recognize, which means that you cannot define your own custom attributes using this syntax. Attributes are enclosed by double square brackets:  
 
 ```  
 [[deprecated]]  
 void Foo(int);    
 ```  
 
- Attributes represent a standardized alternative to vendor-specific extensions such as #pragma directives, __declspec() (Visual C++), or \__attribute\_\_ (GNU). However, you will still need to use the vendor-specific constructs for most purposes. The standard currently specifies three attributes that a conforming compiler should recognize:  
+ Attributes represent a standardized alternative to vendor-specific extensions such as #pragma directives, __declspec() (Visual C++), or \__attribute\_\_ (GNU). However, you will still need to use the vendor-specific constructs for most purposes. The standard currently specifies the following attributes that a conforming compiler should recognize:  
 
--   `noreturn` -- specifies that a function never returns; in other words it always throws an exception. The compiler can adjust its compilation rules for [[noreturn]] entities.  
+-   `noreturn` Specifies that a function never returns; in other words it always throws an exception. The compiler can adjust its compilation rules for `[[noreturn]]` entities.  
 
--   `carries_dependency`--specifies that the function propagates data dependency ordering with respect to thread synchronization. The attribute can be applied to one or more parameters, to specify that the passed-in argument carries a dependency into the function body. The attribute can be applied to the function itself, to specify that the return value carries a dependency out of the function. The compiler can use this information to generate more efficient code.  
+-   `carries_dependency` Specifies that the function propagates data dependency ordering with respect to thread synchronization. The attribute can be applied to one or more parameters, to specify that the passed-in argument carries a dependency into the function body. The attribute can be applied to the function itself, to specify that the return value carries a dependency out of the function. The compiler can use this information to generate more efficient code.  
 
--   `deprecated` - **Visual Studio 2015 and later:** specifies that a function is not intended to be used, and might not exist in future versions of a library interface. The compiler can use this to generate an informational message when client code attempts to call the function. Can be applied to declaration of a class, a typedef-name, a variable, a non-static data member, a function, a namespace, an enumeration, an enumerator, or a template specialization.  
+-   `deprecated` - **Visual Studio 2015 and later:** Specifies that a function is not intended to be used, and might not exist in future versions of a library interface. The compiler can use this to generate an informational message when client code attempts to call the function. Can be applied to declaration of a class, a typedef-name, a variable, a non-static data member, a function, a namespace, an enumeration, an enumerator, or a template specialization.  
+
+-   `[[fallthrough]]` - **Visual Studio 2017 and later:** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)) The `[[fallthrough]]` attribute can be used in the context of [switch](switch-statement-cpp.md) statements as a hint to the compiler (or anyone reading the code) that the fallthrough behavior is intended. The Visual C++ compiler currently does not warn on fallthrough behavior, so this attribute has no effect compiler behavior.
+
+- `[[nodiscard]]` **Visual Studio 2017 version 15.3 and later:** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)) Specifies that a function's return value is not intended to be discarded. Raises warning C4834, as shown in the following example
+ 
+```cpp
+[[nodiscard]]
+int foo(int i) { return i * i; }
+
+int main()
+{
+	foo(42); //warning C4834: discarding return value of function with 'nodiscard' attribute
+    return 0;
+}
+```
 
--   `fallthrough` - **Visual Studio 2017 and later:**(available with [/std:c++latest](../build/reference/std-specify-language-standard-version.md)) The `[[fallthrough]]` attribute can be used in the context of [switch](switch-statement-cpp.md) statements as a hint to the compiler (or anyone reading the code) that the fallthrough behavior is intended. The Visual C++ compiler currently does not warn on fallthrough behavior, so this attribute has no effect compiler behavior.
+- `[[maybe_unused]]` **Visual Studio 2017 version 15.3 and later:** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)) Specifies that a variable, function, class, typedef, non-static data member, enum, or template specialization may intentionally not be used. The compiler does not warn when an entity marked `[[maybe_unused]]` is not used. An entity that is declared without the attribute can later be redeclared with the attribute and vice versa. An entity is considered marked after its first declaration that is marked is analyzed, and for the remainder of translation of the current translation unit.
 
-**Microsoft-specific:**
+## Microsoft-specific attributes
   
 -   `gsl::suppress`  -- this Microsoft-specific attribute is used for suppressing warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider the code snippet below  
   
@@ -55,4 +84,3 @@ void Foo(int);
   
    The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing [[gsl::suppress(bounds)]] without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they are not wanted.  
   
- The C++ standard allows compiler vendors to define their own attribute parameters (within a vendor-specific namespace), but compilers are required to recognize only those attributes defined in the standard. In Visual C++, you can use the [[deprecated]] attribute instead of using declspec (deprecated) and the attribute will be recognized by any conformant compiler. For all other declspec parameters such as dllimport and dllexport, there is as yet no standard attribute equivalent so you must continue to use declspec syntax. Attributes do not affect the type system, and they don’t change the meaning of a program. Compilers ignore attribute values they don't recognize.

docs/cpp/attributes2.md

@@ -39,6 +39,8 @@ translation.priority.ht:
 ---
 # bool (C++)
 This keyword is a built-in type. A variable of this type can have values [true](../cpp/true-cpp.md) and [false](../cpp/false-cpp.md). Conditional expressions have the type `bool` and so have values of type `bool`. For example, `i!=0` now has **true** or **false** depending on the value of `i`.  
+
+**Visual Studio 2017 version 15.3 and later** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)): The operand of a postfix or prefix increment or decrement operator may not be of type `bool`. 
 
  The values **true** and **false** have the following relationship:  
 
@@ -55,7 +57,10 @@ if (condexpr1) statement1;
 
  If `condexpr1` is **true**, `statement1` is always executed; if `condexpr1` is **false**, `statement1` is never executed.  
 
- When a postfix or prefix `++` operator is applied to a variable of type `bool`, the variable is set to **true**. The postfix or prefix `--` operator cannot be applied to a variable of this type.  
+ When a postfix or prefix `++` operator is applied to a variable of type `bool`, the variable is set to **true**. 
+**Visual Studio 2017 version 15.3 and later**: operator++ for bool was removed from the language and is no longer supported.
+
+The postfix or prefix `--` operator cannot be applied to a variable of this type.  
 
  The `bool` type participates in integral promotions. An r-value of type `bool` can be converted to an r-value of type `int`, with **false** becoming zero and **true** becoming one. As a distinct type, `bool` participates in overload resolution.  
 

docs/cpp/bool-cpp.md

@@ -56,7 +56,9 @@ if( Amount > 100 )
     Alert();  
 }  
 else  
+{
     Balance -= Amount;  
+}
 ```  
 
 > [!NOTE]

docs/cpp/compound-statements-blocks.md

@@ -62,23 +62,25 @@ enum [class|struct]
 
 ```  
 // Forward declaration of enumerations  (C++11):  
-enum A : int; // non-scoped enum must have type specifiedenum class B; // scoped enum defaults to intenum class C : short;  
+enum A : int; // non-scoped enum must have type specified
+enum class B; // scoped enum defaults to int but ...
+enum class C : short;  // ... may have any integral underlying type
 ```  
 
-#### Parameters  
+## Parameters  
  `identifier`  
  The type name given to the enumeration.  
 
  `type`  
  The underlying type of the enumerators; all enumerators have the same underlying type. May be any integral type.  
 
  `enum-list`  
- Comma-separated list of the enumerators in the enumeration. Every enumerator or variable name in the scope must be unique. However, the values can be duplicated. In a unscoped enum, the scope is the surrounding scope; in a scoped enum, the scope is the `enum-list` itself.  
+ Comma-separated list of the enumerators in the enumeration. Every enumerator or variable name in the scope must be unique. However, the values can be duplicated. In a unscoped enum, the scope is the surrounding scope; in a scoped enum, the scope is the `enum-list` itself.  In a scoped enum, the list may be empty which in effect defines a new integral type.
 
  `class`  
  By using this keyword in the declaration, you specify the enum is scoped, and an `identifier` must be provided. You can also use the `struct` keyword in place of `class`, as they are semantically equivalent in this context.  
 
-## Remarks  
+## Enumerator scope  
  An enumeration provides context to describe a range of values which are represented as named constants and are also called enumerators. In the original C and C++ enum types, the unqualified enumerators are visible throughout the scope in which the enum is declared. In scoped enums, the enumerator name must be qualified by the enum type name. The following example demonstrates this basic difference between the two kinds of enums:  
 
 ```cpp  
@@ -123,7 +125,7 @@ enum Suit { Diamonds = 5, Hearts, Clubs = 4, Spades };
 
  Then the values of `Diamonds`, `Hearts`, `Clubs`, and `Spades` are 5, 6, 4, and 5, respectively. Notice that 5 is used more than once; this is allowed even though it may not be intended. These rules are the same for scoped enums.  
 
- **Casting rules**  
+ ## Casting rules  
 
  Unscoped enum constants can be implicitly converted to `int`, but an `int` is never implicitly convertible to an enum value. The following example shows what happens if you try to assign `hand` a value that is not a `Suit`:  
 
@@ -162,7 +164,45 @@ namespace ScopedEnumConversions
 
 ```  
 
- Notice that the line `hand = account_num;` still causes the error that occurs with unscoped enums, as shown earlier. It is allowed with an explicit cast. However, with scoped enums, the attempted conversion in the next statement, `account_num = Suit::Hearts;`, is no longer allowed without an explicit cast.  
+ Notice that the line `hand = account_num;` still causes the error that occurs with unscoped enums, as shown earlier. It is allowed with an explicit cast. However, with scoped enums, the attempted conversion in the next statement, `account_num = Suit::Hearts;`, is no longer allowed without an explicit cast. 
+
+## Enums with no enumerators
+**Visual Studio 2017 version 15.3 and later** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)): By defining an enum (regular or scoped) with an explicit underlying type and no enumerators, you can in effect introduce a new integral type that has no implicit conversion to any other type. By using this type instead of its built-in underlying type, you can eliminate the potential for subtle errors caused by inadvertent implicit conversions.  
+
+
+```cpp
+enum class byte : unsigned char { };
+```
+
+The new type is an exact copy of the underlying type, and therefore has the same calling convention, which means it can be used across ABIs without any performance penalty. No cast is required when variables of the type are initialized by using direct-list initialization. The following example shows how to initialize enums with no enumerators in various contexts:
+
+```cpp
+enum class byte : unsigned char { };
+
+enum class E : int { };
+E e1{ 0 };
+E e2 = E{ 0 };
+
+struct X 
+{
+    E e{ 0 };
+    X() : e{ 0 } { }
+};
+
+E* p = new E{ 0 }; 
+
+void f(E e) {};
+
+int main()
+{
+    f(E{ 0 });
+    byte i{ 42 };
+    byte j = byte{ 42 };
+
+    // unsigned char c = j; // C2440: 'initializing': cannot convert from 'byte' to 'unsigned char'
+    return 0;
+}
+``` 
 
 ## See Also  
  [C Enumeration Declarations](../c-language/c-enumeration-declarations.md)   

docs/cpp/enumerations-cpp.md

@@ -282,15 +282,26 @@ int main()
 
 ### Example  
  You can use lambda expressions in the body of a function. The lambda expression can access any function or data member that the enclosing function can access. You can explicitly or implicitly capture the `this` pointer to provide access to functions and data members of the enclosing class.  
+**Visual Studio 2017 version 15.3 and later** (available with [/std:c++17](../build/reference/std-specify-language-standard-version.md)): Capture `this` by value (`[*this]`) when the lambda will be used in asynchronous or parallel operations where the code might execute after the original object goes out of scope.
 
  You can use the `this` pointer explicitly in a function, as shown here:  
 
 ```cpp  
+
+// capture "this" by reference
 void ApplyScale(const vector<int>& v) const  
 {  
    for_each(v.begin(), v.end(),   
       [this](int n) { cout << n * _scale << endl; });  
 }  
+
+// capture "this" by value (Visual Studio 2017 version 15.3 and later)
+void ApplyScale2(const vector<int>& v) const  
+{  
+   for_each(v.begin(), v.end(),   
+      [*this](int n) { cout << n * _scale << endl; });  
+}  
+
 ```  
   
  You can also capture the `this` pointer implicitly: