upgrade/v2012-Developer-Upgrade-Guide.md

@@ -4,24 +4,174 @@
 [![upgrade](/icons/chevrons-up.svg "upgrade guide")][upgrade-guide]
 [![code](/icons/code.svg "coding patterns")][code-patterns]
 
-***Preview information, subject to change at any time !!!***
-
 [[_TOC_]]
 
 ## Deprecation and Removal
 
 ### Deprecated Methods
 
+Compile-type deprecate the empty() method for autoPtr/tmp. This was
+never used by tmp, and only used in a few places by autoPtr.
+Less clutter and clearer to use plain tests with the bool operator.
+Eg,
+```
+if (!ptr) ...  vs  if (ptr.empty())  ...
+if (ptr)  ...  vs  if (!ptr.empty()) ...
+```
+
+
+Deprecate labelRange::valid() in favour of using labelRange::empty()
+or the bool operator. For example,
+```
+if (range) ...
+vs
+if (range.valid()) ...   // older
+```
+
+
 ### Removed Methods
 
+The autoPtr copy assigment is now marked as `= delete`. This was
+previously marked as transitional/deprecated (2018-02), but is now
+deleted since it can cause unexpected stealing of the pointer. Use the
+move assignment operator if that was indeed your intention.
+
+
 ### Removed Items
 
-## Changes in definition
+- removed labelRange::null, scalarRange::null static variables,
+  which turned out to be not particularly useful since we can simply
+  use constexpr contructor forms in most places.
+
+- removed labelRange::identity(label) static method,
+  which is replaced by the single-parameter constructor.
+
 
 ## Changes in behaviour
 
-## Namespace changes
+Improve flexiblity for flat output of items by changing to templated
+implementation instead of relying on the container's writeList()
+method. This inlines the generation while also adding the flexibility
+to define different delimiters (at compile time) without the
+performance penalty of passing run-time parameters.
+
+
+## Mesh shape matching
+
+Added static test methods for matching simple cell shapes (tet, pyr,
+hex) which can be identified from their number of faces and vertices.
+
+For these common shapes the static `test()` method is much cheaper to
+call on individual basis than the virtual `isA()` method since it
+avoids the unnecessary overhead of constructing an object.
+
+
+## Memory containers
+
+Introduced `refPtr` to the collection of memory containers. This looks
+largely like `tmp` in that it can hold a reference or a pointer, but
+unlike tmp it does not use ref-counting or have any special field
+functions associated with it. Both `refPtr` and `tmp` can now have
+three different types of content:
+
+- PTR : Managing a pointer (not ref-counted)
+- CREF : Using (const) reference to an object
+- REF : Using (non-const) reference to an object
+
+Access:
+- Assignment to pointer is normally done with the `reset()` method,
+  similar to autoPtr and std::unique_ptr.
+- Assignment to a const reference and constant dereferencing use the
+  `cref()` method.
+- Assignment to a non-const reference and non-const dereferencing use
+  the `ref()` method.
+Construction:
+- Construct from pointer
+- Construct from const reference
+- No construct from non-const reference, to avoid ambiguities.
+
+This allows us to tag a tmp as allowing non-const access to
+the reference and skip additional const_cast in following code.
+For example,
+```
+tmp<volScalarField> tfld(nullptr);
+auto* ptr = getObjectPtr<volScalarField>("field");
+if (ptr)
+{
+    tfld.ref(*ptr);
+}
+else
+{
+    tfld.reset(volScalarField::New(...));
+}
+auto& fld = tfld.ref();
+```
+
+In some places refPtr and tmp can be used instead of a
+std::reference_wrapper for handling external references.
+
+Unlike std::reference_wrapper, it can be default constructed
+(holding nothing), whereas reference_wrapper may need a dummy
+reference.
+However, the lifetime extension of references _may_ be better served
+with reference_wrapper.
+
+
+## Ease of programming
+
+For easier programming of parallel logic, introduced
+`Pstream::allProcs()` and `Pstream::subProcs()` methods that return
+ranges of `int` values that can be iterated across.
+For example,
+```
+for (const int proci : Pstream::allProcs()) { ... }
+
+// previously
+for (int proci = 0; proci < Pstream::nProcs(); ++proci) { ... }
+```
+and
+```
+for (const int proci : Pstream::subProcs()) { ... }
+
+
+// previously
+for (int slave = Pstream::firstSlave(); proci <= Pstream::lastSlave(); ++proci) { ... }
+```
+
+For case where parallel logic needs to be temporarily suspended,
+the new `UPstream::parRun(bool)` can be used. For example,
+```
+const bool oldParRun = Pstream::parRun(false);
+
+...
+// restore
+Pstream::parRun(oldParRun);
+```
+
+
+
+## Compatibility
+
+Add some scalar constants for .org compatibility.
+Although it can very much be a moving target, it can prove partly
+useful to have some compatibility constants/methods.
+
+- The wholesale change of 'GREAT' -> 'great' etc (JAN-2018), makes
+  user coding for multiple versions problematic. When
+  COMPAT_OPENFOAM_ORG is defined, now define constants (aliases) named
+  as per the openfoam.org version. Values, however, remain identical.
+
+- For type-safe dictionary value retrieval, we have the templated
+  `get<>` methods added around NOV-2018 and deprecated the lookupType
+  method. The .org version followed suit in NOV-2019, but opted for
+  renaming the templated lookupType method as a templated 'lookup'
+  method. Using this is discouraged, but allowed when
+  COMPAT_OPENFOAM_ORG is defined.
+
+
+----
 
 [code-patterns]: /coding/patterns/patterns
+[upgrade-guide]: /upgrade/upgrade
 
 [v2012-notes]: https://www.openfoam.com/releases/openfoam-v2012/