Loading...
Searching...
No Matches
TfToken Class Reference

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

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

Public Member Functions

constexpr TfToken () noexcept=default
 Create the empty token, containing the empty string.
 
 TfToken (TfToken const &rhs) noexcept
 Copy constructor.
 
 TfToken (TfToken &&rhs) noexcept
 Move constructor.
 
TfTokenoperator= (TfToken const &rhs) noexcept
 Copy assignment.
 
TfTokenoperator= (TfToken &&rhs) noexcept
 Move assignment.
 
 ~TfToken ()
 Destructor.
 
TF_API TfToken (std::string const &s)
 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)
 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.
 
size_t Hash () const
 Return a size_t hash for this token.
 
size_t size () const
 Return the size of the string that this token represents.
 
char const * GetText () const
 Return the text that this token represents.
 
char const * data () const
 Synonym for GetText().
 
std::string const & GetString () const
 Return the string that this token represents.
 
void Swap (TfToken &other)
 Swap this token with another.
 
bool operator== (TfToken const &o) const
 Equality operator.
 
bool operator!= (TfToken const &o) const
 Equality operator.
 
TF_API bool operator== (std::string const &o) const
 Equality operator for char strings.
 
TF_API bool operator== (const char *) const
 Equality operator for char strings.
 
bool operator!= (std::string const &o) const
 Inequality operator for string's.
 
bool operator!= (char const *o) const
 Inequality operator for char strings.
 
bool operator< (TfToken const &r) const
 Less-than operator that compares tokenized strings lexicographically.
 
bool operator> (TfToken const &o) const
 Greater-than operator that compares tokenized strings lexicographically.
 
bool operator>= (TfToken const &o) const
 Greater-than-or-equal operator that compares tokenized strings lexicographically.
 
bool operator<= (TfToken const &o) const
 Less-than-or-equal operator that compares tokenized strings lexicographically.
 
 operator std::string const & () const
 Allow TfToken to be auto-converted to string.
 
bool IsEmpty () const
 Returns true iff this token contains the empty string "".
 
bool IsImmortal () const
 Returns true iff this is an immortal token.
 

Static Public Member Functions

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

Friends

struct TfTokenFastArbitraryLessThan
 
bool operator== (std::string const &o, TfToken const &t)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
bool operator== (const char *o, TfToken const &t)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
bool operator!= (std::string const &o, TfToken const &t)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
bool operator!= (char const *o, TfToken const &t)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
TF_API std::ostream & operator<< (std::ostream &stream, TfToken const &)
 Stream insertion.
 
template<class HashState >
void TfHashAppend (HashState &h, TfToken const &token)
 TfHash support.
 
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

◆ HashSet

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

Definition at line 175 of file token.h.

◆ 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

◆ _ImmortalTag

enum _ImmortalTag

Definition at line 90 of file token.h.

Constructor & Destructor Documentation

◆ TfToken() [1/7]

constexpr TfToken ( )
constexprdefaultnoexcept

Create the empty token, containing the empty string.

◆ TfToken() [2/7]

TfToken ( TfToken const &  rhs)
inlinenoexcept

Copy constructor.

Definition at line 96 of file token.h.

◆ TfToken() [3/7]

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.

◆ TfToken() [4/7]

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

Acquire a token for the given string.

◆ TfToken() [5/7]

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.

◆ TfToken() [6/7]

TF_API TfToken ( char const *  s)
explicit

Acquire a token for the given string.

◆ TfToken() [7/7]

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

◆ data()

char const * data ( ) const
inline

Synonym for GetText().

Definition at line 202 of file token.h.

◆ Find()

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

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

◆ GetString()

std::string const & GetString ( ) const
inline

Return the string that this token represents.

Definition at line 207 of file token.h.

◆ GetText()

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

◆ Hash()

size_t Hash ( ) const
inline

Return a size_t hash for this token.

Definition at line 432 of file token.h.

◆ IsEmpty()

bool IsEmpty ( ) const
inline

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

Definition at line 305 of file token.h.

◆ IsImmortal()

bool 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.

◆ operator std::string const &()

operator std::string const & ( ) const
inline

Allow TfToken to be auto-converted to string.

Definition at line 302 of file token.h.

◆ operator!=() [1/3]

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

◆ operator!=() [2/3]

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

◆ operator!=() [3/3]

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

Equality operator.

Definition at line 224 of file token.h.

◆ operator<()

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

◆ operator<=()

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

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

Definition at line 297 of file token.h.

◆ operator=() [1/2]

TfToken & operator= ( TfToken &&  rhs)
inlinenoexcept

Move assignment.

Definition at line 114 of file token.h.

◆ operator=() [2/2]

TfToken & operator= ( TfToken const &  rhs)
inlinenoexcept

Copy assignment.

Definition at line 104 of file token.h.

◆ operator==() [1/3]

TF_API bool operator== ( const char *  ) const

Equality operator for char strings.

Not as fast as direct token to token equality testing

◆ operator==() [2/3]

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

Equality operator for char strings.

Not as fast as direct token to token equality testing

◆ operator==() [3/3]

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

Equality operator.

Definition at line 218 of file token.h.

◆ operator>()

bool operator> ( TfToken const &  o) const
inline

Greater-than operator that compares tokenized strings lexicographically.

Definition at line 285 of file token.h.

◆ operator>=()

bool 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()

size_t size ( ) const
inline

Return the size of the string that this token represents.

Definition at line 186 of file token.h.

◆ Swap()

void Swap ( TfToken other)
inline

Swap this token with another.

Definition at line 213 of file token.h.

Friends And Related Function Documentation

◆ operator!= [1/2]

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.

◆ operator!= [2/2]

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.

◆ operator<<

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

Stream insertion.

◆ operator== [1/2]

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.

◆ operator== [2/2]

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.

◆ swap

void swap ( TfToken lhs,
TfToken rhs 
)
friend

Definition at line 337 of file token.h.

◆ TfHashAppend

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

TfHash support.

Definition at line 331 of file token.h.

◆ TfTokenFastArbitraryLessThan

friend struct TfTokenFastArbitraryLessThan
friend

Definition at line 423 of file token.h.


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