includes:
ENH: simplify hashing overloads of string-types
- this revises the changes made in 95cd8ee75c to replace the
SFINAE-type of handling of string hashes with direct definitions.
This places a bit more burden on the developer if creating hashable
classes derived from std::string or variants of Foam::string, but
improves reliability when linking.
STYLE: drop template key defaulting from HashSet
- this was never used and `HashSet<>` is much less transparent
than writing `HashSet<word>` or `wordHashSet`
STYLE: use Hash<word> instead of string::hasher for runTimeSelectionTables
- 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.
- 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.
- use an IndirectListBase class for various indirect list types.
- new SortList type
In some places the SortList can be used as a lightweight alternative
to SortableList to have the convenience of bundling data and sort
indices together, but while operating on existing data lists.
In other situations, it can be useful as an alternative to
sortedOrder. For example,
pointField points = ...;
labelList order;
sortedOrder(points, order);
forAll(order, i)
{
points[order[i]] = ...;
}
Can be replaced with the following (with the same memory overhead)
pointField points = ...;
SortList<point> sortedPoints(points);
for (point& pt : sortedPoints)
{
pt = ...;
}
- new SliceList type (#1220), which can be used for stride-based
addressing into existing lists
- 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).
- improves backward compatibility and more naming consistency.
Retain setMany(iter1, iter2) to avoid ambiguity with the
PackedList::set(index, value) method.
- 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
- Eg instead of using labelHashSet, used HashSet<label> which uses
the string::hash for hashing. Other places inadvertently using the
string::hash instead of Hash<label> for hashing.
STYLE: use Map<..> instead of HashTable<.., label, Hash<label>>
- reduces clutter
- 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
- 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())
{
...
}
- previously had a mismash of const/non-const attributes on iterators
that were confused with the attributes of the object being accessed.
- use the iterator keys() and object() methods consistently for all
internal access of the HashTable iterators. This makes the intention
clearer, the code easier to maintain, and protects against any
possible changes in the definition of the operators.
- 'operator*': The standard form expected by STL libraries.
However, for the std::map, this dereferences to a <key,value> pair,
whereas OpenFOAM dereferences simply to <value>.
- 'operator()': OpenFOAM treats this like the 'operator*'
- adjusted the values of end() and cend() to reinterpret from nullObject
instead of returning a static iteratorEnd() object.
This means that C++ templates can now correctly deduce and match
the return types from begin() and end() consistently.
So that range-based now works.
Eg,
HashTable<label> table1 = ...;
for (auto i : table1)
{
Info<< i << endl;
}
Since the 'operator*' returns hash table values, this prints all the
values in the table.
- make construct from UList explicit and provide corresponding
assignment operator.
- add construct,insert,set,assignment from FixedList.
This is convenient when dealing with things like edges or triFaces.
- explicitly mention the value-initialized status for the operator().
This means that the following code will properly use an initialized
zero.
HashTable<label> regionCount;
if (...)
regionCount("region1")++;
... and also this;
if (regionCount("something") > 0)
{
...
}
Note that the OpenFOAM HashTable uses operator[] to provide read and
write access to *existing* entries and will provoke a FatalError if
the entry does not exist.
The operator() provides write access to *existing* entries or will
create the new entry as required.
The STL hashes use operator[] for this purpose.
DynamicList
-----------
- construction, assignment and append
HashSet
-------
- construction, insert, set.
- assignment will use the implicit List constructor
hashedWordList
--------------
- construction, assignment
- additional sort() and uniq() methods.
- Readonly access to HashTable information via lookup() method.
- NB: could avoid 'const char**' constructors in the future
- it was possible to create a PackedList::iterator from a
PackedList::const_iterator and violate const-ness
- added HashTable::printInfo for emitting some information
- changed default table sizes from 100 -> 128 in preparation for future
2^n table sizes
