Confirm merge from FromPublicMasterBranch to main to sync with https://github.com/MicrosoftDocs/cpp-docs (branch main) (#4878)

learn-build-service-prod[bot] · huypub · TylerMSFT · web-flow · commit 54d8386acf76 · 2023-04-15T01:05:30.000+08:00
* 3/31 AM Publish (#4859) * fix SAL annotation * acrolinx * go with _Out_opt_ and annotate the sample with why --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> * Update assert-asserte-assert-expr-macros.md (#4496) * 4/10/2023 AM Publish (#4868) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> * Update attributes.md (#4498) * 4/11/2023 AM Publish (#4869) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> * remove unneeded `To` * 4/12/2023 AM Publish (#4872) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> * 4/13/2023 AM Publish (#4876) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text * Confirm merge from FromPublicMasterBranch to main to sync with https://github.com/MicrosoftDocs/cpp-docs (branch main) (#4867) * 3/31 AM Publish (#4859) * fix SAL annotation * acrolinx * go with _Out_opt_ and annotate the sample with why --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> * Update assert-asserte-assert-expr-macros.md (#4496) * 4/10/2023 AM Publish (#4868) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> * Update attributes.md (#4498) * 4/11/2023 AM Publish (#4869) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> * remove unneeded `To` * 4/12/2023 AM Publish (#4872) * alt-text updates * acrolinx * fix image links, acrolinx * update alt-text * fixup text --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> --------- Co-authored-by: huypub <38988242+huypub@users.noreply.github.com> Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com> Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com> Co-authored-by: LuShuchen <50068848+LuShuchen@users.noreply.github.com> Co-authored-by: Taojunshen <v-jutao@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> Co-authored-by: Terry Mahaffey <terry.mahaffey@gmail.com> Co-authored-by: Igor Zhukov <fsb4000@yandex.ru> Co-authored-by: Shannon Leavitt <V-SHLEAV@microsoft.com> --------- Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com> Co-authored-by: huypub <38988242+huypub@users.noreply.github.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com> Co-authored-by: LuShuchen <50068848+LuShuchen@users.noreply.github.com> Co-authored-by: Terry Mahaffey <terry.mahaffey@gmail.com> Co-authored-by: Igor Zhukov <fsb4000@yandex.ru> Co-authored-by: Shannon Leavitt <V-SHLEAV@microsoft.com> * Remove unmatched left bracket in stl-containers.md * Add missing quotation mark in algorithms.md * Fix punctuation typo in functional.md --------- Co-authored-by: huypub <38988242+huypub@users.noreply.github.com> Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com> Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com> Co-authored-by: LuShuchen <50068848+LuShuchen@users.noreply.github.com> Co-authored-by: Taojunshen <v-jutao@microsoft.com> Co-authored-by: James Barnett <v-jabarnett@microsoft.com> Co-authored-by: Terry Mahaffey <terry.mahaffey@gmail.com> Co-authored-by: Igor Zhukov <fsb4000@yandex.ru> Co-authored-by: Shannon Leavitt <V-SHLEAV@microsoft.com> Co-authored-by: Martin Schonger <martin@schonger.dev> Co-authored-by: Courtney Wales <62625502+Court72@users.noreply.github.com>
diff --git a/docs/cpp/attributes.md b/docs/cpp/attributes.md
@@ -167,3 +167,40 @@ The Microsoft-specific attribute `[[msvc::noinline_calls]]` has the same usage a
 ### `[[msvc::no_tls_guard]]`
 
 The Microsoft-specific `[[msvc::no_tls_guard]]` attribute disables checks for initialization on first access to thread-local variables in DLLs. The checks are enabled by default in code built using Visual Studio 2019 version 16.5 and later versions. This attribute applies only to the specific variable that follows it. To disable checks globally, use the [`/Zc:tlsGuards-`](../build/reference/zc-tlsguards.md) compiler option.
+
+### `[[msvc::forceinline]]`
+
+This Microsoft specific `[[msvc::forceinline]]` attribute has the same meaning as `__forceinline` when placed before a function declaration. 
+
+### `[[msvc::forceinline_calls]]`
+
+This Microsoft specific `[[msvc::forceinline_calls]]` attribute can be placed on before a statement or a block, and will cause the inline heurisitc to attempt to forceinline all calls in that statement or block:
+
+```cpp
+void f() {
+    [[msvc::forceinline_calls]]
+    {
+        foo();
+        bar();
+    }
+    ...
+    [[msvc::forceinline_calls]]
+    bar();
+    
+    foo();
+}
+```
+
+Here, the first call to `foo` and both calls to `bar` will be treated as if they were declared `__forceinline`, but not the second call to `foo`.
+
+### `[[msvc::noinline]]`
+
+This Microsoft specific `[[msvc::noinline]]` attribute has the same meaning as `declspec(noinline)` when placed before a function declaration. 
+
+### `[[msvc::noinline_calls]]`
+
+This Microsoft specific `[[msvc::noinline_calls]]` attribute has the same usage as `[[msvc::forceinline_calls]]`, and can be placed before any statement or block. Rather than forceinlining all calls in that block, however, it has the effect of turning off inlining for the scope to which it is applied.
+
+### `[[msvc::flatten]]`
+
+This Microsoft specific `[[msvc::flatten]]` attribute is very similar to `[[msvc::forceinline_calls]]`, and can be used in the same places and in the same way. The difference is flatten will dutifully forceinline all calls in the scope to which it is applied recursively, until no calls are left. This may have consequences for the resulting code size growth of the function or the throughput of the compiler, which the user must manage manually.
diff --git a/docs/standard-library/algorithms.md b/docs/standard-library/algorithms.md
@@ -18,7 +18,7 @@ The descriptions of the algorithm function templates employ several shorthand ph
 
 - The phrase "the lowest value of *N* in the range \[*A*, *B*) such that *X*" means that the condition *X* is determined for each *N* in the range \[*A*, *B*) until the condition *X* is met.
 
-- The phrase "the highest value of *N* in the range \[*A*, *B*) such that *X* means that *X* is determined for each *N* in the range \[*A*, *B*). The function stores in *K* a copy of *N* each time the condition *X* is met. If any such store occurs, the function replaces the final value of *N*, which equals *B*, with the value of *K*. For a bidirectional or random-access iterator, however, it can also mean that *N* begins with the highest value in the range and is decremented over the range until the condition *X* is met.
+- The phrase "the highest value of *N* in the range \[*A*, *B*) such that *X*" means that *X* is determined for each *N* in the range \[*A*, *B*). The function stores in *K* a copy of *N* each time the condition *X* is met. If any such store occurs, the function replaces the final value of *N*, which equals *B*, with the value of *K*. For a bidirectional or random-access iterator, however, it can also mean that *N* begins with the highest value in the range and is decremented over the range until the condition *X* is met.
 
 - Expressions such as *X* - *Y*, where *X* and *Y* can be iterators other than random-access iterators, are intended in the mathematical sense. The function doesn't necessarily evaluate operator **-** if it must determine such a value. The same is also true for expressions such as *X* + *N* and *X* - *N*, where *N* is an integer type.
 
diff --git a/docs/standard-library/functional.md b/docs/standard-library/functional.md
@@ -20,7 +20,7 @@ Defines C++ Standard Library functions that help construct *function objects*, a
 
 Algorithms require two types of function objects: *unary* and *binary*. Unary function objects require one argument, and binary function objects require two arguments. A function object and function pointers can be passed as a predicate to an algorithm, but function objects are also adaptable and increase the scope, flexibility, and efficiency of the C++ Standard Library. If, for example, a value needed to be bound to a function before being passed to an algorithm, then a function pointer could not be used. Function adaptors convert function pointers into adaptable function objects that can be bound to a value. The header \<functional> also contains member function adaptors that allow member functions to be called as adaptable function objects. Functions are adaptable if they have nested type declarations specifying their argument and return types. Function objects and their adaptors allow the C++ Standard Library to upgrade existing applications and help integrate the library into the C++ programming environment.
 
-The implementation of the function objects in \<functional> includes *transparent operator functors*. which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less<MyType>())`.
+The implementation of the function objects in \<functional> includes *transparent operator functors*, which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less<MyType>())`.
 
 The following features are added in C++11, C++14 and C++17:
 
diff --git a/docs/standard-library/stl-containers.md b/docs/standard-library/stl-containers.md
@@ -142,7 +142,7 @@ In general, elements inserted into a C++ Standard Library container can be of ju
 
 The destructor isn't permitted to throw an exception.
 
-Ordered associative containers—described earlier in this article—must have a public comparison operator defined. (By default, the operator is `operator<`, but even types that don't work with `operator<` are supported.
+Ordered associative containers—described earlier in this article—must have a public comparison operator defined. By default, the operator is `operator<`, but even types that don't work with `operator<` are supported.
 
 Some operations on containers might also require a public default constructor and a public equivalence operator. For example, the unordered associative containers require support for equality and hashing.
 
