- returns UPtrList view (read-only or read/write) of the objects
- shorter names for IOobject checks: hasHeaderClass(), isHeaderClass()
- remove unused IOobject::isHeaderClassName(const word&) method.
The typed versions are preferable/recommended, but can still check
directly if needed:
(io.headerClassName() == "foo")
- the sorted() method fills a UPtrList with sorted entries. In some
places this can provide a more convenient means of traversing a
HashTable in consistent order, without the extra step of creating
a sortedToc(). The sorted() method with a UPtrList will also have
a lower overhead than creating any sortedToc() or toc() since it is
list of pointers and not full copies of the keys.
Instead of this:
HashTable<someType> table = ...;
for (const word& key : table.sortedToc())
{
Info<< key << " => " << table[key] << nl;
}
can write this:
for (const auto& iter : table.sorted())
{
Info<< iter.key() << " => " << iter.val() << nl;
}
STYLE:
- declare hash entry key 'const' since it is immutable
- additional dummy template parameter to assist with supporting
derived classes. Currently just used for string types, but can be
extended.
- provide hash specialization for various integer types.
Removes the need for any forwarding.
- change default hasher for HashSet/HashTable from 'string::hash'
to `Hash<Key>`. This avoids questionable hashing calls and/or
avoids compiler resolution problems.
For example,
HashSet<label>::hasher and labelHashSet::hasher now both properly
map to Hash<label> whereas previously HashSet<label> would have
persistently mapped to string::hash, which was incorrect.
- standardize internal hashing functors.
Functor name is 'hasher', as per STL set/map and the OpenFOAM
HashSet/HashTable definitions.
Older code had a local templated name, which added unnecessary
clutter and the template parameter was always defaulted.
For example,
Old: `FixedList<label, 3>::Hash<>()`
New: `FixedList<label, 3>::hasher()`
Unchanged: `labelHashSet::hasher()`
Existing `Hash<>` functor namings are still supported,
but deprecated.
- define hasher and Hash specialization for bitSet and PackedList
- add symmetric hasher for 'face'.
Starts with lowest vertex value and walks in the direction
of the next lowest value. This ensures that the hash code is
independent of face orientation and face rotation.
NB:
- some of keys for multiphase handling (eg, phasePairKey)
still use yet another function naming: `hash` and `symmHash`.
This will be targeted for alignment in the future.
- handle binary/contiguous first as being the most obvious, followed
by increasing complexity of ascii.
Structure reading and writing routines similarly by introducing a
readList method to compliment the writeList method.
- forwarding like the emplace() method, but overwriting existing
entries as required
- propagate similar changes to HashPtrTable
For example, with HashPtrTable<labelList> table(...) :
With 'insert' semantics
table.emplace("list1", 1000);
vs
if (!table.found("list1"))
{
table.set("list1", new labelList(1000));
}
or
table.insert("list1", autoPtr<labelList>::New(1000));
Note that the last example invokes an unnecessary allocation/deletion
if the insertion is unsuccessful.
With 'set' semantics:
table.emplace_set("list1", 15);
vs
table.set("list1", new labelList(15));
- previously allowed mapped value modification with a const iterator.
However, this can lead to incorrect access patterns.
Now tie the constness of the mapped value to that of the iterator.
- Remove deprecated iterator object() method.
Was only used internally and was superseded by the val() method
in an earlier version.
ENH: change isPointer to isPointerLike
- can distinguish between real pointers and wrapped pointers
- this largely reverts 3f0f218d88 and 4ee65d12c4.
Consistent addressing with support for wrapped pointer types (eg,
autoPtr, std::unique_ptr) has proven to be less robust than desired.
Thus rescind HashTable iterator '->' dereferencing (from APR-2019).
- use HashTable emplace instead of insert to avoid unneeded argument
(for HashSet).
- use emplace when generating zero-initialized values for
HashTable::operator()
- drop unused parameter from Detail::HashTableSingle,
adjust templates parameter names
- forward HashTable::operator[] to the semantically identical
HashTable::at() to avoid code duplication
- unfriend HashSet, HashTable IO operators
- global min(), max(), minMax() functions taking a labelHashSet and an
optional limit. For example,
labelHashSet set = ...;
Info<< "min is " << min(set) << nl;
Info<< "max (non-negative) " << max(set, 0) << nl;
- make HashTable iterator '->' dereferencing more consistent by also
supporting non-pointer types as well.
- read HashTable values in-situ to avoid copying
- support move insert/set and emplace insertion.
These adjustments can be used for improved memory efficiency, and
allow hash tables of non-copyable objects (eg, std::unique_ptr).
- extend special HashTable output treatment to include pointer-like
objects such as autoPtr and unique_ptr.
ENH: HashTable::at() method with checking. Fatal if entry does not exist.
- introduced a ListPolicy details to make the transition between
a short list (space separated) and a long list (newline separated)
more configurable.
We suppress line breaks for commonly used types that often have
short content: (word, wordRes, keyType).
- relocate the pair_entry (HashTable) and unary_entry (HashSet) into
the Detail namespace and add output handling.
The output handling at this level removes the reliance on zero::null
output (HashSet) and allows direct support of pointers.
This means that the following now works
HashTable<T*> tbl;
os << tbl;
It also means that we don't need to overload operator<< for
HashPtrTable anymore.
- avoid delete/new when calling HashSet::set(). If the entry already
exists there is no reason to remove it and add another one with the
same content.
STYLE: HashTable iterators now have a val() method
- identical to the object() iterator method, but shorter to type.
- can be used as a more natural test on the iterator.
For example, with
HashTable<..> table;
auto iter = table.find(...);
Following are now all equivalent:
1. if (iter != table.end()) ...
2. if (iter.found()) ...
3. if (iter) ...
- improves backward compatibility and more naming consistency.
Retain setMany(iter1, iter2) to avoid ambiguity with the
PackedList::set(index, value) method.
- disallow insert() of raw pointers, since a failed insertion
(ie, entry already existed) results in an unmanaged pointer.
Either insert using an autoPtr, or set() with raw pointers or autoPtr.
- IOobjectList::add() now takes an autoPtr instead of an object reference
- IOobjectList::remove() now returns an autoPtr instead of a raw pointer
- without these will use the normal move construct + move assign.
This is similarly efficient, but avoids the inadvertently having the
incorrect Swap being used for derived classes.
STYLE: remove unused xfer methods for HashTable, HashSet
- unneeded since move construct and move assignment are possible
- this increases the flexibility of the interface
- Add stringOps 'natural' string sorting comparison.
Digits are sorted in their natural order, which means that
(file10.txt file05.txt file2.txt)
are sorted as
(file2.txt file05.txt file10.txt)
STYLE: consistent naming of template parameters for comparators
- Compare for normal binary predicates
- ListComparePredicate for list compare binary predicates
- improve functional compatibility with DynList (remove methods)
* eg, remove an element from any position in a DynamicList
* reduce the number of template parameters
* remove/subset regions of DynamicList
- propagate Swap template specializations for lists, hashtables
- move construct/assignment to various containers.
- add find/found methods for FixedList and UList for a more succinct
(and clearer?) usage than the equivalent global findIndex() function.
- simplify List_FOR_ALL loops
- This follows the same idea as cbegin/cend and is helpful when using
C++11 auto to ensure we have unambiguous const-safe access.
Previously:
====
typename someLongClass::const_iterator iter = someTable.find(key);
... later on:
*iter = value; // Oops, but caught by compiler.
We can save some typing with auto, but it is uncertain what we get:
====
auto iter = someTable.find(key);
// iterator or const_iterator?
// depends on someTable having const or non-const access.
... later on:
*iter = value; // Oops, but not caught by compiler.
Using cfind instead, auto will deduce const_iterator as the type:
====
auto iter = someTable.cfind(key); // definitely const_iterator
... later on:
*iter = value; // Oops, but caught by compiler.
- Generalized means over filtering table entries based on their keys,
values, or both. Either filter (retain), or optionally prune elements
that satisfy the specified predicate.
filterKeys and filterValues:
- Take a unary predicate with the signature
bool operator()(const Key& k);
- filterEntries:
Takes a binary predicate with the signature
bool operator()(const Key& k, const T& v);
==
The predicates can be normal class methods, or provide on-the-fly
using a C++ lambda. For example,
wordRes goodFields = ...;
allFieldNames.filterKeys
(
[&goodFields](const word& k){ return goodFields.match(k); }
);
Note that all classes that can match a string (eg, regExp, keyType,
wordRe, wordRes) or that are derived from a Foam::string (eg, fileName,
word) are provided with a corresponding
bool operator()(const std::string&)
that either performs a regular expression or a literal match.
This allows such objects to be used directly as a unary predicate
when filtering any string hash keys.
Note that HashSet and hashedWordList both have the proper
operator() methods that also allow them to be used as a unary
predicate.
- Similar predicate selection with the following:
* tocKeys, tocValues, tocEntries
* countKeys, countValues, countEntries
except that instead of pruning, there is a simple logic inversion.
- lookup(): with a default value (const access)
For example,
Map<label> something;
value = something.lookup(key, -1);
being equivalent to the following:
Map<label> something;
value = -1; // bad value
if (something.found(key))
{
value = something[key];
}
except that lookup also makes it convenient to handle const references.
Eg,
const labelList& ids = someHash.lookup(key, labelList());
- For consistency, provide a two parameter HashTable '()' operator.
The lookup() method is, however, normally preferable when
const-only access is to be ensured.
- retain(): the counterpart to erase(), it only retains entries
corresponding to the listed keys.
For example,
HashTable<someType> largeCache;
wordHashSet preserve = ...;
largeCache.retain(preserve);
being roughly equivalent to the following two-stage process,
but with reduced overhead and typing, and fewer potential mistakes.
HashTable<someType> largeCache;
wordHashSet preserve = ...;
{
wordHashSet cull(largeCache.toc()); // all keys
cull.erase(preserve); // except those to preserve
largeCache.erase(cull); //
}
The HashSet &= operator and retain() are functionally equivalent,
but retain() also works with dissimilar value types.
- provide key_iterator/const_key_iterator for all hashes,
reuse directly for HashSet as iterator/const_iterator, respectively.
- additional keys() method for HashTable that returns a wrapped to
a pair of begin/end const_iterators with additional size/empty
information that allows these to be used directly by anything else
expecting things with begin/end/size. Unfortunately does not yet
work with std::distance().
Example,
for (auto& k : labelHashTable.keys())
{
...
}
