for_each_n doc completed (#3933)

docs/standard-library/algorithm-functions.md

@@ -2191,7 +2191,7 @@ int main()
 
     // The function object is templatized and so can be
     // used again on the elements with a different Factor
-    for_each (v1.begin( ), v1.end( ), MultValue<int> (5 ) );
+    for_each ( v1.begin( ), v1.end( ), MultValue<int> ( 5 ) );
 
     cout << "Multiplying the elements of the vector v1mod\n "
             << "by the factor 5 gives:\n v1mod2 = ( " ;
@@ -2223,19 +2223,123 @@ Average ( v1mod2 ) = 10.
 
 ## <a name="for_each_n"></a> `for_each_n`
 
+Applies a specified function object to a specified number of elements in a range beginning with a particular element.
+
 ```cpp
 template<class InputIterator, class Size, class Function>
 InputIterator for_each_n(
     InputIterator first,
-    Size n,
-    Function f);
+    Size count,
+    Function func);
 
 template<class ExecutionPolicy, class ForwardIterator, class Size, class Function>
 ForwardIterator for_each_n(
     ExecutionPolicy&& exec,
     ForwardIterator first,
-    Size n,
-    Function f);
+    Size count,
+    Function func);
+```
+
+### Parameters
+
+*`exec`*\
+The execution policy to use.
+
+*`first`*\
+An input iterator addressing the position of the first element in the range to be operated on.
+
+*`count`*\
+A signed or unsigned integral type specifying the number of elements to be operated on.
+
+*`func`*\
+User-defined function object that is applied to each element in the range [`first`, `first` + `count`).
+
+### Return value
+
+An iterator to the element that follows the last element processed if *`count`* > zero,
+otherwise the first element.
+
+### Remarks
+
+The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation.
+
+The complexity is linear with at most *`count`* operations.
+
+### Example
+
+```cpp
+// alg_for_each_n.cpp
+// compile with: /EHsc
+#include <vector>
+#include <algorithm>
+#include <iostream>
+
+// The function object multiplies an element by a Factor
+template <class Type>
+class MultValue
+{
+private:
+    Type Factor;   // The value to multiply by
+public:
+    // Constructor initializes the value to multiply by
+    MultValue ( const Type& value ) : Factor ( value ) {
+    }
+
+    // The function call for the element to be multiplied
+    void operator( ) ( Type& elem ) const
+    {
+        elem *= Factor;
+    }
+};
+
+int main()
+{
+    using namespace std;
+    vector<int> v;
+    vector<int>::iterator Iter;
+
+    // Constructing vector v
+    int i;
+    for ( i = -4 ; i <= 2 ; i++ )
+    {
+        v.push_back( i );
+    }
+
+    cout << "Original vector v = ( " ;
+    for ( Iter = v.begin( ) ; Iter != v.end( ) ; Iter++ )
+        cout << *Iter << " ";
+    cout << ")." << endl;
+
+    // Using for_each_n to multiply the first 3 elements by a Factor,
+    // saving position
+    auto pos = for_each_n ( v.begin( ), 3, MultValue<int> ( -2 ) );
+
+    cout << "Multiplying the first 3 elements of the vector v\n "
+            << "by the factor -2 gives:\n vmod1 = ( " ;
+    for ( Iter = v.begin( ) ; Iter != v.end( ) ; Iter++ )
+        cout << *Iter << " ";
+    cout << ")." << endl;
+
+    // Using for_each_n to multiply the next 3 elements by a Factor,
+    // starting at the position saved by the previous for_each_n
+    for_each_n ( pos, 4, MultValue<int> ( -3 ) );
+
+    cout << "Multiplying the next 4 elements of the vector v\n "
+            << "by the factor -3 gives:\n vmod2 = ( " ;
+    for ( Iter = v.begin( ) ; Iter != v.end( ) ; Iter++ )
+        cout << *Iter << " ";
+    cout << ")." << endl;
+}
+```
+
+```Output
+Original vector v1 = ( -4 -3 -2 -1 0 1 2 ).
+Multiplying the first 3 elements of the vector v1
+ by the factor -2 gives:
+ v1mod1 = ( 8 6 4 -1 0 1 2 ).
+Multiplying the next 4 elements of the vector v1
+ by the factor -3 gives:
+ v1mod2 = ( 8 6 4 3 0 -3 -6 ).
 ```
 
 ## <a name="generate"></a> `generate`