From 1ccff0324c74051da445852b31932aa2bbdb0c7a Mon Sep 17 00:00:00 2001
From: Araq <rumpf_a@web.de>
Date: Tue, 27 Aug 2019 12:13:06 +0200
Subject: manual: more precise rules about evaluation order

---
 doc/manual.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'doc')

diff --git a/doc/manual.rst b/doc/manual.rst
index a40e83809..f0945f78d 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -721,6 +721,44 @@ Rationale: Consistency with overloaded assignment or assignment-like operations,
 ``a = b`` can be read as ``performSomeCopy(a, b)``.
 
 
+However, the concept of "order of evaluation" is only applicable after the code
+was normalized: The normalization involves template expansions and argument
+reorderings that have been passed to named parameters:
+
+.. code-block:: nim
+    :test: "nim c $1"
+
+  var s = ""
+
+  proc p(): int =
+    s.add "p"
+    result = 5
+
+  proc q(): int =
+    s.add "q"
+    result = 3
+
+  # Evaluation order is 'b' before 'a' due to template
+  # expansion's semantics.
+  template swapArgs(a, b): untyped =
+    b + a
+
+  doAssert swapArgs(p() + q(), q() - p()) == 6
+  doAssert s == "qppq"
+
+  # Evaluation order is not influenced by named parameters:
+  proc construct(first, second: int) =
+    discard
+
+  # 'p' is evaluated before 'q'!
+  construct(second = q(), first = p())
+
+  doAssert s == "qppqpq"
+
+
+Rationale: This is far easier to implement than hypothetical alternatives.
+
+
 Constants and Constant Expressions
 ==================================
 
-- 
cgit 1.4.1-2-gfad0