stringUtils.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_TF_STRING_UTILS_H
#define PXR_BASE_TF_STRING_UTILS_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/base/arch/attributes.h"
#include "pxr/base/arch/hints.h"
#include "pxr/base/arch/inttypes.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/enum.h"
 
#include <cstdarg>
#include <cstring>
#include <list>
#include <locale>
#include <set>
#include <sstream>
#include <string>
#include <type_traits>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class TfToken;
 
 
TF_API
std::string TfStringPrintf(const char *fmt, ...)
#ifndef doxygen
    ARCH_PRINTF_FUNCTION(1, 2)
#endif /* doxygen */
    ;
 
TF_API
std::string TfVStringPrintf(const std::string& fmt, va_list ap);
 
 
TF_API
std::string TfVStringPrintf(const char *fmt, va_list ap)
#ifndef doxygen
    ARCH_PRINTF_FUNCTION(1, 0)
#endif /* doxygen */
    ;
 
inline std::string TfSafeString(const char* ptr) {
    return ptr ? std::string(ptr) : std::string();
}
 
inline std::string TfIntToString(int i) {
    return TfStringPrintf("%d", i);
}
 
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);
 
inline bool
Tf_StringStartsWithImpl(char const *s, size_t slen,
                        char const *prefix, size_t prelen)
{
    return slen >= prelen && strncmp(s, prefix, prelen) == 0;
}
 
inline bool
TfStringStartsWith(const std::string& s, const char *prefix)
{
    return Tf_StringStartsWithImpl(
        s.c_str(), s.length(), prefix, strlen(prefix));
}
 
inline bool
TfStringStartsWith(const std::string& s, const std::string& prefix) {
    return TfStringStartsWith(s, prefix.c_str());
}
 
inline bool
Tf_StringEndsWithImpl(char const *s, size_t slen,
                      char const *suffix, size_t suflen)
{
    return slen >= suflen && strcmp(s + (slen - suflen), suffix) == 0;
}
 
inline bool TfStringEndsWith(const std::string& s, const char *suffix)
{
    return Tf_StringEndsWithImpl(s.c_str(), s.length(),
                                 suffix, strlen(suffix));
}
 
inline bool
TfStringEndsWith(const std::string& s, const std::string& suffix)
{
    return TfStringEndsWith(s, suffix.c_str());
}
 
// \ingroup group_tf_String
TF_API
bool TfStringContains(const std::string& s, const char *substring);
 
inline bool
TfStringContains(const std::string &s, const std::string &substring) {
    return TfStringContains(s, substring.c_str());
}
 
TF_API
bool TfStringContains(const std::string &s, const TfToken& substring);
 
TF_API
std::string TfStringToLower(const std::string& source);
 
TF_API
std::string TfStringToUpper(const std::string& source);
 
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);
 
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 = " ")
{
    if (begin == end)
        return std::string();
 
    size_t distance = std::distance(begin, end);
    if (distance == 1)
        return *begin;
 
    std::string retVal;
 
    size_t sum = 0;
    ForwardIterator i = begin;
    for (i = begin; i != end; ++i)
        sum += i->size();
    retVal.reserve(sum + strlen(separator) * (distance - 1));
 
    i = begin;
    retVal.append(*i);
    while (++i != end) {
        retVal.append(separator);
        retVal.append(*i);
    }
 
    return retVal;
}
 
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);
 
inline
std::vector<std::string> 
TfMatchedStringTokenize(const std::string& source, 
                        char openDelimiter, 
                        char closeDelimiter, 
                        std::string *errors)
{
    return TfMatchedStringTokenize(source, openDelimiter,
                                   closeDelimiter, '\0', errors);
}
 
struct TfDictionaryLessThan {
    inline bool operator()(const std::string &lhs,
                           const std::string &rhs) const {
        // Check first chars first.  By far, it is most common that these
        // characters are ASCII letters that differ.  It is very rare that we
        // have to account for different cases, or numerical comparisons, or
        // UTF-8 characters so we special-case this first.
        const unsigned char l = lhs.c_str()[0], r = rhs.c_str()[0];
        const bool bothAscii = l < 0x80 && r < 0x80;
        const bool differsIgnoringCase = (l & ~0x20) != (r & ~0x20);
        const bool inLetterZone = (l >= 0x40) && (r >= 0x40);
        if (ARCH_LIKELY(bothAscii && differsIgnoringCase && inLetterZone)) {
            // This bit about add 5 mod 32 makes it so that '_' sorts less than
            // all letters, which preserves existing behavior.
            return ((l + 5) & 31) < ((r + 5) & 31);
        }
        else {
            return _LessImpl(lhs, rhs);
        }
    }
private:
    TF_API bool _LessImpl(const std::string &lhs,
                          const std::string &rhs) const;
};
 
template <typename T>
std::string
TfStringify(const T& v)
{
    if constexpr (std::is_enum<T>::value) {
        return TfEnum::GetName(v);
    }
    else {
        std::ostringstream stream;
        stream.imbue(std::locale::classic());
        stream << v;
        return stream.str();
    }
}
 
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);
 
struct TfStreamFloat {
    explicit TfStreamFloat(float f) : value(f) {}
    float value;
};
 
TF_API std::ostream& operator<<(std::ostream& o, TfStreamFloat t);
 
struct TfStreamDouble {
    explicit TfStreamDouble(double d) : value(d) {}
    double value;
};
 
TF_API std::ostream& operator<<(std::ostream& o, TfStreamDouble t);
 
template <typename T>
T
TfUnstringify(const std::string &instring, bool* status = NULL)
{
    T v = T();
    std::istringstream stream(instring);
    stream >> v;
    if (status && !stream)
        *status = false;
    return v;
}
 
template <>
TF_API 
bool TfUnstringify(const std::string &instring, bool* status);
template <>
TF_API 
std::string 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 );
 
inline bool
TfIsValidIdentifier(std::string const &identifier)
{
    char const *p = identifier.c_str();
    auto letter = [](unsigned c) { return ((c-'A') < 26) || ((c-'a') < 26); };
    auto number = [](unsigned c) { return (c-'0') < 10; };
    auto under = [](unsigned c) { return c == '_'; };
    unsigned x = *p;
    if (!x || number(x)) {
        return false;
    }
    while (letter(x) || number(x) || under(x)) {
        x = *p++;
    };
    return x == 0;
}
 
TF_API
std::string
TfMakeValidIdentifier(const std::string &in);
 
TF_API
std::string TfGetXmlEscapedString(const std::string &in);
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_TF_STRING_UTILS_H