TfToken Class Reference

#include <token.h>

Classes
struct	HashFunctor
	Functor to use for hash maps from tokens to other things. More...

Public Types
enum	_ImmortalTag { Immortal }
typedef TfHashSet< TfToken, TfToken::HashFunctor >	HashSet
typedef std::set< TfToken, TfTokenFastArbitraryLessThan >	Set

Public Member Functions
constexpr	TfToken () noexcept=default
	Create the empty token, containing the empty string. More...
	TfToken (TfToken const &rhs) noexcept
	Copy constructor. More...
	TfToken (TfToken &&rhs) noexcept
	Move constructor. More...
TfToken &	operator= (TfToken const &rhs) noexcept
	Copy assignment. More...
TfToken &	operator= (TfToken &&rhs) noexcept
	Move assignment. More...
	~TfToken ()
	Destructor. More...
TF_API	TfToken (std::string const &s)
	Acquire a token for the given string. More...
TF_API	TfToken (std::string const &s, _ImmortalTag)
TF_API	TfToken (char const *s)
	Acquire a token for the given string. More...
TF_API	TfToken (char const *s, _ImmortalTag)
size_t	Hash () const
	Return a size_t hash for this token. More...
size_t	size () const
	Return the size of the string that this token represents. More...
char const *	GetText () const
char const *	data () const
	Synonym for GetText(). More...
std::string const &	GetString () const
	Return the string that this token represents. More...
void	Swap (TfToken &other)
	Swap this token with another. More...
bool	operator== (TfToken const &o) const
	Equality operator. More...
bool	operator!= (TfToken const &o) const
	Equality operator. More...
TF_API bool	operator== (std::string const &o) const
TF_API bool	operator== (const char *) const
bool	operator!= (std::string const &o) const
bool	operator!= (char const *o) const
bool	operator< (TfToken const &r) const
bool	operator> (TfToken const &o) const
	Greater-than operator that compares tokenized strings lexicographically. More...
bool	operator>= (TfToken const &o) const
bool	operator<= (TfToken const &o) const
	operator std::string const & () const
	Allow TfToken to be auto-converted to string. More...
bool	IsEmpty () const
	Returns true iff this token contains the empty string "". More...
bool	IsImmortal () const

Static Public Member Functions
static TF_API TfToken	Find (std::string const &s)
	Find the token for the given string, if one exists. More...

Friends
struct	TfTokenFastArbitraryLessThan
struct	Tf_TokenRegistry
bool	operator== (std::string const &o, TfToken const &t)
bool	operator== (const char *o, TfToken const &t)
bool	operator!= (std::string const &o, TfToken const &t)
bool	operator!= (char const *o, TfToken const &t)
TF_API std::ostream &	operator<< (std::ostream &stream, TfToken const &)
	Stream insertion. More...
template<class HashState >
void	TfHashAppend (HashState &h, TfToken const &token)
	TfHash support. More...
void	swap (TfToken &lhs, TfToken &rhs)

Detailed Description

Token for efficient comparison, assignment, and hashing of known strings.

A TfToken is a handle for a registered string, and can be compared, assigned, and hashed in constant time. It is useful when a bounded number of strings are used as fixed symbols (but never modified).

For example, the set of avar names in a shot is large but bounded, and once an avar name is discovered, it is never manipulated. If these names were passed around as strings, every comparison and hash would be linear in the number of characters. (String assignment itself is sometimes a constant time operation, but it is sometimes linear in the length of the string as well as requiring a memory allocation.)

To use TfToken, simply create an instance from a string or const char*. If the string hasn't been seen before, a copy of it is added to a global table. The resulting TfToken is simply a wrapper around an string*, pointing that canonical copy of the string. Thus, operations on the token are very fast. (The string's hash is simply the address of the canonical copy, so hashing the string is constant time.)

The free functions TfToTokenVector() and TfToStringVector() provide conversions to and from vectors of string.

Note: Access to the global table is protected by a mutex. This is a good idea as long as clients do not construct tokens from strings too frequently. Construct tokens only as often as you must (for example, as you read data files), and never in inner loops. Of course, once you have a token, feel free to compare, assign, and hash it as often as you like. (That's what it's for.) In order to help prevent tokens from being re-created over and over, auto type conversion from string and char* to TfToken is disabled (you must use the explicit TfToken constructors). However, auto conversion from TfToken to string and char* is provided.

Definition at line 87 of file token.h.

Member Typedef Documentation

TfHashSet< TfToken, TfToken::HashFunctor > TfToken::HashSet

Predefined type for TfHashSet of tokens, since it's so awkward to manually specify.

Definition at line 175 of file token.h.

std::set< TfToken, TfTokenFastArbitraryLessThan > TfToken::Set

Predefined type for set of tokens, for when faster lookup is desired, without paying the memory or initialization cost of a TfHashSet.

Definition at line 183 of file token.h.

Member Enumeration Documentation

enum TfToken::_ImmortalTag

Enumerator
Immortal

Definition at line 90 of file token.h.

Constructor & Destructor Documentation

constexpr TfToken::TfToken ( )

defaultnoexcept

Create the empty token, containing the empty string.

TfToken::TfToken ( TfToken const &  rhs )

inlinenoexcept

Copy constructor.

Definition at line 96 of file token.h.

TfToken::TfToken ( TfToken &&  rhs )

inlinenoexcept

Move constructor.

Definition at line 99 of file token.h.

TfToken::~TfToken ( )

inline

Destructor.

Definition at line 124 of file token.h.

TF_API TfToken::TfToken ( std::string const &  s )

explicit

Acquire a token for the given string.

TF_API TfToken::TfToken	(	std::string const &	s,
		_ImmortalTag
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

TF_API TfToken::TfToken ( char const *  s )

explicit

Acquire a token for the given string.

TF_API TfToken::TfToken	(	char const *	s,
		_ImmortalTag
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Function Documentation

char const* TfToken::data ( ) const

inline

Synonym for GetText().

Definition at line 202 of file token.h.

static TF_API TfToken TfToken::Find ( std::string const &  s )

static

Find the token for the given string, if one exists.

std::string const& TfToken::GetString ( ) const

inline

Return the string that this token represents.

Definition at line 207 of file token.h.

char const* TfToken::GetText ( ) const

inline

Return the text that this token represents.

Note

The returned pointer value is not valid after this TfToken object has been destroyed.

Definition at line 196 of file token.h.

size_t TfToken::Hash ( ) const

inline

Return a size_t hash for this token.

Definition at line 432 of file token.h.

bool TfToken::IsEmpty ( ) const

inline

Returns true iff this token contains the empty string "".

Definition at line 305 of file token.h.

bool TfToken::IsImmortal ( ) const

inline

Returns true iff this is an immortal token. Note that a return of false could be instantly stale if another thread races to immortalize this token. A return of true is always valid since tokens cannot lose immortality.

Definition at line 311 of file token.h.

TfToken::operator std::string const & ( ) const

inline

Allow TfToken to be auto-converted to string.

Definition at line 302 of file token.h.

bool TfToken::operator!= ( TfToken const &  o ) const

inline

Equality operator.

Definition at line 224 of file token.h.

bool TfToken::operator!= ( std::string const &  o ) const

inline

Inequality operator for string's. Not as fast as direct token to token equality testing

Definition at line 248 of file token.h.

bool TfToken::operator!= ( char const *  o ) const

inline

Inequality operator for char strings. Not as fast as direct token to token equality testing

Definition at line 259 of file token.h.

bool TfToken::operator< ( TfToken const &  r ) const

inline

Less-than operator that compares tokenized strings lexicographically. Allows TfToken to be used in std::set

Definition at line 270 of file token.h.

bool TfToken::operator<= ( TfToken const &  o ) const

inline

Less-than-or-equal operator that compares tokenized strings lexicographically.

Definition at line 297 of file token.h.

TfToken& TfToken::operator= ( TfToken const &  rhs )

inlinenoexcept

Copy assignment.

Definition at line 104 of file token.h.

TfToken& TfToken::operator= ( TfToken &&  rhs )

inlinenoexcept

Move assignment.

Definition at line 114 of file token.h.

bool TfToken::operator== ( TfToken const &  o ) const

inline

Equality operator.

Definition at line 218 of file token.h.

TF_API bool TfToken::operator==

(

std::string const &

o

)

const

Equality operator for char strings. Not as fast as direct token to token equality testing

TF_API bool TfToken::operator==

(

const char *

)

const

Equality operator for char strings. Not as fast as direct token to token equality testing

bool TfToken::operator> ( TfToken const &  o ) const

inline

Greater-than operator that compares tokenized strings lexicographically.

Definition at line 285 of file token.h.

bool TfToken::operator>= ( TfToken const &  o ) const

inline

Greater-than-or-equal operator that compares tokenized strings lexicographically.

Definition at line 291 of file token.h.

size_t TfToken::size ( void  ) const

inline

Return the size of the string that this token represents.

Definition at line 186 of file token.h.

void TfToken::Swap ( TfToken &  other )

inline

Swap this token with another.

Definition at line 213 of file token.h.

Friends And Related Function Documentation

bool operator!= ( std::string const &  o, TfToken const &  t  )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 253 of file token.h.

bool operator!= ( char const *  o, TfToken const &  t  )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 264 of file token.h.

TF_API std::ostream& operator<< ( std::ostream &  stream, TfToken const &    )

friend

Stream insertion.

bool operator== ( std::string const &  o, TfToken const &  t  )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 237 of file token.h.

bool operator== ( const char *  o, TfToken const &  t  )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 242 of file token.h.

void swap ( TfToken &  lhs, TfToken &  rhs  )

friend

Definition at line 337 of file token.h.

friend struct Tf_TokenRegistry

friend

Definition at line 424 of file token.h.

template<class HashState >

void TfHashAppend ( HashState &  h, TfToken const &  token  )

friend

TfHash support.

Definition at line 331 of file token.h.

friend struct TfTokenFastArbitraryLessThan

friend

Definition at line 423 of file token.h.

---

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

• pxr/base/tf/token.h