init checks and 'out' parameters (#14521)

* I don't care about observable stores
* enforce explicit initializations
* cleaner code for the stdlib
* stdlib: use explicit initializations
* make tests green
* algorithm.nim: set result explicitly
* remove out parameters and bring the PR into a mergable state
* updated the changelog

2 files changed, 24 insertions, 14 deletions

diff --git a/doc/manual.rst b/doc/manual.rst
index a7bca7616..da50e2c56 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -2458,12 +2458,13 @@ matches) is preferred:
   gen(ri) # "ref T"
 
 
-Overloading based on 'var T'
-----------------------------
+Overloading based on 'var T' / 'out T'
+--------------------------------------
 
-If the formal parameter ``f`` is of type ``var T`` in addition to the ordinary
-type checking, the argument is checked to be an `l-value`:idx:. ``var T``
-matches better than just ``T`` then.
+If the formal parameter ``f`` is of type ``var T`` (or ``out T``)
+in addition to the ordinary
+type checking, the argument is checked to be an `l-value`:idx:.
+``var T`` (or ``out T``) matches better than just ``T`` then.
 
 .. code-block:: nim
   proc sayHi(x: int): string =
@@ -2482,6 +2483,17 @@ matches better than just ``T`` then.
               # 13
 
 
+An l-value matches ``var T`` and ``out T`` equally well, hence
+the following is ambiguous:
+
+.. code-block:: nim
+
+  proc p(x: out string) = x = ""
+  proc p(x: var string) = x = ""
+  var v: string
+  p(v) # ambiguous
+
+
 Lazy type resolution for untyped
 --------------------------------
 
@@ -4230,9 +4242,7 @@ error message from ``e``, and for such situations it is enough to use
 Custom exceptions
 -----------------
 
-Is it possible to create custom exceptions. These make it easy to distinguish between exceptions raised by nim and those from your own code.
-
-A custom exception is a custom type:
+Is it possible to create custom exceptions. A custom exception is a custom type:
 
 .. code-block:: nim
   type
@@ -4782,7 +4792,7 @@ of "typedesc"-ness is stripped off:
 Generic inference restrictions
 ------------------------------
 
-The types ``var T`` and ``typedesc[T]`` cannot be inferred in a generic
+The types ``var T``, ``out T`` and ``typedesc[T]`` cannot be inferred in a generic
 instantiation. The following is not allowed:
 
 .. code-block:: nim
@@ -5930,7 +5940,7 @@ noSideEffect pragma
 The ``noSideEffect`` pragma is used to mark a proc/iterator to have no side
 effects. This means that the proc/iterator only changes locations that are
 reachable from its parameters and the return value only depends on the
-arguments. If none of its parameters have the type ``var T``
+arguments. If none of its parameters have the type ``var T`` or ``out T``
 or ``ref T`` or ``ptr T`` this means no locations are modified. It is a static
 error to mark a proc/iterator to have no side effect if the compiler cannot
 verify this.
@@ -6593,7 +6603,7 @@ during semantic analysis:
 Emit pragma
 -----------
 The ``emit`` pragma can be used to directly affect the output of the
-compiler's code generator. So it makes your code unportable to other code
+compiler's code generator. The code is then unportable to other code
 generators/backends. Its usage is highly discouraged! However, it can be
 extremely useful for interfacing with `C++`:idx: or `Objective C`:idx: code.
 
diff --git a/doc/manual_experimental.rst b/doc/manual_experimental.rst
index 1398d1a9b..d8efddf94 100644
--- a/doc/manual_experimental.rst
+++ b/doc/manual_experimental.rst
@@ -482,7 +482,7 @@ nil`` annotation to exclude ``nil`` as a valid value:
 
 .. code-block:: nim
   {.experimental: "notnil"}
-  
+
   type
     PObject = ref TObj not nil
     TProc = (proc (x, y: int)) not nil
@@ -1828,8 +1828,8 @@ Aliasing restrictions in parameter passing
 implementation and need to be fleshed out further.
 
 "Aliasing" here means that the underlying storage locations overlap in memory
-at runtime. An "output parameter" is a parameter of type ``var T``, an input
-parameter is any parameter that is not of type ``var``.
+at runtime. An "output parameter" is a parameter of type ``var T``,
+an input parameter is any parameter that is not of type ``var``.
 
 1. Two output parameters should never be aliased.
 2. An input and an output parameter should not be aliased.