All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TfToken Class Reference

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

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
 Predefined type for TfHashSet of tokens, since it's so awkward to manually specify. More...
 
typedef std::set< TfToken,
TfTokenFastArbitraryLessThan
Set
 Predefined type for set of tokens, for when faster lookup is desired, without paying the memory or initialization cost of a TfHashSet. More...
 

Public Member Functions

constexpr TfToken () noexcept
 Create the empty token, containing the empty string. More...
 
 TfToken (TfToken const &rhs) noexcept
 Copy constructor. More...
 
 TfToken (TfToken &&rhs) noexcept
 Move constructor. More...
 
TfTokenoperator= (TfToken const &rhs) noexcept
 Copy assignment. More...
 
TfTokenoperator= (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
 Return the text that this token represents. More...
 
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
 Equality operator for char strings. More...
 
TF_API bool operator== (const char *) const
 Equality operator for char strings. More...
 
bool operator!= (std::string const &o) const
 Inequality operator for string's. More...
 
bool operator!= (char const *o) const
 Inequality operator for char strings. More...
 
bool operator< (TfToken const &r) const
 Less-than operator that compares tokenized strings lexicographically. More...
 
bool operator> (TfToken const &o) const
 Greater-than operator that compares tokenized strings lexicographically. More...
 
bool operator>= (TfToken const &o) const
 Greater-than-or-equal operator that compares tokenized strings lexicographically. More...
 
bool operator<= (TfToken const &o) const
 Less-than-or-equal operator that compares tokenized strings lexicographically. More...
 
 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
 Returns true iff this is an immortal token. More...
 

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
 
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...
 
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 89 of file token.h.

Member Typedef Documentation

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

Definition at line 177 of file token.h.

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 185 of file token.h.

Constructor & Destructor Documentation

constexpr TfToken ( )
inlinenoexcept

Create the empty token, containing the empty string.

Definition at line 95 of file token.h.

TfToken ( TfToken const &  rhs)
inlinenoexcept

Copy constructor.

Definition at line 98 of file token.h.

TfToken ( TfToken &&  rhs)
inlinenoexcept

Move constructor.

Definition at line 101 of file token.h.

~TfToken ( )
inline

Destructor.

Definition at line 126 of file token.h.

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

Acquire a token for the given string.

TF_API 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 ( char const *  s)
explicit

Acquire a token for the given string.

TF_API 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* data ( ) const
inline

Synonym for GetText().

Definition at line 204 of file token.h.

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

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

std::string const& GetString ( ) const
inline

Return the string that this token represents.

Definition at line 209 of file token.h.

char const* 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 198 of file token.h.

size_t Hash ( ) const
inline

Return a size_t hash for this token.

Definition at line 165 of file token.h.

bool IsEmpty ( ) const
inline

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

Definition at line 311 of file token.h.

bool IsImmortal ( ) const
inline

Returns true iff this is an immortal token.

Definition at line 314 of file token.h.

operator std::string const & ( ) const
inline

Allow TfToken to be auto-converted to string.

Definition at line 308 of file token.h.

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

Equality operator.

Definition at line 228 of file token.h.

bool 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 252 of file token.h.

bool operator!= ( char const *  o) const
inline

Inequality operator for char strings.

Not as fast as direct token to token equality testing

Definition at line 263 of file token.h.

bool 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 274 of file token.h.

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

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

Definition at line 303 of file token.h.

TfToken& operator= ( TfToken const &  rhs)
inlinenoexcept

Copy assignment.

Definition at line 106 of file token.h.

TfToken& operator= ( TfToken &&  rhs)
inlinenoexcept

Move assignment.

Definition at line 116 of file token.h.

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

Equality operator.

Definition at line 220 of file token.h.

TF_API bool operator== ( std::string const &  o) const

Equality operator for char strings.

Not as fast as direct token to token equality testing

TF_API bool operator== ( const char *  ) const

Equality operator for char strings.

Not as fast as direct token to token equality testing

bool operator> ( TfToken const &  o) const
inline

Greater-than operator that compares tokenized strings lexicographically.

Definition at line 291 of file token.h.

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

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

Definition at line 297 of file token.h.

size_t size ( ) const
inline

Return the size of the string that this token represents.

Definition at line 188 of file token.h.

void Swap ( TfToken other)
inline

Swap this token with another.

Definition at line 215 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 257 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 268 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 241 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 246 of file token.h.


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