Merge pull request #3192 from ntrel/opApply

[spec/statement.dd] Improve opApply docs

Signed-off-by: Dennis <[email protected]>
Merged-on-behalf-of: Dennis <[email protected]>

Author: dlang-bot

spec/statement.dd

@@ -675,7 +675,7 @@ $(H3 $(LNAME2 foreach_over_struct_and_classes, Foreach over Structs and Classes
         special $(LEGACY_LNAME2 opApply, op-apply, $(D opApply)) member function, and the
         `foreach_reverse` behavior is defined by the special
         $(LEGACY_LNAME2 opApplyReverse, op-apply-reverse, $(D opApplyReverse)) member function.
-        These functions have the type:
+        These functions have the signatures:
     )
 
         --------------
@@ -684,21 +684,27 @@ $(H3 $(LNAME2 foreach_over_struct_and_classes, Foreach over Structs and Classes
         int opApplyReverse(scope int delegate(ref Type [, ...]) dg);
         --------------
 
-    $(P where $(I Type) matches the $(I Type) used in the $(I ForeachType)
-        declaration of $(I Identifier). Multiple $(I ForeachType)s
-        correspond with multiple $(I Type)s in the delegate type
-        passed to $(D opApply) or $(D opApplyReverse).
-        There can be multiple $(D opApply) and $(D opApplyReverse) functions,
+    $(P where $(I Type) determines the type of the first $(GLINK ForeachType)
+        declared. Multiple $(I ForeachType)s are supported.
+        Each one must match a parameter of the delegate *dg*,
+        otherwise the *ForeachStatement* will cause an error.)
+
+    $(P There can be multiple $(D opApply) and $(D opApplyReverse) functions -
         one is selected
-        by matching the type of $(I dg) to the $(I ForeachType)s
-        of the $(I ForeachStatement).
-        The body of the apply
-        function iterates over the elements it aggregates, passing them
-        each to the $(I dg) function. If the $(I dg) returns 0, then
-        apply goes on to the next element.
-        If the $(I dg) returns a nonzero value, apply must cease
-        iterating and return that value. Otherwise, after done iterating
-        across all the elements, apply will return 0.
+        by matching each parameter type of *dg* to the type of each $(I ForeachType)
+        declared in the $(I ForeachStatement).)
+
+    $(P The body of the apply
+        function iterates over the elements it aggregates, passing each one
+        in successive calls to the $(I dg) delegate. The delegate return value
+        determines whether to interrupt iteration:)
+
+    $(UL
+        $(LI If the result is nonzero, apply must cease
+        iterating and return that value.)
+        $(LI If the result is 0, then iteration should continue.
+        If there are no more elements to iterate,
+        apply must return 0.)
     )
 
     $(P For example, consider a class that is a container for two elements:)
@@ -711,25 +717,22 @@ $(H3 $(LNAME2 foreach_over_struct_and_classes, Foreach over Structs and Classes
 
             int opApply(scope int delegate(ref uint) dg)
             {
-                int result = 0;
-
                 foreach (e; array)
                 {
-                    result = dg(e);
+                    int result = dg(e);
                     if (result)
-                        break;
+                        return result;
                 }
-                return result;
+                return 0;
             }
         }
 
         void main()
         {
             import std.stdio;
-            Foo a = new Foo();
 
-            a.array[0] = 73;
-            a.array[1] = 82;
+            Foo a = new Foo();
+            a.array = [73, 82];
 
             foreach (uint u; a)
             {
@@ -745,34 +748,44 @@ $(CONSOLE
 73
 82
 )
-    $(P The `scope` storage class on the $(I dg) parameter means that the parameter's value does
-    not escape the scope of the $(I opApply) function (an example would be assigning $(I dg) to a
-    global). If it cannot be statically guaranteed that $(I dg) does not escape, a closure may
+    $(P The `scope` storage class on the $(I dg) parameter means that the delegate does
+    not escape the scope of the $(D opApply) function (an example would be assigning $(I dg) to a
+    global variable). If it cannot be statically guaranteed that $(I dg) does not escape, a closure may
     be allocated for it on the heap instead of the stack.
     )
 
     $(BEST_PRACTICE Annotate delegate parameters to `opApply` functions with `scope` when possible.)
 
-    $(P $(LEGACY_LNAME2 opApply, op-apply, $(I opApply)) can also be a templated function,
-        which will infer the types of parameters based on the $(I ForeachStatement).
-    )
+    $(P $(B Important:) If $(D opApply) catches any exceptions, ensure that those
+        exceptions did not originate from the delegate passed to $(D opApply). The user would expect
+        exceptions thrown from a `foreach` body to both terminate the loop, and propagate outside
+        the `foreach` body.
+     )
 
-    $(P For example:)
+$(H4 $(LNAME2 template-op-apply, Template `opApply`))
 
+    $(P $(D opApply) can also be a templated function,
+        which will infer the types of parameters based on the $(I ForeachStatement).
+        For example:)
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         --------------
         struct S
         {
             import std.traits : ParameterTypeTuple;  // introspection template
+            import std.stdio;
 
             int opApply(Dg)(scope Dg dg)
             if (ParameterTypeTuple!Dg.length == 2) // foreach with 2 parameters
             {
+                writeln(2);
                 return 0;
             }
 
             int opApply(Dg)(scope Dg dg)
-            if (ParameterTypeTuple!Dg.length == 3) // foreach with takes 3 parameters
+            if (ParameterTypeTuple!Dg.length == 3) // foreach with 3 parameters
             {
+                writeln(3);
                 return 0;
             }
         }
@@ -783,12 +796,7 @@ $(CONSOLE
             foreach (int a, int b, float c; S()) { }  // calls second opApply function
         }
         --------------
-
-    $(P It is important to make sure that, if $(D opApply) catches any exceptions, that those
-        exceptions did not originate from the delegate passed to $(I opApply). The user would expect
-        exceptions thrown from a `foreach` body to both terminate the loop, and propagate outside
-        the `foreach` body.
-     )
+        )
 
 $(H3 $(LEGACY_LNAME2 foreach_with_ranges, foreach-with-ranges, Foreach over Structs and Classes with Ranges))
 
@@ -946,7 +954,8 @@ $(H4 $(LNAME2 front-seq, Multiple Element Values))
 $(H3 $(LNAME2 foreach_over_delegates, Foreach over Delegates))
 
         $(P If $(I ForeachAggregate) is a delegate, the type signature of
-        the delegate is of the same as for $(D opApply). This enables
+        the delegate is of the same as for
+        $(RELATIVE_LINK2 foreach_over_struct_and_classes, opApply). This enables
         many different named looping strategies to coexist in the same
         class or struct.)