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

Files

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

Classes

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

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 double TfStringToDouble (const char *text, int len)
 
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)
 
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 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 TfStringToLowerAscii (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::string > TfStringSplit (std::string const &src, std::string const &separator)
 
TF_API std::vector< std::string > TfStringTokenize (const std::string &source, const char *delimiters=" \t\n")
 
TF_API std::set< std::string > TfStringTokenizeToSet (const std::string &source, const char *delimiters=" \t\n")
 
TF_API std::vector< std::string > TfQuotedStringTokenize (const std::string &source, const char *delimiters=" \t\n", std::string *errors=NULL)
 
TF_API std::vector< std::string > TfMatchedStringTokenize (const std::string &source, char openDelimiter, char closeDelimiter, char escapeCharacter= '\0', std::string *errors=NULL)
 
std::vector< std::string > TfMatchedStringTokenize (const std::string &source, char openDelimiter, char closeDelimiter, std::string *errors)
 
template<typename T >
std::string 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 >
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 212 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 up to 2 digits, octal constants can be up to 3 digits. Both are terminated by a character that is not a valid constant. Note that it is good practice to encode hex and octal constants with maximum width (2 and 3 digits, respectively) using leading zeroes if necessary. This avoids problems where characters after the hex/octal constant that shouldn't be part of the constant get interpreted as part of it. For example, the sequence "\x2defaced" will produce the characters "-efaced" when what was probably intended was the character 0x02 (STX) followed by "defaced". 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 108 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 712 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 489 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 103 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 260 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 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::string 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 572 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 374 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 source 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 220 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 228 of file stringUtils.h.

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 double TfStringToDouble ( const char *  text,
int  len 
)

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

No empty strings are returned: delimiters at the start or end are ignored, consecutive delimiters are treated as though they were one, and an empty input will result in an empty return vector.

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

Locale-independent case folding of [A-Z] for ASCII or UTF-8 encoded source strings

This can be used for case insensitive matching where one of the strings being compared either known to be ASCII only by specification (like a URI scheme or an explicit token) or where the specification explicitly notes that only [A-Z] will be matched case insensitively.

TfStringEndsWith(TfStringToLowerAscii("ΓΌ.JPG"), ".jpg")
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 631 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 631 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()