GitLab

- remove/fully deprecated newElmt in next release

- not yet triggered by any code, but avoid anyhow

- ITstream append() would previously have used the append from the
  underlying tokenList, which leaves the tokenIndex untouched and
  renders the freshly appended tokens effectively invisible if
  interspersed with primitiveEntry::read() that itself uses tokenIndex
  when building the list.

  The new append() method makes this hidden ITstream bi-directionality
  easier to manage. For efficiency, we only append lists
  (not individual tokens) and support a 'lazy' resizing that allows
  the final resizing to occur later when all tokens have been appended.

- The new ITstream seek() method provides a conveniently means to move
  to the end of the list or reposition to the middle.
  Using rewind() and using seek(0) are identical.

ENH: added OTstream to output directly to a list of tokens

---

BUG: List::newElem resized incorrectly

- had a simple doubling of the List size without checking that this
  would indeed be sufficient for the requested index.

  Bug was not triggered since primitiveEntry was the only class using
  this call, and it added the tokens sequentially.

- this can help if using std algorithms that return a const reference
  such as std::min() does.

For example,

   $ someSolver -info-switch writeOptionalEntries

- note that values changed via the command-line are changed after the
  etc/controlDict entries, but *before* any case-local
  system/controlDict entries.

  However, in many testing cases the command-line options eliminate
  the need for such local file modifications.

ENH: cleanup handling of local debug switches in Time

- add as methods directly on simpleObjectRegistry to avoid code
  duplication

STYLE: adjust internal naming of ITstream parameters

- cannot change stream compression after construction.

- Now accept '/' when reading variables without requiring
  a surrounding '{}'

- fix some degenerate parsing cases when the first character is
  already bad.

  Eg, $"abc" would have previously parsed as a <$"> variable, even
  although a double quote is not a valid variable character.

  Now emits a warning and parses as a '$' token and a string token.

- compacter messages in some cases

STYLE: simplify output handling of line numbers

- relax casting rules
  * down-cast of labelToken to boolToken
  * up-cast of wordToken to stringToken.
    Can use isStringType() test for word or string types

- simplify constructors, move construct etc.

- expose reset() method as public, which resets to UNDEFINED and
  clears allocated storage etc.

DEFEATURE: remove assign from word or string pointer.

- This was deprecated 2017-11 and now removed.
  For this type of content transfer, move assignment should be used
  instead of stealing pointers.

- creates a std::string with space-delimited tokens, which can be sent
  to another application or even re-parsed into tokens

- allows some internal handling for reading dissimilar storage types.
  Eg, scalars written as float (WM_SP), but read as double (WM_DP)

- reading binary parcel coordinates with dissimilar storage types is
  still pending

- change contiguous from a series of global functions to separate
  templated traits classes:

    - is_contiguous
    - is_contiguous_label
    - is_contiguous_scalar

  The static constexpr 'value' and a constexpr conversion operator
  allow use in template expressions.  The change also makes it much
  easier to define general traits and to inherit from them.

  The is_contiguous_label and is_contiguous_scalar are special traits
  for handling data of homogeneous components of the respective types.

- these use the additional byte-size checks in IOstream to handle
  native vs non-native sizes

- this is principally for cases where reduced indentation is desired,
  such as when streaming to a memory location. If the indentation size
  is zero or one, only a single space will be used to separate the
  key/value.

  This change does not affect the stream allocation size, since the
  extra data falls within the padding.

ENH: relocate label/scalar sizes from Istream to IOstream.

- could allow future use for output streams as well?

  Due to padding, reorganization has no effect on allocated size
  of output streams.

STYLE: add read/write name qualifier to beginRaw, endRaw

- removes ambiguity for bi-directional streams

STYLE: fix inconsistent 'const' qualifier on std::streamsize

- base Ostream was without const, some derived streams with const

- allows full recovery of allocated space, not just addressable range.

  This can be particularly useful for code patterns that repeatedly
  reuse the same buffer space. For example,

      DynamicList<char> buf(1024);

      // some loop
      {
          OListStream os(std::move(buf));
          os << ...

          os.swap(buf);
      }

   Can read back from this buffer as a second operation:

      {
          UIListStream is(buf);
          is >> ...
      }

- symmetric with writeRaw() etc for the output stream. These are
  methods that are not required by normal users, but which provide
  a finer granularity for reading.

- additional information about the current stream position when
  endList fails. This may help when tracing errors.

STYLE: change return type of beginRaw()/endRaw() to bool

- was of type Ostream& for output, but return value was unused.
  Having bool may be better for encapsulating logic

STYLE: remove unused Istream::readEndBegin() function

- previously would have different SHA1 depending on whether the
  string was a C-string, a C++-string or if the SHA1 was calculated
  directly or via the OSHA1stream.

    - SHA1("string")
    - OSHA1stream << "string";
    - OSHA1stream << string("string");

  By avoiding string quoting on output, they now all deliver the same
  result. This also means that the following will no longer change the SHA1
  content, since it does not add anything:

    osha<< string() << string() << string() << string();

  This would have previously add a pair of double quotes each time!

- this improves overall consistency and is independent of higher level
  tagging as ASCII or BINARY for IFstream, OFstream etc.

- simplifies their use when reordering lists etc.
  (word, fileName, keyType, wordRe)

- "unfriend" IO operators for string types. They require no internal access

- add compile/uncompile methods to keyType for symmetry with wordRe

- when outputting keyType/wordRe, be more explicit about them using
  writeQuoted()

- when combining lists in processor order this simplifies code and
  reduces memory overhead.

  Write this:
    ----
    labelList collected;

    const globalIndex sizing(input.size());
    sizing.gather(input, collected);
    ----

  OR

    ----
    labelList collected;
    globalIndex::gatherOp(input, collected);
    ----

  Instead of this:

    ----
    labelList collected;

    List<labelList> scratch(Pstream::nProcs());
    scratch[Pstream::myProcNo()] = input;
    Pstream::gatherList(scratch);

    if (Pstream::master())
    {
        collected = ListListOps::combine<labelList>
        (
            scratch,
            accessOp<labelList>()
        );
    }
    scratch.clear();
    ----

- missing verbatim/endverbatim markers, missing "Foam::" prefix, typos

- makes the intent clearer and avoids the need for additional
  constructor casting. Eg,

      labelList(10, Zero)    vs.  labelList(10, 0)
      scalarField(10, Zero)  vs.  scalarField(10, scalar(0))
      vectorField(10, Zero)  vs.  vectorField(10, vector::zero)

- useful when generating formatted output such as tables.

- Start brief descriptions with 'Deprecated(YYYY-MM)' so that it is
  readily visible in the short method description. Consistent date
  format (YYYY-MM), placed immediately after the \deprecated tag.

- a failed attempt to read a value (eg, word, label, scalar) from a
  stream now always provokes a FatalIOError.
  This helps avoid some difficult to trace input errors.

- more dictionary-like methods, enforce keyType::LITERAL for all
  lookups to avoid any spurious keyword matching.

- new readEntry, readIfPresent methods

- The get() method replaces the now deprecate lookup() method.

- Deprecate lookupOrFailsafe()
  Failsafe behaviour is now an optional parameter for lookupOrDefault,
  which makes it easier to tailor behaviour at runtime.

- output of the names is now always flatted without line-breaks.
  Thus,

     os << flatOutput(someEnumNames.names()) << nl;
     os << someEnumNames << nl;

  both generate the same output.

- Constructor now uses C-string (const char*) directly instead of
  Foam::word in its initializer_list.

- Remove special enum + initializer_list constructor form since
  it can create unbounded lookup indices.

- Removd old hasEnum, hasName forms that were provided during initial
  transition from NamedEnum.

- Added static_assert on Enum contents to restrict to enum or
  integral values.  Should not likely be using this class to enumerate
  other things since it internally uses an 'int' for its values.

  Changed volumeType accordingly to enumerate on its type (enum),
  not the class itself.