Path.hpp

#ifndef OPALS_PATH_HPP_INCLUDED
#define OPALS_PATH_HPP_INCLUDED

#include <opals/fwd.hpp>
#include <opals/String.hpp>

namespace opals {

  /**
  \class Path

  \brief A file/directory path

  Internally, all '\\' are replaced by '/'

  \author wk
  \date   02.02.2011

  \internal
  Path encapsulates a boost::filesystem::path using the pimpl-idiom.
  Conversion constructors and operators for boost::filesystem::path are provided.
  boost::filesystems's iterators are not exposed, as that may result in unexpected behaviour
  when used as if Path were a string - convert to a boost::filesystem::path for that purpose (e.g. by calling Path::impl()).
  In addition to boost::filesystem::path's interface, operator+ and operator+= are defined.
  */

  class OPALS_API Path
  {
    class Impl;
    Impl *pimpl_;

  public:
    typedef String::size_type size_type;

    Path();
    Path( const char* );
    Path( const String& );
    Path( const Path& );
    ~Path();

    /// \name assignment operators
    ///@{
    Path& operator= ( const char*   );
    Path& operator= ( const String& );
    Path& operator= ( const Path&   );
    ///}@

    /// \name append a file / directory name
    /// introducing a '/' between the stored path and the directory/filename to append
    ///@{
    Path& operator/= ( const char*   );
    Path& operator/= ( const String& );
    Path& operator/= ( const Path&   );
    ///}@

    /// \name add a string
    /// return a path where a string has been appended to the stored path (not introducing a '/' in between)
    ///@{
    Path  operator+ ( const char*   ) const;
    Path  operator+ ( const String& ) const;
    ///}@

    /// \name append a string
    /// append a string to the stored path (not introducing a '/' in between)
    ///@{
    Path& operator+= ( const char*   );
    Path& operator+= ( const String& );
    ///}@

    /// postcondition: this->empty() is true.
    void clear();
    /// postcondition: For the returned path, is_absolute() is true.
    Path& make_absolute();
    /// Convert the contained pathname to the native format.
    Path& make_preferred();
    /// if has_parent_path() then remove the last filename from the stored path.
    Path& remove_filename();
    /// postcondition: extension() == new_extension (where a leading dot has been removed from replacement, if present)
    Path& replace_extension( const String& new_extension = String() );
    /// swaps the contents of the two paths.
    void swap( Path& );

    /// returns the stored path, formatted according to the operating system rules for regular file pathnames
    const String string() const;

    /// returns the root name (e.g. d:/path/filename.ext -> d:)
    Path root_name() const;
    /// returns the root directory (e.g. d:/path/filename.ext -> /)
    Path root_directory() const;
    /// returns root_name() + root_directory()
    Path root_path() const;

    /// returns the stored path without root_path() (e.g. d:/path/file.ext -> path/file.ext)
    Path        relative_path() const;
    /// returns the parent directory, if any (e.g. d:/path/filename.ext -> d:/path/)
    Path        parent_path() const;

    /// returns the filename (i.e. /path/filename.ext -> filename.ext)
    Path  filename() const;
    /// returns the filename without extension (i.e. /path/filename.ext -> filename)
    String  stem() const;
    /// returns the filename extension (i.e. /path/filename.ext -> .ext)
    String  extension() const;

    /// returns string().empty()
    bool empty() const;
    /// returns !root_name().empty()
    bool has_root_name() const;
    /// returns !root_directory().empty()
    bool has_root_directory() const;
    /// returns !root_path().empty()
    bool has_root_path() const;
    /// returns !relative_path().empty()
    bool has_relative_path() const;
    /// returns !parent_path().empty()
    bool has_parent_path() const;
    /// returns !filename().empty()
    bool has_filename() const;
    /// returns !stem().empty()
    bool has_stem() const;
    /// returns !extension().empty()
    bool has_extension() const;
    /// returns true if the elements of root_path() uniquely identify a directory, else false
    bool is_absolute() const;
    /// returns !is_absolute()
    bool is_relative() const;

    /// Replace symlinks, replace '/' with '\', replace "foo/../bar" with "bar", etc.
    Path &normalize();

    /// shorten path to length, e.g. d:/foo_long_directory_name/bar.txt -> d:/foo.../bar.txt
    String compressed( size_type length ) const;

  };

  /// \relatesalso Path
  void OPALS_API swap( Path&, Path& );
  /// \relatesalso Path
  Path OPALS_API operator/(const Path&   lhs, const Path&   rhs );
  /// \relatesalso Path
  Path OPALS_API operator/(const Path&   lhs, const char*   rhs );
  /// \relatesalso Path
  Path OPALS_API operator/(const char*   lhs, const Path&   rhs );
  /// \relatesalso Path
  Path OPALS_API operator/(const Path&   lhs, const String& rhs );
  /// \relatesalso Path
  Path OPALS_API operator/(const String& lhs, const Path&   rhs );

  /// \relatesalso Path
  bool OPALS_API operator< ( const Path&  , const Path&   );

  /// \relatesalso Path
  bool OPALS_API operator<=( const Path&  , const Path&   );

  /// \relatesalso Path
  bool OPALS_API operator> ( const Path&  , const Path&   );

  /// \relatesalso Path
  bool OPALS_API operator>=( const Path&  , const Path&   );

  /// \relatesalso Path
  bool OPALS_API operator==( const Path&  , const Path&   );
  /// \relatesalso Path
  bool OPALS_API operator==( const Path&  , const String&   );
  /// \relatesalso Path
  bool OPALS_API operator==( const String&  , const Path&   );
  /// \relatesalso Path
  bool OPALS_API operator==( const Path&  , const char *   );
  /// \relatesalso Path
  bool OPALS_API operator==( const char *  , const Path&   );

  /// \relatesalso Path
  bool OPALS_API operator!=( const Path&  , const Path&   );
  /// \relatesalso Path
  bool OPALS_API operator!=( const Path&  , const String&   );
  /// \relatesalso Path
  bool OPALS_API operator!=( const String&  , const Path&   );
  /// \relatesalso Path
  bool OPALS_API operator!=( const Path&  , const char *   );
  /// \relatesalso Path
  bool OPALS_API operator!=( const char *  , const Path&   );

};

#endif