|
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::HashFunctor > | HashSet |
Predefined type for TfHashSet of tokens, since it's so awkward to manually specify. | |
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. | |
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. | |
TfToken & | operator= (TfToken const &rhs) noexcept |
Copy assignment. | |
TfToken & | operator= (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) |
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.
TfHashSet< TfToken, TfToken::HashFunctor > HashSet |
std::set< TfToken, TfTokenFastArbitraryLessThan > Set |
|
constexprdefaultnoexcept |
Create the empty token, containing the empty string.
|
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.
|
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.
|
static |
Find the token for the given string, if one exists.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
TF_API bool operator== | ( | const char * | ) | const |
Equality operator for char
strings.
Not as fast as direct token to token equality testing
TF_API bool operator== | ( | std::string const & | o | ) | const |
Equality operator for char
strings.
Not as fast as direct token to token equality testing
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
friend |
|
friend |
|
friend |
Stream insertion.
|
friend |
|
friend |
|
friend |
|
friend |