Add definite initialization section

And:
- add placeholder for contracts
- add some is/as side-by-side examples
- add parameter passing styles

Author: hsutter

docs/cpp2/contracts.md

@@ -0,0 +1,16 @@
+
+# Contracts
+
+## Overview
+
+TODO
+
+
+## Contract groups
+
+TODO
+
+
+## Customizing the violation handler
+
+TODO

docs/cpp2/expressions.md

@@ -72,6 +72,17 @@ There are two kinds of `is`:
 - [`pure2-type-safety-1.cpp2`](https://github.com/hsutter/cppfront/tree/main/regression-tests/pure2-type-safety-1.cpp2)
 - [`pure2-type-safety-2-with-inspect-expression.cpp2`](https://github.com/hsutter/cppfront/tree/main/regression-tests/pure2-type-safety-2-with-inspect-expression.cpp2)
 
+Here are some `is` queries with their Cpp1 equivalents. In this table, uppercase names are type names, lowercase names are objects, `v` is a `std::variant` where one alternative is `T`, `o` is a `std::optional<T>`, and `a` is a `std::any`:
+
+| Some sample `is` queries | Cpp1 equivalent
+|---|---|
+| `X is Y && Y is X` | `std::is_same_v<X,Y>` |
+| `D is B` | `std::is_base_of<B,D>` |
+| `pb is *D` | `dynamic_cast<D*>(pb) != nullptr` |
+| `v is T`  | `std::holds_alternative<T>(v)` |
+| `a is T`  | `a.type() == typeid(T)` |
+| `o is T`  | `o.has_value()` |
+
 
 ## `as` — safe casts and conversions
 
@@ -97,6 +108,17 @@ test: (x) = {
 }
 ```
 
+Here are some `as` casts with their Cpp1 equivalents. In this table, uppercase names are type names, lowercase names are objects, `v` is a `std::variant` where one alternative is `T`, `o` is a `std::optional<T>`, and `a` is a `std::any`:
+
+| Some sample `as` casts | Cpp1 equivalent
+|---|---|
+| `x as Y` | `Y{x}` |
+| `pb as *D` | `dynamic_cast<D*>(pb)` |
+| `v as T`  | `std::get<T>(v)` |
+| `a as T`  | `std::any_cast<T>(a)` |
+| `o as T`  | `o.value()` |
+
+
 ## `inspect` — pattern matching
 
 An `inspect expr -> Type` expression allows pattern matching using `is`.

docs/cpp2/functions.md

@@ -5,7 +5,7 @@
 
 TODO
 
-## Calling functions: Nonmember function syntax, and UFCS syntax
+## Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
 
 A function call like `f(x)` is a normal non-member function call. It will call non-member functions only.
 
@@ -15,22 +15,38 @@ For example:
 
 ``` cpp title="Example: Function calls"
 f: ( v : std::vector<widget> ) = {
-
     //  This calls std::vector::size()
     std::cout << v.size();
 
     //  This calls std::ssize(v), because v
     //  doesn't have a .ssize member function
     std::cout << v.ssize();
 }
-```
 
-If the function has an output  that cannot be silently discarded, you can
+//  Generic function to print "hello, ___!" for any printable type
+hello: (name) = {
+    //  Using the C standard library is arguably nicer with UFCS
+    myfile := fopen("xyzzy.txt", "w");
+    myfile.fprintf( "Hello, (name)%!\n" );
+    myfile.fclose();
+}
+```
 
 
 ## Parameters
 
-TODO
+There are six ways to pass parameters that cover all use cases:
+
+| Parameter kind | "Pass me an `x` I can ______" | Accepts arguments that are | Special semantics |
+|---|---|---|---|
+| `in` (default) | read from | anything | always `const`<p>automatically passes by value if cheaply copyable |
+| `copy` | take a copy of | anything | acts like a normal local variable initialized with the argument |
+| `inout` | read from and write to | lvalues | |
+| `out` | write to (including construct) | lvalues, including uninitialized lvalues | must `=` assign/construct before other uses |
+| `move` | move from | rvalues | automatically moves from every definite last use |
+| `forward` | forward | anything | automatically forwards from every definite last use |
+
+
 
 > Note: All parameters and other objects in Cpp2 are `const` by default, except for local variables. For details, see [Design note: `const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
 

docs/cpp2/objects.md

@@ -26,6 +26,75 @@ count := -1;        // same, deducing the object's type by just omitting it
 ```
 
 
+## Guaranteed initialization
+
+Every object must be initialized using `=` before it is used.
+
+An object in any scope can be initialized at its declaration. For example:
+
+``` cpp title="Example: Initializing objects when they are declared" hl_lines="4 10"
+shape: type = {
+    //  An object at type scope (data member)
+    //  initialized with its type's default value
+    points: std::vector<point2d> = ();
+
+    draw: (this, where: canvas) -> bool
+    = {
+        //  An object at function scope (local variable)
+        //  initialized with color::red
+        pen := color::red;
+
+        // ...
+    }
+
+    //  ...
+}
+```
+
+Additionally, at function local scope an object `obj` can be initialized separately from its declaration. This can be useful when the object must be declared before a program-meaningful initial value is known (to avoid a dead write of a wrong 'dummy' value), and/or when the object may be initialized in more than one way depending on other logic (e.g., by using different constructors on different paths). The way to do this is:
+
+- Declare `obj` without an initializer, such as `obj: some_type;`. This allocates stack space for the object, but does not construct it.
+
+- `obj` must have a definite first use on every `if`/`else` branch path, and
+
+- that definite first use must be of the form `obj = value;` which is a constructor call, or else pass `obj` as an `out` argument to an `out` parameter (which is also effectively a constructor call, and performs the construction in the callee).
+
+For example:
+
+``` cpp title="Example: Initializing local objects after they are declared"
+f: () = {
+    buf: std::array<std::byte, 1024>;   // uninitialized
+    //  ... calculate some things ...
+    //  ...  no uses of buf here  ...
+    buf = some_calculated_value;        // constructs (not assigns) buf
+    //  ...
+    std::cout buf[0];                   // ok, a has been initialized
+}
+
+g: () = {
+    buf: std::array<std::byte, 1024>;   // uninitialized
+    if flip_coin_is_heads() {
+        if heads_default_is_available {
+            buf = copy_heads_default(); // constructs buf
+        }
+        else {
+            buf = (other, constructor); // constructs buf
+        }
+    }
+    else {
+        load_from_disk( out buf );      // constructs buf (*)
+    }
+    std::cout buf[0];                   // ok, a has been initialized
+}
+
+load_from_disk: (out buffer) = {
+    x = /* data read from disk */ ;     // when `buffer` is uninitialized,
+}                                       // constructs it; otherwise, assigns
+```
+
+In the above example, note the simple rule for branches: The local variable must be initialized on both the `if` and `else` branches, or neither branch.
+
+
 ## Heap objects
 
 Objects can also be allocated on the heap using `arena.new <T> (/*initializer, arguments)` where `arena` is any object that acts as a memory arena and provides a `.new` function template. Two memory arena objects are provided in namespace `cpp2`:
@@ -58,8 +127,3 @@ f: () -> std::shared_ptr<widget>
   // destroys the heap vector and deallocates its dynamic memory
 ```
 
-
-## Guaranteed initialization
-
-TODO
-

mkdocs.yml

@@ -59,6 +59,7 @@ nav:
     - 'Declaration syntax': cpp2/declarations.md
     - 'Objects, initialization, and memory': cpp2/objects.md
     - 'Functions': cpp2/functions.md
+    - 'Contracts': cpp2/contracts.md
     - 'Types': cpp2/types.md
     - 'Metafunctions & reflection API': cpp2/metafunctions.md
     - 'Namespaces': cpp2/namespaces.md