stringUtils.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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/inttypes.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/enum.h"

#include <cstdarg>
#include <cstring>
#include <list>
#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 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 letters of the same case that differ, or of different
        // case that differ.  It is very rare that we have to account for
        // different cases, or numerical comparisons, so we special-case this
        // first.
        char l = lhs.c_str()[0], r = rhs.c_str()[0];
        if (((l & ~0x20) != (r & ~0x20)) & bool(l & r & ~0x3f)) {
            // 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>
typename std::enable_if<!std::is_enum<T>::value, std::string>::type
TfStringify(const T& v)
{
    std::ostringstream stream;
    stream << v;
    return stream.str();
}

template <typename T>
typename std::enable_if<std::is_enum<T>::value, std::string>::type
TfStringify(const T& v)
{
    return TfEnum::GetName(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);

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