Add function local statics + 'singleton' metaclass

And 'encapsulated' and 'noncopyable' metaclasses

Author: hsutter

docs/cpp2/functions.md

@@ -391,7 +391,7 @@ outer: while i<M next i++ {      // loop named "outer"
 
 For example:
 
-``` cpp title="Throw, try, catch"
+``` cpp title="Throw, try, catch" hl_lines="1 3-5 9-11"
 //  This program will print "caught something else"
 main: () = {
     try {
@@ -407,6 +407,39 @@ main: () = {
 ```
 
 
+### <a id="static"></a> `#!cpp static` — Global variables inside functions
+
+**`#!cpp static`** can be specified as the first token of a local variable declaration at function scope, to denote that the variable is a global value initialized thread-safely the first time the line is executed (aka C++ "function local static," aka "magic static").
+
+For example (see also [`@singleton`](metafunctions.md#singleton)):
+
+``` cpp title="static variable (function local scope only)" hl_lines="15"
+//  For exposition only - normally, use @singleton for convenience
+my_singleton: type = {
+    value    : int = 42;
+
+    print    : (this) = std::cout << "(value)$\n";
+
+    //--------------------------------------------------------------------
+    //  writing '@singleton type' above would generate these two functions
+    //  but this example shows them for exposition of 'static'
+    //
+    private
+    operator=: (out this) = { }
+    
+    instance : () -> forward my_singleton = { 
+        static _instance: my_singleton = ();    // singleton variable
+        return _instance; 
+    }
+    //--------------------------------------------------------------------
+}
+
+main: () = {
+    my_singleton::instance().print();
+}
+```
+
+
 ## <a id="definite-last-use"></a> Move/forward from definite last use
 
 In a function body, a **definite last use** of a local name is a single use of that name in a statement that is not in a loop, where no control flow path after that statement mentions the name again.

docs/cpp2/metafunctions.md

@@ -365,13 +365,44 @@ main: () = {
 ```
 
 
+### For other common types
+
+#### `encapsulated`
+
+An `encapsulated` type is one that has no public data members.
+
+
+#### `noncopyable`
+
+A `noncopyable` type is one that has no user-defined copy or move functions (`operator=` with `this` and `that` parameters).
+
+
+#### <a id="singleton"></a> `singleton`
+
+A `singleton` type is one that has only one global object (instance) in the whole program. The single object is initialized lazily the first time it is accessed. A singleton type has no constructors other than a generated default constructor (note: therefore all data members must have default values), and provides a generated `instance()` function to create and give access to the global instance.
+
+For example:
+
+``` cpp title="A templated custom safe union type" hl_lines="1 7"
+my_singleton: @singleton type = {
+    value: int = 42;
+    print: (this) = std::cout << "(value)$\n";
+}
+
+main: () = {
+    my_singleton::instance().print();
+}
+```
+
+
 ### For computational and functional types
 
 #### `autodiff`
 
 An `autodiff` type is extended so that derivatives can be computed. The metafunction adds for each function and member function a differentiated version. **This is a proof of concept implementation. Expect it to break.**
 A simple hello diff example is:
-```
+
+``` cpp
 ad: @autodiff type = {
     func: (x: double) -> (r: double) = {
         r = x * x;

regression-tests/pure2-singleton-and-static.cpp2

@@ -0,0 +1,9 @@
+
+test: @singleton type = {
+    value: int = 42;
+    print: (this) = std::cout << "(value)$\n";
+}
+
+main: () = {
+    test::instance().print();
+}

regression-tests/test-results/clang-12-c++20/pure2-singleton-and-static.cpp.execution

@@ -0,0 +1 @@
+42

regression-tests/test-results/gcc-10-c++20/pure2-singleton-and-static.cpp.execution

@@ -0,0 +1 @@
+42

regression-tests/test-results/gcc-10-c++20/run-tests-gcc-10.sh

@@ -10,7 +10,7 @@ for f in *.cpp
 do
     let count=count+1
     printf "[%s] Starting gcc 10 %s\n" "$count" "$f"
-    g++-10 -I../../../include -std=c++20 -pthread -Wold-style-cast -Wunused-parameter -o test.exe $f > $f.output 2>&1
+    g++-10 -I../../../include -std=c++20 -pthread -Wold-style-cast -Wunused-parameter -Wno-unused-result -o test.exe $f > $f.output 2>&1
     rm -f $f
     if test -f "test.exe"; then
         let exe_count=exe_count+1

regression-tests/test-results/gcc-14-c++2b/pure2-singleton-and-static.cpp.execution

@@ -0,0 +1 @@
+42

regression-tests/test-results/gcc-14-c++2b/run-tests-gcc-14.sh

@@ -10,7 +10,7 @@ for f in *.cpp
 do
     let count=count+1
     printf "[%s] Starting gcc 14 %s\n" "$count" "$f"
-    g++ -I../../../include -std=c++2b -pthread -Wold-style-cast -Wunused-parameter -o test.exe $f > $f.output 2>&1
+    g++ -I../../../include -std=c++2b -pthread -Wold-style-cast -Wunused-parameter -Wno-unused-result -o test.exe $f > $f.output 2>&1
     rm -f $f
     if test -f "test.exe"; then
         let exe_count=exe_count+1

regression-tests/test-results/msvc-2022-c++latest/MSVC-version.output

@@ -1,3 +1,3 @@
-Microsoft (R) C/C++ Optimizing Compiler Version 19.43.34808 for x64
+Microsoft (R) C/C++ Optimizing Compiler Version 19.50.35721 for x64
 Copyright (C) Microsoft Corporation.  All rights reserved.
 

regression-tests/test-results/msvc-2022-c++latest/pure2-singleton-and-static.cpp.execution

@@ -0,0 +1 @@
+42