Move function calls to expressions

Author: hsutter

docs/cpp2/expressions.md

@@ -1,6 +1,52 @@
 
 # Common expressions
 
+## Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
+
+A function call like `f(x)` is a normal function call that will call non-member functions only, as usual in C++.
+
+A function call like `x.f()` is a unified function call syntax (aka UFCS) call. It will call a member function if one is available, and otherwise will call `f(x)`. Having UFCS is important for generic code that may want to call a member or a non-member function, whichever is available. It's also important to enable fluid programming styles and natural IDE autocompletion support.
+
+An operator notation call like `#!cpp a + b` will call an overloaded operator function if one is available, as usual in C++.
+
+For example:
+
+``` cpp title="Function calls" hl_lines="3 7 11 16 19 20"
+//  Generic function to log something
+//  This calls operator<< using operator notation
+log: (x) = clog << x;
+
+f: ( v : std::vector<widget> ) = {
+    //  This calls log() with the result of std::vector::size()
+    log( v.size() );
+
+    //  This calls log() with the result of std::ssize(v), because
+    //  v doesn't have a .ssize member function
+    log( v.ssize() );
+}
+
+//  Generic function to print "hello, ___!" for any printable type
+hello: (name) = {
+    myfile := fopen("xyzzy.txt", "w");
+    //  Direct calls to C nonmember functions, using UFCS and safe
+    //  string interpolation (instead of type-unsafe format strings)
+    myfile.fprintf( "Hello, (name)$!\n" );
+    myfile.fclose();
+    //  The C and C++ standard libraries are not only fully available,
+    //  but safer (and arguably nicer) when used from Cpp2 syntax code
+}
+```
+
+To explicitly treat an object name passed as an argument as `move` or `out`, write that keyword before the variable name.
+
+- Explicit `move` is rarely needed. Every definite last use of a local variable will apply `move` by default. Writing `move` from an object before its definite last use means that later uses may see a moved-from state.
+
+- Explicit `out` is needed only when initializing a local variable separately from its declaration using a call to a function with an `out` parameter. For details, see [Guaranteed initialization](../cpp2/objects.md#Init).
+
+For example:
+
+
+
 ## `_` — the "don't care" wildcard, including explicit discard
 
 `_` is pronounced **"don't care"** and allowed as a wildcard in most contexts. For example:

docs/cpp2/functions.md

@@ -5,50 +5,6 @@
 
 TODO
 
-## Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
-
-A function call like `f(x)` is a normal function call that will call non-member functions only, as usual in C++.
-
-A function call like `x.f()` is a unified function call syntax (aka UFCS) call. It will call a member function if one is available, and otherwise will call `f(x)`. Having UFCS is important for generic code that may want to call a member or a non-member function, whichever is available. It's also important to enable fluid programming styles and natural IDE autocompletion support.
-
-An operator notation call like `#!cpp a + b` will call an overloaded operator function if one is available, as usual in C++.
-
-For example:
-
-``` cpp title="Function calls" hl_lines="3 7 11 16 19 20"
-//  Generic function to log something
-//  This calls operator<< using operator notation
-log: (x) = clog << x;
-
-f: ( v : std::vector<widget> ) = {
-    //  This calls log() with the result of std::vector::size()
-    log( v.size() );
-
-    //  This calls log() with the result of std::ssize(v), because
-    //  v doesn't have a .ssize member function
-    log( v.ssize() );
-}
-
-//  Generic function to print "hello, ___!" for any printable type
-hello: (name) = {
-    myfile := fopen("xyzzy.txt", "w");
-    //  Direct calls to C nonmember functions, using UFCS and safe
-    //  string interpolation (instead of type-unsafe format strings)
-    myfile.fprintf( "Hello, (name)$!\n" );
-    myfile.fclose();
-    //  The C and C++ standard libraries are not only fully available,
-    //  but safer (and arguably nicer) when used from Cpp2 syntax code
-}
-```
-
-To explicitly treat an object name passed as an argument as `move` or `out`, write that keyword before the variable name.
-
-- Explicit `move` is rarely needed. Every definite last use of a local variable will apply `move` by default. Writing `move` from an object before its definite last use means that later uses may see a moved-from state.
-
-- Explicit `out` is needed only when initializing a local variable separately from its declaration using a call to a function with an `out` parameter. For details, see [Guaranteed initialization](../cpp2/objects.md#Init).
-
-For example:
-
 
 ## Parameters