This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
stringUtils.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_BASE_TF_STRING_UTILS_H
8#define PXR_BASE_TF_STRING_UTILS_H
9
13
14#include "pxr/pxr.h"
15
17#include "pxr/base/arch/hints.h"
19#include "pxr/base/tf/api.h"
20#include "pxr/base/tf/enum.h"
21
22#include <cstdarg>
23#include <cstring>
24#include <list>
25#include <set>
26#include <sstream>
27#include <string>
28#include <type_traits>
29#include <vector>
30
31PXR_NAMESPACE_OPEN_SCOPE
32
33class TfToken;
34
37
55TF_API
56std::string TfStringPrintf(const char *fmt, ...)
57#ifndef doxygen
59#endif /* doxygen */
60 ;
61
71TF_API
72std::string TfVStringPrintf(const std::string& fmt, va_list ap);
73
75
76TF_API
77std::string TfVStringPrintf(const char *fmt, va_list ap)
78#ifndef doxygen
80#endif /* doxygen */
81 ;
82
86inline std::string TfSafeString(const char* ptr) {
87 return ptr ? std::string(ptr) : std::string();
88}
89
91inline std::string TfIntToString(int i) {
92 return TfStringPrintf("%d", i);
93}
94
114TF_API double TfStringToDouble(const std::string& txt);
115
117TF_API double TfStringToDouble(const char *text);
118
120TF_API double TfStringToDouble(const char *text, int len);
121
133TF_API
134long TfStringToLong(const std::string &txt, bool *outOfRange=NULL);
135
137
138TF_API
139long TfStringToLong(const char *txt, bool *outOfRange=NULL);
140
151TF_API
152unsigned long TfStringToULong(const std::string &txt, bool *outOfRange=NULL);
153
155
156TF_API
157unsigned long TfStringToULong(const char *txt, bool *outOfRange=NULL);
158
170TF_API
171int64_t TfStringToInt64(const std::string &txt, bool *outOfRange=NULL);
172
174TF_API
175int64_t TfStringToInt64(const char *txt, bool *outOfRange=NULL);
176
187TF_API
188uint64_t TfStringToUInt64(const std::string &txt, bool *outOfRange=NULL);
189
191TF_API
192uint64_t TfStringToUInt64(const char *txt, bool *outOfRange=NULL);
193
194inline bool
195Tf_StringStartsWithImpl(char const *s, size_t slen,
196 char const *prefix, size_t prelen)
197{
198 return slen >= prelen && strncmp(s, prefix, prelen) == 0;
199}
200
202inline bool
203TfStringStartsWith(const std::string& s, const char *prefix)
204{
205 return Tf_StringStartsWithImpl(
206 s.c_str(), s.length(), prefix, strlen(prefix));
207}
208
210inline bool
211TfStringStartsWith(const std::string& s, const std::string& prefix) {
212 return TfStringStartsWith(s, prefix.c_str());
213}
214
215inline bool
216Tf_StringEndsWithImpl(char const *s, size_t slen,
217 char const *suffix, size_t suflen)
218{
219 return slen >= suflen && strcmp(s + (slen - suflen), suffix) == 0;
220}
221
223inline bool TfStringEndsWith(const std::string& s, const char *suffix)
224{
225 return Tf_StringEndsWithImpl(s.c_str(), s.length(),
226 suffix, strlen(suffix));
227}
228
230inline bool
231TfStringEndsWith(const std::string& s, const std::string& suffix)
232{
233 return TfStringEndsWith(s, suffix.c_str());
234}
235
237// \ingroup group_tf_String
238TF_API
239bool TfStringContains(const std::string& s, const char *substring);
240
242inline bool
243TfStringContains(const std::string &s, const std::string &substring) {
244 return TfStringContains(s, substring.c_str());
245}
246
248TF_API
249bool TfStringContains(const std::string &s, const TfToken& substring);
250
252TF_API
253std::string TfStringToLower(const std::string& source);
254
256TF_API
257std::string TfStringToUpper(const std::string& source);
258
261TF_API
262std::string TfStringCapitalize(const std::string& source);
263
275TF_API
276std::string TfStringToLowerAscii(const std::string& source);
277
282TF_API
283std::string TfStringTrimLeft(const std::string& s,
284 const char* trimChars = " \n\t\r");
285
290TF_API
291std::string TfStringTrimRight(const std::string& s,
292 const char* trimChars = " \n\t\r");
293
299TF_API
300std::string TfStringTrim(const std::string& s,
301 const char* trimChars = " \n\t\r");
302
308TF_API
309std::string TfStringGetCommonPrefix(std::string a, std::string b);
310
316TF_API
317std::string TfStringGetSuffix(const std::string& name, char delimiter = '.');
318
325TF_API
326std::string TfStringGetBeforeSuffix(const std::string& name, char delimiter = '.');
327
329TF_API
330std::string TfGetBaseName(const std::string& fileName);
331
339TF_API
340std::string TfGetPathName(const std::string& fileName);
341
347TF_API
348std::string TfStringReplace(const std::string& source, const std::string& from,
349 const std::string& to);
350
356template <class ForwardIterator>
357std::string TfStringJoin(
358 ForwardIterator begin, ForwardIterator end,
359 const char* separator = " ")
360{
361 if (begin == end)
362 return std::string();
363
364 size_t distance = std::distance(begin, end);
365 if (distance == 1)
366 return *begin;
367
368 std::string retVal;
369
370 size_t sum = 0;
371 ForwardIterator i = begin;
372 for (i = begin; i != end; ++i)
373 sum += i->size();
374 retVal.reserve(sum + strlen(separator) * (distance - 1));
375
376 i = begin;
377 retVal.append(*i);
378 while (++i != end) {
379 retVal.append(separator);
380 retVal.append(*i);
381 }
382
383 return retVal;
384}
385
390TF_API
391std::string TfStringJoin(const std::vector<std::string>& strings,
392 const char* separator = " ");
393
398TF_API
399std::string TfStringJoin(const std::set<std::string>& strings,
400 const char* separator = " ");
401
407TF_API
408std::vector<std::string> TfStringSplit(std::string const &src,
409 std::string const &separator);
410
420TF_API
421std::vector<std::string> TfStringTokenize(const std::string& source,
422 const char* delimiters = " \t\n");
423
427TF_API
428std::set<std::string> TfStringTokenizeToSet(const std::string& source,
429 const char* delimiters = " \t\n");
430
440TF_API
441std::vector<std::string>
442TfQuotedStringTokenize(const std::string& source,
443 const char* delimiters = " \t\n",
444 std::string *errors = NULL);
445
456TF_API
457std::vector<std::string>
458TfMatchedStringTokenize(const std::string& source,
459 char openDelimiter,
460 char closeDelimiter,
461 char escapeCharacter = '\0',
462 std::string *errors = NULL);
463
470inline
471std::vector<std::string>
472TfMatchedStringTokenize(const std::string& source,
473 char openDelimiter,
474 char closeDelimiter,
475 std::string *errors)
476{
477 return TfMatchedStringTokenize(source, openDelimiter,
478 closeDelimiter, '\0', errors);
479}
480
524 inline bool operator()(const std::string &lhs,
525 const std::string &rhs) const {
526 // Check first chars first. By far, it is most common that these
527 // characters are ASCII letters that differ. It is very rare that we
528 // have to account for different cases, or numerical comparisons, or
529 // UTF-8 characters so we special-case this first.
530 const unsigned char l = lhs.c_str()[0], r = rhs.c_str()[0];
531 const bool bothAscii = l < 0x80 && r < 0x80;
532 const bool differsIgnoringCase = (l & ~0x20) != (r & ~0x20);
533 const bool inLetterZone = (l >= 0x40) && (r >= 0x40);
534 if (ARCH_LIKELY(bothAscii && differsIgnoringCase && inLetterZone)) {
535 // This bit about add 5 mod 32 makes it so that '_' sorts less than
536 // all letters, which preserves existing behavior.
537 return ((l + 5) & 31) < ((r + 5) & 31);
538 }
539 else {
540 return _LessImpl(lhs, rhs);
541 }
542 }
543private:
544 TF_API bool _LessImpl(const std::string &lhs,
545 const std::string &rhs) const;
546};
547
553template <typename T>
554std::string
555TfStringify(const T& v)
556{
557 if constexpr (std::is_enum<T>::value) {
558 return TfEnum::GetName(v);
559 }
560 else {
561 std::ostringstream stream;
562 stream << v;
563 return stream.str();
564 }
565}
566
568TF_API std::string TfStringify(bool v);
570TF_API std::string TfStringify(std::string const&);
572TF_API std::string TfStringify(float);
574TF_API std::string TfStringify(double);
575
583 double d, char* buffer, int len, bool emitTrailingZero);
584
590 explicit TfStreamFloat(float f) : value(f) {}
591 float value;
592};
593
594TF_API std::ostream& operator<<(std::ostream& o, TfStreamFloat t);
595
601 explicit TfStreamDouble(double d) : value(d) {}
602 double value;
603};
604
605TF_API std::ostream& operator<<(std::ostream& o, TfStreamDouble t);
606
612template <typename T>
613T
614TfUnstringify(const std::string &instring, bool* status = NULL)
615{
616 T v = T();
617 std::istringstream stream(instring);
618 stream >> v;
619 if (status && !stream)
620 *status = false;
621 return v;
622}
623
625template <>
626TF_API
627bool TfUnstringify(const std::string &instring, bool* status);
629template <>
630TF_API
631std::string TfUnstringify(const std::string &instring, bool* status);
632
638TF_API
639std::string TfStringGlobToRegex(const std::string& s);
640
667//
672TF_API std::string TfEscapeString(const std::string &in);
673TF_API void TfEscapeStringReplaceChar(const char** in, char** out);
674
685TF_API
686std::string TfStringCatPaths( const std::string &prefix,
687 const std::string &suffix );
688
694inline bool
695TfIsValidIdentifier(std::string const &identifier)
696{
697 char const *p = identifier.c_str();
698 auto letter = [](unsigned c) { return ((c-'A') < 26) || ((c-'a') < 26); };
699 auto number = [](unsigned c) { return (c-'0') < 10; };
700 auto under = [](unsigned c) { return c == '_'; };
701 unsigned x = *p;
702 if (!x || number(x)) {
703 return false;
704 }
705 while (letter(x) || number(x) || under(x)) {
706 x = *p++;
707 };
708 return x == 0;
709}
710
713TF_API
714std::string
715TfMakeValidIdentifier(const std::string &in);
716
721TF_API
722std::string TfGetXmlEscapedString(const std::string &in);
723
725
726PXR_NAMESPACE_CLOSE_SCOPE
727
728#endif // PXR_BASE_TF_STRING_UTILS_H
Define function attributes.
#define ARCH_PRINTF_FUNCTION(_fmt, _firstArg)
Macro used to indicate a function takes a printf-like specification.
Definition: attributes.h:34
static TF_API std::string GetName(TfEnum val)
Returns the name associated with an enumerated value.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].
TF_API int64_t TfStringToInt64(const std::string &txt, bool *outOfRange=NULL)
Convert a sequence of digits in txt to an int64_t value.
TF_API bool TfStringContains(const std::string &s, const char *substring)
Returns true if s contains substring.
TF_API std::string TfStringTrimLeft(const std::string &s, const char *trimChars=" \n\t\r")
Trims characters (by default, whitespace) from the left.
bool TfStringStartsWith(const std::string &s, const char *prefix)
Returns true if s starts with prefix.
Definition: stringUtils.h:203
T TfUnstringify(const std::string &instring, bool *status=NULL)
Convert a string to an arbitrary type.
Definition: stringUtils.h:614
TF_API std::string TfStringToLower(const std::string &source)
Makes all characters in source lowercase, and returns the result.
std::string TfSafeString(const char *ptr)
Safely create a std::string from a (possibly NULL) char*.
Definition: stringUtils.h:86
TF_API std::string TfStringToLowerAscii(const std::string &source)
Locale-independent case folding of [A-Z] for ASCII or UTF-8 encoded source strings.
std::string TfIntToString(int i)
Returns the given integer as a string.
Definition: stringUtils.h:91
TF_API bool TfDoubleToString(double d, char *buffer, int len, bool emitTrailingZero)
Writes the string representation of d to buffer of length len.
TF_API std::string TfMakeValidIdentifier(const std::string &in)
Produce a valid identifier (see TfIsValidIdentifier) from in by replacing invalid characters with '_'...
std::string TfStringify(const T &v)
Convert an arbitrary type into a string.
Definition: stringUtils.h:555
TF_API std::string TfVStringPrintf(const std::string &fmt, va_list ap)
Returns a string formed by a printf()-like specification.
TF_API std::string TfStringGlobToRegex(const std::string &s)
Returns a string with glob characters converted to their regular expression equivalents.
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.
bool TfIsValidIdentifier(std::string const &identifier)
Test whether identifier is valid.
Definition: stringUtils.h:695
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.
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.
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.
TF_API std::string TfEscapeString(const std::string &in)
Process escape sequences in ANSI C string constants.
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.
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.
TF_API long TfStringToLong(const std::string &txt, bool *outOfRange=NULL)
Convert a sequence of digits in txt to a long int value.
TF_API std::string TfStringGetBeforeSuffix(const std::string &name, char delimiter='.')
Returns everything up to the suffix of a string.
bool TfStringEndsWith(const std::string &s, const char *suffix)
Returns true if s ends with suffix.
Definition: stringUtils.h:223
TF_API uint64_t TfStringToUInt64(const std::string &txt, bool *outOfRange=NULL)
Convert a sequence of digits in txt to a uint64_t value.
std::string TfStringJoin(ForwardIterator begin, ForwardIterator end, const char *separator=" ")
Concatenates the strings (begin, end), with default separator.
Definition: stringUtils.h:357
TF_API std::string TfStringCapitalize(const std::string &source)
Returns a copy of the source string with only its first character capitalized.
TF_API std::string TfStringGetCommonPrefix(std::string a, std::string b)
Returns the common prefix of the input strings, if any.
TF_API unsigned long TfStringToULong(const std::string &txt, bool *outOfRange=NULL)
Convert a sequence of digits in txt to an unsigned long value.
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 TfStringToUpper(const std::string &source)
Makes all characters in source uppercase, and returns the result.
TF_API std::string TfStringPrintf(const char *fmt,...)
Returns a string formed by a printf()-like specification.
TF_API std::string TfStringTrimRight(const std::string &s, const char *trimChars=" \n\t\r")
Trims characters (by default, whitespace) from the right.
TF_API double TfStringToDouble(const std::string &txt)
Converts text string to double.
TF_API std::string TfGetXmlEscapedString(const std::string &in)
Escapes characters in in so that they are valid XML.
TF_API std::string TfGetPathName(const std::string &fileName)
Returns the path component of a file (complement of TfGetBaseName()).
TF_API std::string TfStringGetSuffix(const std::string &name, char delimiter='.')
Returns the suffix of a string.
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.
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.
Compiler hints.
Define integral types.
Provides dictionary ordering binary predicate function on strings.
Definition: stringUtils.h:511
bool operator()(const std::string &lhs, const std::string &rhs) const
Return true if lhs is less than rhs in dictionary order.
Definition: stringUtils.h:524
A type which offers streaming for doubles in a canonical format that can safely roundtrip with the mi...
Definition: stringUtils.h:600
A type which offers streaming for floats in a canonical format that can safely roundtrip with the min...
Definition: stringUtils.h:589