Merge pull request MicrosoftDocs#1932 from dmitrykobets/patch-1

Colin Robertson · web-flow · commit 9584d4c1da90 · 2020-02-24T12:38:41.000-08:00
Document new rule C26817
diff --git a/docs/code-quality/c26817.md b/docs/code-quality/c26817.md
@@ -0,0 +1,71 @@
+---
+title: C26817
+description: "Reference for Microsoft C++ Code Analysis warning C26817 in Visual Studio."
+ms.date: 02/24/2020
+ms.topic: "reference"
+f1_keywords: ["C26817"]
+helpviewer_keywords: ["C26817"]
+---
+# C26817
+
+> Potentially expensive copy of variable *name* in range-for loop. Consider making it a const reference (es.71).
+
+For more information, see [ES.71 notes](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#note-217) in the C++ Core Guidelines.
+
+## Example
+
+If a range-for loop variable isn't explicitly marked as a reference, it gets a copy of each element iterated over:
+
+```cpp
+#include <vector>
+
+class MyComplexType { 
+    int native_array[1000];
+    // ...
+};
+
+void expensive_function(std::vector<MyComplexType>& complex_vector_ref)
+{
+    for (auto item: complex_vector_ref)
+    {
+        // At each iteration, item gets a copy of the next element
+        // ...
+    }
+    for (MyComplexType item: complex_vector_ref)
+    {
+        // It happens whether you use the auto keyword or the type name
+        // ...
+    }
+}
+```
+
+This behavior is fine for scalars (pointers, arithmetic types, and so on), but for larger types, the copying may become expensive.
+
+## Solution
+
+To fix this issue, if the loop variable isn't mutated anywhere in the loop, make it a const reference:
+
+```cpp
+#include <vector>
+
+class MyComplexType { 
+    int native_array[1000];
+    // ...
+};
+
+void less_expensive_function(std::vector<MyComplexType>& complex_vector_ref)
+{
+    for (const auto& item: complex_vector_ref)
+    {
+        // item no longer gets a copy of each iterated element
+        // ...
+    }
+    for (const MyComplexType& item: complex_vector_ref)
+    {
+        // item no longer gets a copy of each iterated element
+        // ...
+    }
+}
+```
+
+The **const** keyword makes the loop variable immutable. Use of a non-const reference may cause potentially unwanted side effects in the original container elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable.
