HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Group_tf_String

Files

file  hash.h
 
file  patternMatcher.h
 
file  stringUtils.h
 

Classes

class  TfDictionaryLessThan
 
struct  TfStreamFloat
 
struct  TfStreamDouble
 
class  TfHash
 
class  TfPatternMatcher
 
class  TfTemplateString
 
class  TfToken
 

Functions

TF_API std::string TfStringPrintf (const char *fmt,...)
 
TF_API std::string TfVStringPrintf (const std::string &fmt, va_list ap)
 
TF_API std::string TfVStringPrintf (const char *fmt, va_list ap)
 Bloat-avoidance version of TfVStringPrintf() More...
 
std::string TfSafeString (const char *ptr)
 
std::string TfIntToString (int i)
 Returns the given integer as a string. More...
 
TF_API double TfStringToDouble (const std::string &txt)
 
TF_API double TfStringToDouble (const char *text)
 
TF_API long TfStringToLong (const std::string &txt, bool *outOfRange=NULL)
 
TF_API long TfStringToLong (const char *txt, bool *outOfRange=NULL)
 
TF_API unsigned long TfStringToULong (const std::string &txt, bool *outOfRange=NULL)
 
TF_API unsigned long TfStringToULong (const char *txt, bool *outOfRange=NULL)
 
TF_API int64_t TfStringToInt64 (const std::string &txt, bool *outOfRange=NULL)
 
TF_API int64_t TfStringToInt64 (const char *txt, bool *outOfRange=NULL)
 
TF_API uint64_t TfStringToUInt64 (const std::string &txt, bool *outOfRange=NULL)
 
TF_API uint64_t TfStringToUInt64 (const char *txt, bool *outOfRange=NULL)
 
bool Tf_StringStartsWithImpl (char const *s, size_t slen, char const *prefix, size_t prelen)
 
bool TfStringStartsWith (const std::string &s, const char *prefix)
 Returns true if s starts with prefix. More...
 
bool TfStringStartsWith (const std::string &s, const std::string &prefix)
 
TF_API bool TfStringStartsWith (const std::string &s, const TfToken &prefix)
 
bool Tf_StringEndsWithImpl (char const *s, size_t slen, char const *suffix, size_t suflen)
 
bool TfStringEndsWith (const std::string &s, const char *suffix)
 Returns true if s ends with suffix. More...
 
bool TfStringEndsWith (const std::string &s, const std::string &suffix)
 
TF_API bool TfStringEndsWith (const std::string &s, const TfToken &suffix)
 
TF_API bool TfStringContains (const std::string &s, const char *substring)
 Returns true if s contains substring. More...
 
bool TfStringContains (const std::string &s, const std::string &substring)
 
TF_API bool TfStringContains (const std::string &s, const TfToken &substring)
 
TF_API std::string TfStringToLower (const std::string &source)
 Makes all characters in source lowercase, and returns the result. More...
 
TF_API std::string TfStringToUpper (const std::string &source)
 Makes all characters in source uppercase, and returns the result. More...
 
TF_API std::string TfStringCapitalize (const std::string &source)
 
TF_API std::string TfStringTrimLeft (const std::string &s, const char *trimChars=" \n\t\r")
 
TF_API std::string TfStringTrimRight (const std::string &s, const char *trimChars=" \n\t\r")
 
TF_API std::string TfStringTrim (const std::string &s, const char *trimChars=" \n\t\r")
 
TF_API std::string TfStringGetCommonPrefix (std::string a, std::string b)
 
TF_API std::string TfStringGetSuffix (const std::string &name, char delimiter= '.')
 
TF_API std::string TfStringGetBeforeSuffix (const std::string &name, char delimiter= '.')
 
TF_API std::string TfGetBaseName (const std::string &fileName)
 Returns the base name of a file (final component of the path). More...
 
TF_API std::string TfGetPathName (const std::string &fileName)
 
TF_API std::string TfStringReplace (const std::string &source, const std::string &from, const std::string &to)
 
template<class ForwardIterator >
std::string TfStringJoin (ForwardIterator begin, ForwardIterator end, const char *separator=" ")
 
TF_API std::string TfStringJoin (const std::vector< std::string > &strings, const char *separator=" ")
 
TF_API std::string TfStringJoin (const std::set< std::string > &strings, const char *separator=" ")
 
TF_API std::vector< std::stringTfStringSplit (std::string const &src, std::string const &separator)
 
TF_API std::vector< std::stringTfStringTokenize (const std::string &source, const char *delimiters=" \t\n")
 
TF_API std::set< std::stringTfStringTokenizeToSet (const std::string &source, const char *delimiters=" \t\n")
 
TF_API std::vector< std::stringTfQuotedStringTokenize (const std::string &source, const char *delimiters=" \t\n", std::string *errors=NULL)
 
TF_API std::vector< std::stringTfMatchedStringTokenize (const std::string &source, char openDelimiter, char closeDelimiter, char escapeCharacter= '\0', std::string *errors=NULL)
 
std::vector< std::stringTfMatchedStringTokenize (const std::string &source, char openDelimiter, char closeDelimiter, std::string *errors)
 
template<typename T >
std::enable_if<!std::is_enum
< T >::value, std::string >
::type 
TfStringify (const T &v)
 
TF_API std::string TfStringify (bool v)
 
TF_API std::string TfStringify (std::string const &)
 
TF_API std::string TfStringify (float)
 
TF_API std::string TfStringify (double)
 
TF_API bool TfDoubleToString (double d, char *buffer, int len, bool emitTrailingZero)
 
TF_API std::ostream & operator<< (std::ostream &o, TfStreamFloat t)
 
TF_API std::ostream & operator<< (std::ostream &o, TfStreamDouble t)
 
template<typename T >
TfUnstringify (const std::string &instring, bool *status=NULL)
 
template<>
TF_API bool TfUnstringify (const std::string &instring, bool *status)
 
TF_API std::string TfStringGlobToRegex (const std::string &s)
 
TF_API std::string TfEscapeString (const std::string &in)
 
TF_API void TfEscapeStringReplaceChar (const char **in, char **out)
 
TF_API std::string TfStringCatPaths (const std::string &prefix, const std::string &suffix)
 
bool TfIsValidIdentifier (std::string const &identifier)
 
TF_API std::string TfMakeValidIdentifier (const std::string &in)
 
TF_API std::string TfGetXmlEscapedString (const std::string &in)
 

Detailed Description

Function Documentation

TF_API std::ostream& operator<< ( std::ostream &  o,
TfStreamFloat  t 
)
TF_API std::ostream& operator<< ( std::ostream &  o,
TfStreamDouble  t 
)
bool Tf_StringEndsWithImpl ( char const s,
size_t  slen,
char const suffix,
size_t  suflen 
)
inline

Definition at line 233 of file stringUtils.h.

bool Tf_StringStartsWithImpl ( char const s,
size_t  slen,
char const prefix,
size_t  prelen 
)
inline

Definition at line 208 of file stringUtils.h.

TF_API bool TfDoubleToString ( double  d,
char *  buffer,
int  len,
bool  emitTrailingZero 
)

Writes the string representation of d to buffer of length len. If emitTrailingZero is true, the string representation will end with .0 in the case where d is an integer otherwise it will be omitted. The buffer length must be at least 25 in order to ensure that all doubles values can be represented. Returns whether the conversion was successful.

TF_API std::string TfEscapeString ( const std::string in)

Process escape sequences in ANSI C string constants.

The following escape sequences are accepted:

  • \\: backslash
  • \a: ring the bell
  • \b: backspace
  • \f: form feed
  • \n: new line
  • \r: carriage return
  • \t: tab
  • \v: vertical tab
  • \xdd: hex constant
  • \ddd: octal constant

So, if the two-character sequence "\\n" appears in the string, it is replaced by an actual newline. Each hex and octal constant translates into one character in the output string. Hex constants can be any length, while octal constants are limited to 3 characters. Both are terminated by a character that is not a valid constant. Illegal escape sequences are replaced by the character following the backslash, so the two character sequence "\\c" would become "c". Processing continues until the input hits a NUL character in the input string - anything appearing after the NUL will be ignored.

TF_API void TfEscapeStringReplaceChar ( const char **  in,
char **  out 
)
TF_API std::string TfGetBaseName ( const std::string fileName)

Returns the base name of a file (final component of the path).

TF_API std::string TfGetPathName ( const std::string fileName)

Returns the path component of a file (complement of TfGetBaseName()).

The returned string ends in a '/' (or possibly a '\' on Windows), unless none was found in fileName, in which case the empty string is returned. In particular, TfGetPathName(s)+TfGetBaseName(s) == s for any string s (as long as s doesn't end with multiple adjacent slashes, which is illegal).

TF_API std::string TfGetXmlEscapedString ( const std::string in)

Escapes characters in in so that they are valid XML.

Returns the name with special characters (&, <, >, ", ') replaced with the corresponding escape sequences.

std::string TfIntToString ( int  i)
inline

Returns the given integer as a string.

Definition at line 107 of file stringUtils.h.

bool TfIsValidIdentifier ( std::string const identifier)
inline

Test whether identifier is valid.

An identifier is valid if it follows the C/Python identifier convention; that is, it must be at least one character long, must start with a letter or underscore, and must contain only letters, underscores, and numerals.

Definition at line 659 of file stringUtils.h.

TF_API std::string TfMakeValidIdentifier ( const std::string in)

Produce a valid identifier (see TfIsValidIdentifier) from in by replacing invalid characters with '_'. If in is empty, return "_".

TF_API std::vector<std::string> TfMatchedStringTokenize ( const std::string source,
char  openDelimiter,
char  closeDelimiter,
char  escapeCharacter = '\0',
std::string errors = NULL 
)

Breaks the given string apart by matching delimiters.

The string source is broken apart into individual words, where a word begins with openDelimiter and ends with a matching closeDelimiter. Any delimiters within the matching delimiters become part of the word, and anything outside matching delimiters gets dropped. For example, TfMatchedStringTokenize("{a} string {to {be} split}", '{', '}') would return a vector containing "a" and "to {be} split". If openDelimiter and closeDelimiter cannot be the same. errors, if provided, contains any error messages.

std::vector<std::string> TfMatchedStringTokenize ( const std::string source,
char  openDelimiter,
char  closeDelimiter,
std::string errors 
)
inline

This overloaded version of TfMatchedStringTokenize does not take an escapeCharacter parameter but does take

Parameters
errors.It allows TfMatchedStringTokenize to be called with or without an escapeCharacter and with or without errors.

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 475 of file stringUtils.h.

TF_API std::vector<std::string> TfQuotedStringTokenize ( const std::string source,
const char *  delimiters = " \t\n",
std::string errors = NULL 
)

Breaks the given quoted string apart, returning a vector of strings.

The string source is broken apart into individual words, where a word is delimited by the characters in delimiters. This function is similar to TfStringTokenize, except it considers a quoted string as a single word. The function will preserve quotes that are nested within other quotes or are preceded by a backslash character. errors, if provided, contains any error messages. Delimiters default to white space (space, tab, and newline).

std::string TfSafeString ( const char *  ptr)
inline

Safely create a std::string from a (possibly NULL) char*.

If ptr is NULL, the empty string is safely returned.

Definition at line 102 of file stringUtils.h.

TF_API std::string TfStringCapitalize ( const std::string source)

Returns a copy of the source string with only its first character capitalized. This emulates the behavior of Python's str.capitalize().

TF_API std::string TfStringCatPaths ( const std::string prefix,
const std::string suffix 
)

Concatenate two strings containing '/' and '..' tokens like a file path or scope name.

Tokenize the input strings using a '/' delimiter. Look for '..' tokens in the suffix and construct the appropriate result.

Examples:

  • TfStringCatPaths( "foo/bar", "jive" ) => "foo/bar/jive"
  • TfStringCatPaths( "foo/bar", "../jive" ) => "foo/jive"
TF_API bool TfStringContains ( const std::string s,
const char *  substring 
)

Returns true if s contains substring.

bool TfStringContains ( const std::string s,
const std::string substring 
)
inline

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 stringUtils.h.

TF_API bool TfStringContains ( const std::string s,
const TfToken substring 
)

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

bool TfStringEndsWith ( const std::string s,
const char *  suffix 
)
inline

Returns true if s ends with suffix.

Definition at line 240 of file stringUtils.h.

bool TfStringEndsWith ( const std::string s,
const std::string suffix 
)
inline

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

TF_API bool TfStringEndsWith ( const std::string s,
const TfToken suffix 
)

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::string TfStringGetBeforeSuffix ( const std::string name,
char  delimiter = '.' 
)

Returns everything up to the suffix of a string

Returns characters before the final character delimiter (default ".") of a string. Thus not-suffix of "abc.def" is "abc" using "." as the delimiter. If the delimiter does not occur, the original string is returned.

TF_API std::string TfStringGetCommonPrefix ( std::string  a,
std::string  b 
)

Returns the common prefix of the input strings, if any.

Copies of the input strings are compared. Returns a new string which is the longest prefix common to both input strings. If the strings have no common prefix, an empty string is returned.

TF_API std::string TfStringGetSuffix ( const std::string name,
char  delimiter = '.' 
)

Returns the suffix of a string

Returns characters after the final character delimiter (default ".") of a string. Thus suffix of "abc.def" is "def" using "." as the delimiter. If the delimiter does not occur, the empty string is returned.

TF_API std::string TfStringGlobToRegex ( const std::string s)

Returns a string with glob characters converted to their regular expression equivalents.

Currently, this transforms strings by replacing all instances of '.' with '.', '*' with '.*', and '?' with '.', in that order.

template<typename T >
std::enable_if<!std::is_enum<T>::value, std::string>::type TfStringify ( const T &  v)

Convert an arbitrary type into a string

Use the type's stream output operator to convert it into a string. You are free to use the stream operators in ostreamMethods.h, but are not required to do so.

Definition at line 523 of file stringUtils.h.

TF_API std::string TfStringify ( bool  v)

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::string TfStringify ( std::string const )

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::string TfStringify ( float  )

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::string TfStringify ( double  )

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

template<class ForwardIterator >
std::string TfStringJoin ( ForwardIterator  begin,
ForwardIterator  end,
const char *  separator = " " 
)

Concatenates the strings (begin, end), with default separator.

Returns the concatenation of the strings in the range begin to end, with separator (by default, a space) added between each successive pair of strings.

Definition at line 364 of file stringUtils.h.

TF_API std::string TfStringJoin ( const std::vector< std::string > &  strings,
const char *  separator = " " 
)

Concatenates strings, with default separator.

Returns the concatenation of the strings in strings, with separator (by default, a space) added between each successive pair of strings.

TF_API std::string TfStringJoin ( const std::set< std::string > &  strings,
const char *  separator = " " 
)

Concatenates strings, with default separator.

Returns the concatenation of the strings in strings, with separator (by default, a space) added between each successive pair of strings.

TF_API std::string TfStringPrintf ( const char *  fmt,
  ... 
)

Returns a string formed by a printf()-like specification.

TfStringPrintf() is a memory-safe way of forming a string using printf()-like formatting. For example,

string formatMsg(const string& caller, int i, double val[])
{
return TfStringfPrintf("%s: val[%d] = %g\n", caller.c_str(), i, val[i]);
}

The function is safe only to the extent that the arguments match the formatting string. In particular, be careful to pass strings themselves into TfStringPrintf() as in the above example (i.e. caller.c_str() as opposed to just passing caller).

Note
TfStringPrintf() is just a wrapper for ArchStringPrintf().
TF_API std::string TfStringReplace ( const std::string source,
const std::string from,
const std::string to 
)

Replaces all occurrences of string from with to in source

Returns a new string which is created by copying string and replacing every occurrence of from with to. Correctly handles the case in which to contains from.

TF_API std::vector<std::string> TfStringSplit ( std::string const src,
std::string const separator 
)

Breaks the given string apart, returning a vector of strings.

The string source is broken apart into individual words, where a word is delimited by the string separator. This function behaves like pythons string split method.

bool TfStringStartsWith ( const std::string s,
const char *  prefix 
)
inline

Returns true if s starts with prefix.

Definition at line 216 of file stringUtils.h.

bool TfStringStartsWith ( const std::string s,
const std::string prefix 
)
inline

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 224 of file stringUtils.h.

TF_API bool TfStringStartsWith ( const std::string s,
const TfToken prefix 
)

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

TF_API double TfStringToDouble ( const std::string txt)

Converts text string to double

This method converts strings to floating point numbers. It is similar to libc's atof(), but performs the conversion much more quickly.

It expects somewhat valid input: it will continue parsing the input until it hits an unrecognized character, as described by the regexp below, and at that point will return the results up to that point.

(-?[0-9]+(.[0-9]*)?|-?.[0-9]+)([eE][-+]?[0-9]+)?

It will not check to see if there is any input at all, or whitespace after the digits. Ie: TfStringToDouble("") == 0.0 TfStringToDouble("blah") == 0.0 TfStringToDouble("-") == -0.0 TfStringToDouble("1.2foo") == 1.2

Note
TfStringToDouble is a wrapper around the extern-c TfStringToDouble
TF_API double TfStringToDouble ( const char *  text)

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

TF_API int64_t TfStringToInt64 ( const std::string txt,
bool *  outOfRange = NULL 
)

Convert a sequence of digits in txt to an int64_t value. Caller must ensure that txt has content matching:

-?[0-9]+

If the digit sequence's value is out of range, set *outOfRange to true (if outOfRange is not NULL) and return either std::numeric_limits<int64_t>::min() or max(), whichever is closest to the true value.

TF_API int64_t TfStringToInt64 ( const char *  txt,
bool *  outOfRange = NULL 
)

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::vector<std::string> TfStringTokenize ( const std::string source,
const char *  delimiters = " \t\n" 
)

Breaks the given string apart, returning a vector of strings.

The string source is broken apart into individual words, where a word is delimited by the characters in delimiters. Delimiters default to white space (space, tab, and newline).

TF_API std::set<std::string> TfStringTokenizeToSet ( const std::string source,
const char *  delimiters = " \t\n" 
)

Breaks the given string apart, returning a set of strings.

Same as TfStringTokenize, except this one returns a set.

TF_API long TfStringToLong ( const std::string txt,
bool *  outOfRange = NULL 
)

Convert a sequence of digits in txt to a long int value. Caller is responsible for ensuring that txt has content matching:

-?[0-9]+

If the digit sequence's value is out of range, set *outOfRange to true (if outOfRange is not NULL) and return either std::numeric_limits<long>::min() or max(), whichever is closest to the true value.

TF_API long TfStringToLong ( const char *  txt,
bool *  outOfRange = NULL 
)

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::string TfStringToLower ( const std::string source)

Makes all characters in source lowercase, and returns the result.

TF_API uint64_t TfStringToUInt64 ( const std::string txt,
bool *  outOfRange = NULL 
)

Convert a sequence of digits in txt to a uint64_t value. Caller is responsible for ensuring that txt has content matching:

[0-9]+

If the digit sequence's value is out of range, set *outOfRange to true (if outOfRange is not NULL) and return std::numeric_limits<unsigned long>="">max().

TF_API uint64_t TfStringToUInt64 ( const char *  txt,
bool *  outOfRange = NULL 
)

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

TF_API unsigned long TfStringToULong ( const std::string txt,
bool *  outOfRange = NULL 
)

Convert a sequence of digits in txt to an unsigned long value. Caller is responsible for ensuring that txt has content matching:

[0-9]+

If the digit sequence's value is out of range, set *outOfRange to true (if outOfRange is not NULL) and return std::numeric_limits<unsigned long>="">max().

TF_API unsigned long TfStringToULong ( const char *  txt,
bool *  outOfRange = NULL 
)

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::string TfStringToUpper ( const std::string source)

Makes all characters in source uppercase, and returns the result.

TF_API std::string TfStringTrim ( const std::string s,
const char *  trimChars = " \n\t\r" 
)

Trims characters (by default, whitespace) from the beginning and end of string.

Characters at the beginning and end of s are removed until a character not in trimChars is found; the result is returned.

TF_API std::string TfStringTrimLeft ( const std::string s,
const char *  trimChars = " \n\t\r" 
)

Trims characters (by default, whitespace) from the left.

Characters from the beginning of s are removed until a character not in trimChars is found; the result is returned.

TF_API std::string TfStringTrimRight ( const std::string s,
const char *  trimChars = " \n\t\r" 
)

Trims characters (by default, whitespace) from the right.

Characters at the end of s are removed until a character not in trimChars is found; the result is returned.

template<typename T >
T TfUnstringify ( const std::string instring,
bool *  status = NULL 
)

Convert a string to an arbitrary type

Use the type's stream input operator to get it from a string. If status is non-NULL and instring cannot be converted to a T, *status is set to false; otherwise, *status is not modified.

Definition at line 585 of file stringUtils.h.

template<>
TF_API bool TfUnstringify ( const std::string instring,
bool *  status = NULL 
)

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

Convert a string to an arbitrary type

Use the type's stream input operator to get it from a string. If status is non-NULL and instring cannot be converted to a T, *status is set to false; otherwise, *status is not modified.

Definition at line 585 of file stringUtils.h.

TF_API std::string TfVStringPrintf ( const std::string fmt,
va_list  ap 
)

Returns a string formed by a printf()-like specification.

TfVStringPrintf() is equivalent to TfStringPrintf() except that it is called with a va_list instead of a variable number of arguments. TfVStringPrintf() does not call the va_end macro. Consequently, the value of ap is undefined after the call. A functions that calls TfVStringPrintf() should call va_end(ap) itself afterwards.

Note
TfVStringPrintf() is just a wrapper for ArchVStringPrintf().
TF_API std::string TfVStringPrintf ( const char *  fmt,
va_list  ap 
)

Bloat-avoidance version of TfVStringPrintf()