FileSystem.h

Go to the documentation of this file.

/*
  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.

  This file is part of the TerraLib - a Framework for building GIS enabled
  applications.

  TerraLib is free software: you can redistribute it and/or modify
  it under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation, either version 3 of the License,
  or (at your option) any later version.

  TerraLib 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 Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with TerraLib. See COPYING. If not, write to
  TerraLib Team at <terralib-team@terralib.org>.
 */

/*!
  \file terralib/core/filesystem/FileSystem.h

  \brief A class for handling system files and paths.

  \author Matheus Cavassan Zaglia
*/

#ifndef __TERRALIB_CORE_FILESYSTEM_FILESYSTEM_H__
#define __TERRALIB_CORE_FILESYSTEM_FILESYSTEM_H__

// TerraLib
#include "../Config.h"

// STL
#include <string>
#include <vector>
#include <cstdint>

// boost 
#include <boost/thread/mutex.hpp>

namespace te
{
  namespace core
  {
    /*!
      \class FileSystem

      \brief A class for handling system files and paths using UTF-8 strings.
     */
    class TECOREEXPORT FileSystem
    {
      public:

        /*!
          \brief Retrives the current working directory path in UTF-8.

          \return String in UTF-8 for the current working directory path.
         */
        static std::string currentPath();

        /*!
          \brief Composes an absolute path for the given path in UTF-8.

          \param path Path in UTF-8.

          \return String in UTF-8 for the composed path.
         */
        static std::string systemCompletePath(const std::string& path);

        /*!
          \brief Retrives the temp directory in UTF-8.

          \return String in UTF-8 for temp directory.
         */
        static std::string tempDirectoryPath();

        /*!
          \brief Retrives an unique path generated by a given format.

          \param format The format used to create a unique path.
          e.g.: "%%%%-%%%%-%%%%-%%%%"

          \return String in UTF-8 for the generated unique path.
         */
        static std::string uniquePath(
            const std::string& format = "%%%%-%%%%-%%%%-%%%%");

        /*!
          \brief Retrives the absolute path for the given path in UTF-8.

          \param path Path in UTF-8.

          \return String in UTF-8 for the absolute path.
         */
        static std::string absolutePath(const std::string& path);

        /*!
          \brief Retrives the extension of a given file path in UTF-8.

          \param path File path in UTF-8.

          \return String in UTF-8 for the extension.
         */
        static std::string extension(const std::string& path);

        /*!
          \brief Retrives the filename of a given file path in UTF-8, including extension.

          \param path File path in UTF-8.

          \return String in UTF-8 for the name of the file, including the extension.
         */
        static std::string fileName(const std::string& path);

        /*!
          \brief Retrives the filename of a given file path in UTF-8, excluding extension.

          \param path File path in UTF-8.

          \return String in UTF-8 for the name of the file, excluding the extension.
         */
        static std::string stem(const std::string& path);

        /*!
          \brief Retrives the parent path of a given file path in UTF-8. For /home/files/fileName.shp, it will return /home/files

          \param path File path in UTF-8.

          \return String in UTF-8 for the parent path of the give file path.
         */
        static std::string parentPath(const std::string& path);

        /*!
          \brief Checks if a given path in UTF-8 is a directory.

          \param path Path in UTF-8.

          \return true if is a directory, otherwise false.
         */
        static bool isDirectory(const std::string& path);

        /*!
          \brief Checks if a given path in UTF-8 is an empty directory.

          \param path Path in UTF-8.

          \return true if is a empty directory, otherwise false.
         */
        static bool isEmpty(const std::string& path);
        /*!
          \brief Checks if a given path in UTF-8 is a regular file.

          \param path File path in UTF-8.

          \return true if is a regular file, otherwise false.
         */
        static bool isRegularFile(const std::string& path);

        /*
         \brief Returns the full directory to the currently running executable,
          or an empty string in case of failure.

         \return String in UTF-8 of the running executable
        */
        static std::string executableDirectory();

        /*!
          \brief Checks if a given path in UTF-8 exists.

          \param path Path in UTF-8.

          \return true if exists, otherwise false.
         */
        static bool exists(const std::string& path);

        /*!
          \brief Creates a directory from a given path in UTF-8.

          \param path Path in UTF-8.

          \return true if a new directory was created, otherwise false.
         */
        static bool createDirectory(const std::string& path);

        /*!
          \brief Creates a directory for any element of path that does not
          exist.
          \param path Path in UTF-8.

          \return true if a new directory was created, otherwise false.
         */
        static bool createDirectories(const std::string& path);

        /*!
          \brief Copies a file

          \param from Path in UTF-8 for the file to be copied.
          \param to Path in UTF-8 for the copy output.

         */
        static void copyFile(const std::string& from, const std::string& to);

        /*!
          \brief Removes a file or directory from a given path in UTF-8.

          \note This function will not remove if the directory is not empty.

          \param path Path in UTF-8.

          \return false if path did not exist in the first place, otherwise
          true.
         */
        static bool remove(const std::string& path);

        /*!
          \brief Renames a file or directory from a given path in UTF-8.

          \param old_p Old name in UTF-8.
          \param new_p New name in UTF-8.
         */
        static void rename(const std::string& old_p, const std::string& new_p);

        /*!
          \brief Lists a directory from a given path in UTF-8.

          \param path Path in UTF-8.

          \return Vector of strings in UTF-8 for directory content.
         */
        static std::vector<std::string> listDirectory(const std::string& path);

        /*!
          \brief Returns the file size of a FILE in UTF-8.

          \param path Path in UTF-8.

          \return File size.

          \exception te::core::Exception if the given path doesn't exists or its
          used in a directory.
         */
        static uintmax_t fileSize(const std::string& path);

        /*!
          \brief Adjusts the given path to native form
          
          \description Documentation from Boost: 
                       In general, Boost.Filesystem differentiates between native paths and generic paths. 
                       Native paths are operating system specific and must be used when calling operating system functions. 
                       Generic paths are portable and independent of the operating system.
        */
        static std::string adjustPathToNativeForm(const std::string& filePath);

        /*!
          \brief Adjusts the given path to generic form

          \description Documentation from Boost: 
                       In general, Boost.Filesystem differentiates between native paths and generic paths.
                       Native paths are operating system specific and must be used when calling operating system functions.
                       Generic paths are portable and independent of the operating system.
        */
        static std::string adjustPathToGenericForm(const std::string& filePath);

        /*!
          \brief Returns the native separator based on the Operational System
          */
        static std::string getNativeSeparator();

        /*!
          \brief Read file and returns the contents of the file.

          \description Read file, in case of corruption use the copy. Returns the contents of the file.
        */
        static std::string readFromFile(const std::string& filePath);

        /*!
          \brief will create a copy of the file before saving. 
                
          \description In the write to file, this method will create a copy of the file before saving. 
                       If it gets corrupted in the process, when using the read from file method will replace 
                       the corrupted file with the copy.
        */
        static void writeToFile(const std::string& filePath, const std::string& content);

       private:
        // Not instantiable
        FileSystem();
        ~FileSystem();
// No copy allowed
        FileSystem(FileSystem const&);
        FileSystem& operator=(FileSystem const&);

        static std::string createTempFilePathString(const std::string& filePath);

        static std::string createTempFileDirectoryPathString();

        /*!
          \brief Get file content.

          \param file path
        */
        static std::string getFileContent(const std::string& filePath);

        /*!
          \brief Checks whether the file contains full non-printable character content.

          \param file path
        */
        static bool isBlank(const std::string& filePath);

        /*!
          \brief Checks whether the contents contains full non-printable character content.

          \param file path
        */
        static bool isInvalid(const std::string& content);

       private:

        static boost::mutex mutexFileSystem; //!< Used to perform the tasks: write to file or read from file.

    };
  }  // end namespace core
}  // end namespace te

#endif  //__TERRALIB_CORE_FILESYSTEM_FILESYSTEM_H__