path.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef COMMON_PATH_H
#define COMMON_PATH_H
 
#include "common/scummsys.h"
#include "common/str.h"
#include "common/str-array.h"
 
#ifdef CXXTEST_RUNNING
class PathTestSuite;
#endif
 
namespace Common {
 
class Path {
#ifdef CXXTEST_RUNNING
    friend class ::PathTestSuite;
#endif
 
private:
#ifndef RELEASE_BUILD
    static bool _shownSeparatorCollisionWarning;
#endif
 
    // The directory separator
    static const char SEPARATOR = '/';
    // The escape prefix character
    static const char ESCAPE = '|';
    // How the prefix character is escaped (doubling)
    static const char ESCAPED_ESCAPE = '|';
    // How the separator is escaped
    static const char ESCAPED_SEPARATOR  = '\\';
 
    String _str;
 
    static void escape(String &dst, char srcSeparator, const char *src, const char *end = nullptr);
 
    static String unescape(char dstSeparator, const char *src, const char *end = nullptr);
 
    static bool canUnescape(bool willBeAtBegin, bool wasAtBegin,
                            const char *begin, const char *end = nullptr);
 
    static inline bool needsEncoding(const char *str, char separator) {
        return str && *str && // String is not empty and
               (separator != SEPARATOR || // separator is not the one we use
                *str == ESCAPE); // or string begins with ESCAPE
    }
 
    static String encode(const char *str, char separator);
 
    Path extract(const char *begin, const char *end = nullptr) const;
 
    size_t findLastSeparator(size_t last = String::npos) const;
 
    template<typename T>
    T reduceComponents(T (*reducer)(T value, const String &element, bool last), T value) const;
 
    bool compareComponents(bool (*comparator)(const String &x, const String &y), const Path &other) const;
 
    inline bool isEscaped() const {
        // c_str() returns a null terminated string, if _str is empty we get \0
        return *_str.c_str() == ESCAPE;
    }
 
    const char *getSuffix(const Common::Path &other) const;
 
public:
    static const char kNoSeparator = '\x00';
 
#if defined(WIN32)
    static const char kNativeSeparator = '\\';
#else
    static const char kNativeSeparator = '/';
#endif
 
    struct IgnoreCaseAndMac_EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equalsIgnoreCaseAndMac(y); }
    };
 
    struct IgnoreCaseAndMac_Hash {
        uint operator()(const Path &x) const { return x.hashIgnoreCaseAndMac(); }
    };
 
    struct IgnoreCase_EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equalsIgnoreCase(y); }
    };
 
    struct IgnoreCase_Hash {
        uint operator()(const Path &x) const { return x.hashIgnoreCase(); }
    };
 
    struct EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equals(y); }
    };
 
    struct Hash {
        uint operator()(const Path &x) const { return x.hash(); }
    };
 
    Path() {}
 
    Path(const Path &path) : _str(path._str) { }
 
    Path(const char *str, char separator = '/') :
        _str(needsEncoding(str, separator) ? encode(str, separator) : str) { }
 
    explicit Path(const String &str, char separator = '/') :
        _str(needsEncoding(str.c_str(), separator) ? encode(str.c_str(), separator) : str) { }
 
    String toString(char separator = '/') const;
 
    void clear() { _str.clear(); }
 
    Path getParent() const;
 
    Path getLastComponent() const;
 
    String baseName() const;
 
    int numComponents() const;
 
    bool operator==(const Path &x) const {
        return _str == x._str;
    }
 
    bool operator!=(const Path &x) const {
        return _str != x._str;
    }
 
    bool equals(const Path &x) const {
        return _str.equals(x._str);
    }
    bool equalsIgnoreCase(const Path &x) const;
    bool equalsIgnoreCaseAndMac(const Path &x) const;
 
    uint hash() const;
    uint hashIgnoreCase() const;
    uint hashIgnoreCaseAndMac() const;
 
    bool operator<(const Path &x) const;
 
    bool empty() const {
        return _str.empty();
    }
 
    Path &operator=(const Path &path) {
        _str = path._str;
        return *this;
    }
 
    Path &operator=(const char *str) {
        set(str);
        return *this;
    }
 
    Path &operator=(const String &str) {
        set(str.c_str());
        return *this;
    }
 
    void set(const char *str, char separator = '/') {
        if (needsEncoding(str, separator)) {
            _str = encode(str, separator);
        } else {
            _str = str;
        }
    }
 
    Path &appendInPlace(const Path &x);
 
    Path &appendInPlace(const String &str, char separator = '/') {
        appendInPlace(str.c_str(), separator);
        return *this;
    }
 
    Path &appendInPlace(const char *str, char separator = '/');
 
    Path &operator+=(const Path &x) {
        return appendInPlace(x);
    }
 
    Path &operator+=(const String &str) {
        return appendInPlace(str);
    }
 
    Path &operator+=(const char *str) {
        return appendInPlace(str);
    }
 
    WARN_UNUSED_RESULT Path append(const Path &x) const {
        Path temp(*this);
        temp.appendInPlace(x);
        return temp;
    }
 
    WARN_UNUSED_RESULT Path append(const String &str, char separator = '/') const {
        return append(str.c_str(), separator);
    }
 
    WARN_UNUSED_RESULT Path append(const char *str, char separator = '/') const {
        Path temp(*this);
        temp.appendInPlace(str, separator);
        return temp;
    }
 
    WARN_UNUSED_RESULT Path appendComponent(const char *str) const;
 
    WARN_UNUSED_RESULT Path appendComponent(const String &x) const {
        return appendComponent(x.c_str());
    }
 
    Path &joinInPlace(const Path &x);
 
    Path &joinInPlace(const String &str, char separator = '/') {
        return joinInPlace(str.c_str(), separator);
    }
 
    Path &joinInPlace(const char *str, char separator = '/');
 
    Path &operator/=(const Path &x) {
        return joinInPlace(x);
    }
 
    Path &operator/=(const String &str) {
        return joinInPlace(str);
    }
 
    Path &operator/=(const char *str) {
        return joinInPlace(str);
    }
 
    WARN_UNUSED_RESULT Path join(const Path &x) const {
        Path temp(*this);
        temp.joinInPlace(x);
        return temp;
    }
 
    WARN_UNUSED_RESULT Path join(const String &str, char separator = '/') const {
        return join(str.c_str(), separator);
    }
 
    WARN_UNUSED_RESULT Path join(const char *str, char separator = '/') const {
        Path temp(*this);
        temp.joinInPlace(str, separator);
        return temp;
    }
 
    WARN_UNUSED_RESULT Path operator/(const Path &x) const {
        return join(x);
    }
 
    WARN_UNUSED_RESULT Path operator/(const String &str) const {
        return join(str);
    }
 
    WARN_UNUSED_RESULT Path operator/(const char *str) const {
        return join(str);
    }
 
    Path &removeTrailingSeparators();
 
    Path &removeExtension(const char *ext = nullptr);
 
    bool isSeparatorTerminated() const { return _str.lastChar() == SEPARATOR; }
 
    bool isRelativeTo(const Common::Path &other) const { return getSuffix(other) != nullptr; }
 
    Path relativeTo(const Common::Path &other) const;
 
    Path punycodeDecode() const;
 
    Path punycodeEncode() const;
 
    bool punycodeNeedsEncode() const;
 
    bool punycodeIsEncoded() const;
 
    void toLowercase() {
        // Escapism is not changed by changing case
        _str.toLowercase();
    }
 
    void toUppercase() {
        // Escapism is not changed by changing case
        _str.toUppercase();
    }
 
    bool matchPattern(const Path &pattern) const;
 
    Path normalize() const;
 
    StringArray splitComponents() const;
 
    static Path joinComponents(StringArray::const_iterator begin, StringArray::const_iterator end);
    static Path joinComponents(const StringArray &c) {
        return joinComponents(c.begin(), c.end());
    }
 
    String toConfig() const;
 
    static Path fromConfig(const String &value);
 
    static Path fromCommandLine(const String &value);
};
 
} // End of namespace Common
 
#endif