- provides a summary hash of classes used and their associated object names.
The HashTable representation allows us to leverage various HashTable
methods. This hashed summary view can be useful when querying
particular aspects, but is most useful when reducing the objects in
consideration to a particular subset. For example,
const wordHashSet interestingTypes
{
volScalarField::typeName,
volVectorField::typeName
};
IOobjectList objects(runTime, runTime.timeName());
HashTable<wordHashSet> classes = objects.classes();
classes.retain(interestingTypes);
// Or do just the opposite:
classes.erase(unsupportedTypes);
Can also use the underlying HashTable filter methods
STYLE: use templated internals to avoid findString() when matching subsets
- 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.
- predicates::always and predicates::never returning true and false,
respectively. These simple classes make it easier when writing
templated code.
As well as unary and binary predicate forms, they also contain a
match(std::string) method for compatibility with regex-based classes.
STYLE: write bool and direction as primitive 'int' not as 'label'.
- ensure that the string-related classes have consistently similar
matching methods. Use operator()(const std::string) as an entry
point for the match() method, which makes it easier to use for
filters and predicates. In some cases this will also permit using
a HashSet as a match predicate.
regExp
====
- the set method now returns a bool to signal that the requested
pattern was compiled.
wordRe
====
- have separate constructors with the compilation option (was previously
a default parameter). This leaves the single parameter constructor
explicit, but the two parameter version is now non-explicit, which
makes it easier to use when building lists.
- renamed compile-option from REGEX (to REGEXP) for consistency with
with the <regex.h>, <regex> header names etc.
wordRes
====
- renamed from wordReListMatcher -> wordRes. For reduced typing and
since it behaves as an entity only slightly related to its underlying
list nature.
- Provide old name as typedef and include for code transition.
- pass through some list methods into wordRes
hashedWordList
====
- hashedWordList[const word& name] now returns a -1 if the name is is
not found in the list of indices. That has been a pending change
ever since hashedWordList was generalized out of speciesTable
(Oct-2010).
- add operator()(const word& name) for easy use as a predicate
STYLE: adjust parameter names in stringListOps
- reflect if the parameter is being used as a primary matcher, or the
matcher will be derived from the parameter.
For example,
(const char* re), which first creates a regExp
versus (const regExp& matcher) which is used directly.
- inherit from std::iterator to obtain the full STL typedefs, meaning
that std::distance works and the following is now possible:
labelRange range(100, 1500);
scalarList list(range.begin(), range.end());
--
Note that this does not work (mismatched data-types):
scalarList list = identity(12345);
But this does, since the *iter promotes label to scalar:
labelList ident = identity(12345);
scalarList list(ident.begin(), ident.end());
It is however more than slightly wasteful to create a labelList
just for initializing a scalarList. An alternative could be a
a labelRange for the same purpose.
labelRange ident = labelRange::identity(12345);
scalarList list(ident.begin(), ident.end());
Or this
scalarList list
(
labelRange::null.begin(),
labelRange::identity(12345).end()
);
- provides const/non-const access to the underlying list, but the
iterator access itself is const.
- provide linked-list iterator 'found()' method for symmetry with
hash-table iterators. Use nullptr for more clarity.
- 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.
- less clutter and typing to use the default template parameter when
the key is 'word' anyhow.
- use EdgeMap instead of the longhand HashTable version where
appropriate
- 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.
This uses a concept similar to what std::valarray and std::slice do.
A labelRange provides a convenient container for holding start/size
and lends itself to addressing 'sliced' views of lists.
For safety, the operations and constructors restricts the given input range
to a valid addressible region of the underlying list, while the labelRange
itself precludes negative sizes.
The SubList version is useful for patches or other things that have a
SubList as its parameter. Otherwise the UList [] operator will be the
more natural solution. The slices can be done with a labelRange, or
a {start,size} pair.
Examples,
labelList list1 = identity(20);
list1[labelRange(18,10)] = -1;
list1[{-20,25}] = -2;
list1[{1000,5}] = -3;
const labelList list2 = identity(20);
list2[{5,10}] = -3; // ERROR: cannot assign to const!
- some functionality similar to what the standary library <iterator>
provides.
* stdFoam::begin() and stdFoam::end() do type deduction,
which means that many cases it is possible to manage these types
of changes.
For example, when managing a number of indices:
Map<labelHashSet> lookup;
1) Longhand:
for
(
Map<labelHashSet>::const_iterator iter = lookup.begin();
iter != lookup.end();
++iter
)
{ .... }
1b) The same, but wrapped via a macro:
forAllConstIter(Map<labelHashSet>, lookup, iter)
{ .... }
2) Using stdFoam begin/end templates directly
for
(
auto iter = stdFoam::begin(lookup);
iter != stdFoam::end(lookup);
++iter
)
{ .... }
2b) The same, but wrapped via a macro:
forAllConstIters(lookup, iter)
{ .... }
Note that in many cases it is possible to simply use a range-based for.
Eg,
labelList myList;
for (auto val : myList)
{ ... }
for (const auto& val : myList)
{ ... }
These however will not work with any of the OpenFOAM hash-tables,
since the standard C++ concept of an iterator would return a key,value
pair when deferencing the *iter.
The deduction methods also exhibits some slightly odd behaviour with
some PtrLists (needs some more investigation).
- 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.
- more hash-like methods.
Eg, insert/erase via lists, clear(), empty(),...
- minVertex(), maxVertex() to return the smallest/largest label used
- improved documentation, more clarification about where/how negative
point labels are treated.
