TfHash Class Reference

#include <hash.h>

Public Member Functions
template<class T >
auto	operator() (T &&obj) const -> decltype(Tf_HashImpl(std::declval< Tf_HashState & >(), std::forward< T >(obj), 0), size_t())

Static Public Member Functions
template<class... Args>
static size_t	Combine (Args &&...args)
	Produce a hash code by combining the hash codes of several objects. More...

Detailed Description

A user-extensible hashing mechanism for use with runtime hash tables.

The hash functions here are appropriate for storing objects in runtime hash tables. They are not appropriate for document signatures / fingerprinting or for storage and offline use. No specific guarantee is made about hash function quality, and the resulting hash codes are only 64-bits wide. Callers must assume that collisions will occur and be prepared to deal with them.

Additionally, no guarantee is made about repeatability from run-to-run. That is, within a process lifetime an object's hash code will not change (provided its internal state does not change). But an object with equivalent state in a future run of the same process may hash differently.

At the time of this writing we observe good performance combined with the "avalanche" quality (~50% output bit flip probability for a single input bit flip) in the low-order 40 output bits. Higher order bits do not achieve avalanche, and the highest order 8 bits are particularly poor. But for our purposes we deem this performance/quality tradeoff acceptable.

This mechanism has builtin support for integral and floating point types, some STL types and types in Tf. TfHash uses three methods to attempt to hash a passed object. First, TfHash tries to call TfHashAppend() on its argument. This is the primary customization point for TfHash. If that is not viable, TfHash tries to call std::hash<T>{}(). Lastly, TfHash makes an unqualified call to hash_value.

The best way to add TfHash support for user-defined types is to provide a function overload like the following.

template <class HashState>
void TfHashAppend(HashState &h, MyType const &myObj)
    h.Append(myObject._member1,
             myObject._member2,
             myObject._member3);
    h.AppendContiguous(myObject._memberArray, myObject._numArrayElems);
}

The HashState object is left deliberately unspecified, so that different hash state objects may be used in different circumstances without modifying this support code, and without excess abstraction penalty. The methods available for use in TfHashAppend overloads are:

// Append several objects to the hash state.  This invokes the TfHash
// mechanism so it works for any types supported by TfHash.
template <class... Args>
void HashState::Append(Args &&... args);

// Append contiguous objects to the hash state.  Note that this is
// explicitly *not* guaranteed to produce the same result as calling
// Append() with each object in order.
template <class T>
void HashState::AppendContiguous(T const *objects, size_t numObjects);

// Append a general range of objects to the hash state.  Note that this is
// explicitly *not* guaranteed to produce the same result as calling
// Append() with each object in order.
template <class Iter>
void AppendRange(Iter f, Iter l);

The TfHash class function object supports:

• integral types (including bool)
• floating point types
• std::string
• TfRefPtr
• TfWeakPtr
• TfEnum
• const void*
• types that provide overloads for TfHashAppend
• types that provide overloads for std::hash
• types that provide overloads for hash_value

The TfHash class can be used to instantiate a TfHashMap with string keys as follows:

TfHashMap<string, int, TfHash> m;
m["abc"] = 1;

TfHash()(const char*) is disallowed to avoid confusion of whether the pointer or the string is being hashed. If you want to hash a C-string use TfHashCString and if you want to hash a char* use TfHashCharPtr.

Definition at line 477 of file hash.h.

Member Function Documentation

template<class... Args>

static size_t TfHash::Combine ( Args &&...  args )

inlinestatic

Produce a hash code by combining the hash codes of several objects.

Definition at line 492 of file hash.h.

template<class T >

auto TfHash::operator() ( T &&  obj ) const -> decltype(Tf_HashImpl(std::declval<Tf_HashState &>(), std::forward<T>(obj), 0), size_t())

inline

Produce a hash code for obj. See the class documentation for details.

Definition at line 482 of file hash.h.

---

The documentation for this class was generated from the following file:

• pxr/base/tf/hash.h