SdfPathTable< MappedType > Class Template Reference

A mapping from SdfPath to MappedType, somewhat similar to map<SdfPath, MappedType> and TfHashMap<SdfPath, MappedType>, but with key differences. More...

Classes

struct  NodeHandle
 A handle owning a path table node that may be used to "reserve" a stable memory location for key & mapped object. More...
 

Public Types

typedef SdfPath key_type
 
typedef MappedType mapped_type
 
typedef std::pair< key_type, mapped_type > value_type
 
typedef Iterator< value_type, _Entry * > iterator
 
typedef Iterator< const value_type, const _Entry * > const_iterator
 
typedef std::pair< iterator, bool > _IterBoolPair
 Result type for insert(). More...
 

Public Member Functions

 SdfPathTable ()
 Default constructor. More...
 
 SdfPathTable (SdfPathTable const &other)
 Copy constructor. More...
 
 SdfPathTable (SdfPathTable &&other)
 Move constructor. More...
 
 ~SdfPathTable ()
 Destructor. More...
 
SdfPathTableoperator= (SdfPathTable const &other)
 Copy assignment. More...
 
SdfPathTableoperator= (SdfPathTable &&other)
 Move assignment. More...
 
iterator begin ()
 Return an iterator to the start of the table. More...
 
const_iterator begin () const
 Return a const_iterator to the start of the table. More...
 
iterator end ()
 Return an iterator denoting the end of the table. More...
 
const_iterator end () const
 Return a const_iterator denoting the end of the table. More...
 
bool erase (SdfPath const &path)
 Remove the element with path path from the table as well as all elements whose paths are prefixed by path. More...
 
void erase (iterator const &i)
 Remove the element pointed to by i from the table as well as all elements whose paths are prefixed by i->first. More...
 
iterator find (SdfPath const &path)
 Return an iterator to the element corresponding to path, or end() if there is none. More...
 
const_iterator find (SdfPath const &path) const
 Return a const_iterator to the element corresponding to path, or end() if there is none. More...
 
std::pair< iterator, iterator > FindSubtreeRange (SdfPath const &path)
 Return a pair of iterators [b, e), describing the maximal range such that for all i in the range, i->first is b->first or is prefixed by b->first. More...
 
std::pair< const_iterator, const_iterator > FindSubtreeRange (SdfPath const &path) const
 Return a pair of const_iterators [b, e), describing the maximal range such that for all i in the range, i->first is b->first or is prefixed by b->first. More...
 
size_t count (SdfPath const &path) const
 Return 1 if there is an element for path in the table, otherwise 0. More...
 
size_t size () const
 Return the number of elements in the table. More...
 
bool empty () const
 Return true if this table is empty. More...
 
_IterBoolPair insert (value_type const &value)
 Insert value into the table, and additionally insert default entries for all ancestral paths of value.first that do not already exist in the table. More...
 
_IterBoolPair insert (NodeHandle &&node)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Insert the entry held by node into this table. More...
 
mapped_type & operator[] (SdfPath const &path)
 Shorthand for the following, where t is an SdfPathTable<T>. More...
 
void clear ()
 Remove all elements from the table, leaving size() == 0. More...
 
void ClearInParallel ()
 Equivalent to clear(), but destroy contained objects in parallel. More...
 
void swap (SdfPathTable &other)
 Swap this table's contents with other. More...
 
std::vector< size_t > GetBucketSizes () const
 Return a vector of the count of elements in each bucket. More...
 
void UpdateForRename (const SdfPath &oldName, const SdfPath &newName)
 Replaces all prefixes from oldName to newName. More...
 
template<typename Callback >
void ParallelForEach (Callback const &visitFn)
 ParallelForEach: parallel iteration over all of the key-value pairs in the path table. More...
 
template<typename Callback >
void ParallelForEach (Callback const &visitFn) const
 ParallelForEach: const version, runnable on a const path table and taking a (const SdfPath&, const mapped_type&) input. More...
 

Friends

template<class , class >
class Iterator
 

Detailed Description

template<class MappedType>
class SdfPathTable< MappedType >

A mapping from SdfPath to MappedType, somewhat similar to map<SdfPath, MappedType> and TfHashMap<SdfPath, MappedType>, but with key differences.

Notably:

Works exclusively with absolute paths.

Inserting a path p also implicitly inserts all of p's ancestors.

Erasing a path p also implicitly erases all of p's descendants.

The table has an order: it's a preordering of the paths in the table, but with arbitrary sibling order. Given a path p in the table, all other paths in the table with p as a prefix appear contiguously, immediately following p. For example, suppose a table contains the paths:

{'/a/b/c', '/a', '/a/d', '/', '/a/b'}

Then there are two possible valid orderings:

['/', '/a', '/a/d', '/a/b', '/a/b/c'] ['/', '/a', '/a/b', '/a/b/c', '/a/d']

In addition to the ordinary map and TfHashMap methods, this class provides a method FindSubtreeRange, which, given a path p, returns a pair of iterators [b, e) defining a range such that for every iterator i in [b, e), i->first is either equal to p or is prefixed by p.

Iterator Invalidation

Like most other node-based containers, iterators are only invalidated when the element they refer to is removed from the table. Note however, that since removing the element with path p also implicitly removes all elements with paths prefixed by p, a call to erase(i) may invalidate many iterators.

Definition at line 85 of file pathTable.h.

Member Typedef Documentation

◆ _IterBoolPair

typedef std::pair<iterator, bool> _IterBoolPair

Result type for insert().

Definition at line 288 of file pathTable.h.

Constructor & Destructor Documentation

◆ SdfPathTable() [1/3]

SdfPathTable ( )
inline

Default constructor.

Definition at line 374 of file pathTable.h.

◆ SdfPathTable() [2/3]

SdfPathTable ( SdfPathTable< MappedType > const &  other)
inline

Copy constructor.

Definition at line 377 of file pathTable.h.

◆ SdfPathTable() [3/3]

SdfPathTable ( SdfPathTable< MappedType > &&  other)
inline

Move constructor.

Definition at line 404 of file pathTable.h.

◆ ~SdfPathTable()

~SdfPathTable ( )
inline

Destructor.

Definition at line 414 of file pathTable.h.

Member Function Documentation

◆ begin() [1/2]

iterator begin ( )
inline

Return an iterator to the start of the table.

Definition at line 434 of file pathTable.h.

◆ begin() [2/2]

const_iterator begin ( ) const
inline

Return a const_iterator to the start of the table.

Definition at line 442 of file pathTable.h.

◆ clear()

void clear ( )
inline

Remove all elements from the table, leaving size() == 0.

Note that this function will not shrink the number of buckets used for the hash table. To do that, swap this instance with a default constructed instance. See also TfReset.

Definition at line 596 of file pathTable.h.

◆ ClearInParallel()

void ClearInParallel ( )
inline

Equivalent to clear(), but destroy contained objects in parallel.

This requires that running the contained objects' destructors is thread-safe.

Definition at line 612 of file pathTable.h.

◆ count()

size_t count ( SdfPath const &  path) const
inline

Return 1 if there is an element for path in the table, otherwise 0.

Definition at line 537 of file pathTable.h.

◆ empty()

bool empty ( ) const
inline

Return true if this table is empty.

Definition at line 545 of file pathTable.h.

◆ end() [1/2]

iterator end ( )
inline

Return an iterator denoting the end of the table.

Definition at line 450 of file pathTable.h.

◆ end() [2/2]

const_iterator end ( ) const
inline

Return a const_iterator denoting the end of the table.

Definition at line 455 of file pathTable.h.

◆ erase() [1/2]

bool erase ( SdfPath const &  path)
inline

Remove the element with path path from the table as well as all elements whose paths are prefixed by path.

Return true if any elements were removed, false otherwise.

Note that since descendant paths are also erased, size() may be decreased by more than one after calling this function.

Definition at line 465 of file pathTable.h.

◆ erase() [2/2]

void erase ( iterator const &  i)
inline

Remove the element pointed to by i from the table as well as all elements whose paths are prefixed by i->first.

i must be a valid iterator for this table.

Note that since descendant paths are also erased, size() may be decreased by more than one after calling this function.

Definition at line 479 of file pathTable.h.

◆ find() [1/2]

iterator find ( SdfPath const &  path)
inline

Return an iterator to the element corresponding to path, or end() if there is none.

Definition at line 490 of file pathTable.h.

◆ find() [2/2]

const_iterator find ( SdfPath const &  path) const
inline

Return a const_iterator to the element corresponding to path, or end() if there is none.

Definition at line 503 of file pathTable.h.

◆ FindSubtreeRange() [1/2]

std::pair<iterator, iterator> FindSubtreeRange ( SdfPath const &  path)
inline

Return a pair of iterators [b, e), describing the maximal range such that for all i in the range, i->first is b->first or is prefixed by b->first.

Definition at line 518 of file pathTable.h.

◆ FindSubtreeRange() [2/2]

std::pair<const_iterator, const_iterator> FindSubtreeRange ( SdfPath const &  path) const
inline

Return a pair of const_iterators [b, e), describing the maximal range such that for all i in the range, i->first is b->first or is prefixed by b->first.

Definition at line 529 of file pathTable.h.

◆ GetBucketSizes()

std::vector<size_t> GetBucketSizes ( ) const
inline

Return a vector of the count of elements in each bucket.

Definition at line 636 of file pathTable.h.

◆ insert() [1/2]

_IterBoolPair insert ( value_type const &  value)
inline

Insert value into the table, and additionally insert default entries for all ancestral paths of value.first that do not already exist in the table.

Return a pair of iterator and bool. The iterator points to the inserted element, the bool indicates whether insertion was successful. The bool is true if value was successfully inserted and false if an element with path value.first was already present in the map.

Note that since ancestral paths are also inserted, size() may be increased by more than one after calling this function.

Definition at line 558 of file pathTable.h.

◆ insert() [2/2]

_IterBoolPair insert ( NodeHandle &&  node)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Insert the entry held by node into this table.

If the insertion is successful, the contents of node are moved-from and indeterminate. Otherwise if the insertion is unsuccessful, the contents of node are unmodified.

Definition at line 574 of file pathTable.h.

◆ operator=() [1/2]

SdfPathTable& operator= ( SdfPathTable< MappedType > const &  other)
inline

Copy assignment.

Definition at line 420 of file pathTable.h.

◆ operator=() [2/2]

SdfPathTable& operator= ( SdfPathTable< MappedType > &&  other)
inline

Move assignment.

Definition at line 427 of file pathTable.h.

◆ operator[]()

mapped_type& operator[] ( SdfPath const &  path)
inline

Shorthand for the following, where t is an SdfPathTable<T>.

t.insert(value_type(path, mapped_type())).first->second

Definition at line 588 of file pathTable.h.

◆ ParallelForEach() [1/2]

void ParallelForEach ( Callback const &  visitFn)
inline

ParallelForEach: parallel iteration over all of the key-value pairs in the path table.

The type of visitFn should be a callable, taking a (const SdfPath&, mapped_type&), representing the loop body. Note: since this function is run in parallel, visitFn is responsible for synchronizing access to any non-pathtable state.

Definition at line 673 of file pathTable.h.

◆ ParallelForEach() [2/2]

void ParallelForEach ( Callback const &  visitFn) const
inline

ParallelForEach: const version, runnable on a const path table and taking a (const SdfPath&, const mapped_type&) input.

Definition at line 690 of file pathTable.h.

◆ size()

size_t size ( ) const
inline

Return the number of elements in the table.

Definition at line 542 of file pathTable.h.

◆ swap()

void swap ( SdfPathTable< MappedType > &  other)
inline

Swap this table's contents with other.

Definition at line 629 of file pathTable.h.

◆ UpdateForRename()

void UpdateForRename ( const SdfPath oldName,
const SdfPath newName 
)
inline

Replaces all prefixes from oldName to newName.

Note that oldName and newName need to be silbing paths (ie. their parent paths must be the same).

Definition at line 649 of file pathTable.h.


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