- improvement documentation for surface sampling.

- can now specify alternative sampling scheme for obtaining the
  face values instead of just using the "cell" value. For example,

      sampleScheme    cellPoint;

  This can be useful for cases when the surface is close to a boundary
  cell and there are large gradients in the sampled field.

- distanceSurface now handles non-closed surfaces more robustly.
  Unknown regions (not inside or outside) are marked internally and
  excluded from consideration. This allows use of 'signed' surfaces
  where not previously possible.

- The iterator for a HashSet dereferences directly to its key.

- Eg,

      for (const label patchi : patchSet)
      {
          ...
      }
  vs.
      forAllConstIter(labelHashSet, patchSet, iter)
      {
          const label patchi = iter.key();
          ...
      }

- IOstreamOption class to encapsulate format, compression, version.
  This is ordered to avoid internal padding in the structure, which
  reduces several bytes of memory overhead for stream objects
  and other things using this combination of data.

  Byte-sizes:
      old  IOstream:48  PstreamBuffers:88  Time:928
      new  IOstream:24  PstreamBuffers:72  Time:904

====

STYLE: remove support for deprecated uncompressed/compressed selectors

In older versions, the system/controlDict used these types of
specifications:

    writeCompression uncompressed;
    writeCompression compressed;

As of DEC-2009, these were deprecated in favour of using normal switch
names:

    writeCompression true;
    writeCompression false;
    writeCompression on;
    writeCompression off;

Now removed these deprecated names and treat like any other unknown
input and issue a warning. Eg,

   Unknown compression specifier 'compressed', assuming no compression

====

STYLE: provide Enum of stream format names (ascii, binary)

====

COMP: fixed incorrect IFstream construct in FIREMeshReader

- spurious bool argument (presumably meant as uncompressed) was being
  implicitly converted to a versionNumber. Now caught by making
  IOstreamOption::versionNumber constructor explicit.

- bad version specifier in changeDictionary

- in many cases can just use lookupOrDefault("key", bool) instead of
  lookupOrDefault<bool> or lookupOrDefault<Switch> since reading a
  bool from an Istream uses the Switch(Istream&) anyhow

STYLE: relocated Switch string names into file-local scope

- both autoPtr and tmp are defined with an implicit construct from
  nullptr (but with explicit construct from a pointer to null).
  Thus is it safe to use 'nullptr' when returning an empty autoPtr or tmp.

- when constructing dimensioned fields that are to be zero-initialized,
  it is preferrable to use a form such as

      dimensionedScalar(dims, Zero)
      dimensionedVector(dims, Zero)

  rather than

      dimensionedScalar("0", dims, 0)
      dimensionedVector("zero", dims, vector::zero)

  This reduces clutter and also avoids any suggestion that the name of
  the dimensioned quantity has any influence on the field's name.

  An even shorter version is possible. Eg,

      dimensionedScalar(dims)

  but reduces the clarity of meaning.

- NB: UniformDimensionedField is an exception to these style changes
  since it does use the name of the dimensioned type (instead of the
  regIOobject).

- this also provides a better separation of the intent
  (ie, inserting a single value, or inserting multiply values)

- eliminate iterators from PackedList since they were unused, had
  lower performance than direct access and added unneeded complexity.

- eliminate auto-vivify for the PackedList '[] operator.
  The set() method provides any required auto-vivification and
  removing this ability from the '[]' operator allows for a lower
  when accessing the values. Replaced the previous cascade of iterators
  with simpler reference class.

PackedBoolList:

- (temporarily) eliminate logic and addition operators since
  these contained partially unclear semantics.

- the new test() method tests the value of a single bit position and
  returns a bool without any ambiguity caused by the return type
  (like the get() method), nor the const/non-const access (like
  operator[] has). The name corresponds to what std::bitset uses.

- more consistent use of PackedBoolList test(), set(), unset() methods
  for fewer operation and clearer code. Eg,

      if (list.test(index)) ...    |  if (list[index]) ...
      if (!list.test(index)) ...   |  if (list[index] == 0u) ...
      list.set(index);             |  list[index] = 1u;
      list.unset(index);           |  list[index] = 0u;

- deleted the operator=(const labelUList&) and replaced with a setMany()
  method for more clarity about the intended operation and to avoid any
  potential inadvertent behaviour.

- The bitSet class replaces the old PackedBoolList class.
  The redesign provides better block-wise access and reduced method
  calls. This helps both in cases where the bitSet may be relatively
  sparse, and in cases where advantage of contiguous operations can be
  made. This makes it easier to work with a bitSet as top-level object.

  In addition to the previously available count() method to determine
  if a bitSet is being used, now have simpler queries:

    - all()  - true if all bits in the addressable range are empty
    - any()  - true if any bits are set at all.
    - none() - true if no bits are set.

  These are faster than count() and allow early termination.

  The new test() method tests the value of a single bit position and
  returns a bool without any ambiguity caused by the return type
  (like the get() method), nor the const/non-const access (like
  operator[] has). The name corresponds to what std::bitset uses.

  The new find_first(), find_last(), find_next() methods provide a faster
  means of searching for bits that are set.

  This can be especially useful when using a bitSet to control an
  conditional:

  OLD (with macro):

      forAll(selected, celli)
      {
          if (selected[celli])
          {
              sumVol += mesh_.cellVolumes()[celli];
          }
      }

  NEW (with const_iterator):

      for (const label celli : selected)
      {
          sumVol += mesh_.cellVolumes()[celli];
      }

      or manually

      for
      (
          label celli = selected.find_first();
          celli != -1;
          celli = selected.find_next()
      )
      {
          sumVol += mesh_.cellVolumes()[celli];
      }

- When marking up contiguous parts of a bitset, an interval can be
  represented more efficiently as a labelRange of start/size.
  For example,

  OLD:

      if (isA<processorPolyPatch>(pp))
      {
          forAll(pp, i)
          {
              ignoreFaces.set(i);
          }
      }

  NEW:

      if (isA<processorPolyPatch>(pp))
      {
          ignoreFaces.set(pp.range());
      }

This class is largely a pre-C++11 holdover. It is now possible to
simply use move construct/assignment directly.

In a few rare cases (eg, polyMesh::resetPrimitives) it has been
replaced by an autoPtr.

Improve alignment of its behaviour with std::shared_ptr

  - element_type typedef
  - swap, reset methods

* additional reference access methods:

cref()
    returns a const reference, synonymous with operator().
    This provides a more verbose alternative to using the '()' operator
    when that is desired.

        Mnemonic: a const form of 'ref()'

constCast()
    returns a non-const reference, regardless if the underlying object
    itself is a managed pointer or a const object.
    This is similar to ref(), but more permissive.

        Mnemonic: const_cast<>

    Using the constCast() method greatly reduces the amount of typing
    and reading. And since the data type is already defined via the tmp
    template parameter, the type deduction is automatically known.

    Previously,

        const tmp<volScalarField>& tfld;

        const_cast<volScalarField&>(tfld()).rename("name");
        volScalarField& fld = const_cast<volScalarField&>(tfld());

    Now,

        tfld.constCast().rename("name");
        auto& fld = tfld.constCast();

--

BUG: attempts to move tmp value that may still be shared.

- old code simply checked isTmp() to decide if the contents could be
  transfered. However, this means that the content of a shared tmp
  would be removed, leaving other instances without content.

* movable() method checks that for a non-null temporary that is
  unique (not shared).

Improve alignment of its behaviour with std::unique_ptr

  - element_type typedef
  - release() method - identical to ptr() method
  - get() method to get the pointer without checking and without releasing it.
  - operator*() for dereferencing

Method name changes

  - renamed rawPtr() to get()
  - renamed rawRef() to ref(), removed unused const version.

Removed methods/operators

  - assignment from a raw pointer was deleted (was rarely used).
    Can be convenient, but uncontrolled and potentially unsafe.
    Do allow assignment from a literal nullptr though, since this
    can never leak (and also corresponds to the unique_ptr API).

Additional methods

  - clone() method: forwards to the clone() method of the underlying
    data object with argument forwarding.

  - reset(autoPtr&&) as an alternative to operator=(autoPtr&&)

STYLE: avoid implicit conversion from autoPtr to object type in many places

- existing implementation has the following:

     operator const T&() const { return operator*(); }

  which means that the following code works:

       autoPtr<mapPolyMesh> map = ...;
       updateMesh(*map);    // OK: explicit dereferencing
       updateMesh(map());   // OK: explicit dereferencing
       updateMesh(map);     // OK: implicit dereferencing

  for clarity it may preferable to avoid the implicit dereferencing

- prefer operator* to operator() when deferenced a return value
  so it is clearer that a pointer is involve and not a function call
  etc    Eg,   return *meshPtr_;  vs.  return meshPtr_();

- relocated ListAppendEqOp and ListUniqueEqOp to ListOps::appendEqOp
  and ListOps::UniqueEqOp, respectively for better code isolation and
  documentation of purpose.

- relocated setValues to ListOps::setValue() with many more
  alternative selectors possible

- relocated createWithValues to ListOps::createWithValue
  for better code isolation. The default initialization value is itself
  now a default parameter, which allow for less typing.

  Negative indices in the locations to set are now silently ignored,
  which makes it possible to use an oldToNew mapping that includes
  negative indices.

- additional ListOps::createWithValue taking a single position to set,
  available both in copy assign and move assign versions.
  Since a negative index is ignored, it is possible to combine with
  the output of List::find() etc.

STYLE: changes for PackedList

- code simplication in the PackedList iterators, including dropping
  the unused operator() on iterators, which is not available in plain
  list versions either.

- improved sizing for PackedBoolList creation from a labelUList.

ENH: additional List constructors, for handling single element list.

- can assist in reducing constructor ambiguity, but can also helps
  memory optimization when creating a single element list.
  For example,

    labelListList labels(one(), identity(mesh.nFaces()));

- this permits direct storage of a list with additional matcher
  capabilities

- provide wordRes::matcher class for similar behaviour as previously

- reduces some ambiguity and clarifies the expected output and
  behaviour.

STYLE: reduce some automatic conversions of char to string

- now warn about the following:
  * the bounding box does not overlap wih the global mesh
  * plane does not intersect the (valid) bounding box
  * plane does not intersect the global mesh

- add bounding to the "plane" variant of a sampled plane.

- these were previously taken from region-local directories
  (eg, constant/region/triSurface), but this becomes difficult to
  manage when there are many files and regions.

- occurred when variable name exceeded the 15-char alignment format
  and the name run into the previous field.

- eliminates previous code duplication and improves maintainability

Mark Olesen authored Nov 16, 2017 and Mark OLESEN committed Nov 16, 2017

- now also fixed collated output format

There are a few issues:
- error would only throw exceptions if not parallel
- if we change this we also need to make sure the functionObjectList
  construction is synchronised
- bounding box overlap was not returning the correct status so the code
  to avoid the issue of 'badly formed bounding box' was not triggered.

     shortest path between two sets of points. See shortestPathSet.H.
     Fixes #572.