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