TerraLib and TerraView Wiki Page

You are here: start » wiki » documentation » devguide » core » files

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
wiki:documentation:devguide:core:files [2016/11/21 08:28]
carolina.santos 		wiki:documentation:devguide:core:files [2016/11/21 08:47] (current)
carolina.santos [TerraLib.Core: FileSystem]
Line 1: Line 1:
 ====== TerraLib.Core:​ FileSystem ====== ====== TerraLib.Core:​ FileSystem ======
  
 +The class **te::​core::​FileSystem** provides support for system paths using UTF-8 strings.
  
 +Performing the encoding conversion using the **[[http://​www.dpi.inpe.br/​terralib5/​wiki/​doku.php?​id=wiki:​documentation:​devguide:​core:​char_encoding | te::​core::​CharEncoding]]** class and using the [[http://​www.boost.org/​doc/​libs/​1_60_0/​libs/​filesystem/​doc/​reference.html | Boost.FileSystem]] functions.
 ===== API ===== ===== API =====
  
 ==== C++ ==== ==== C++ ====
  
-The API for messages translation ​in TerraLib is defined by **Translator** class, shown below:+The API for system paths in TerraLib is defined by **FileSystem** class, shown below:
  
 <code cpp> <code cpp>
 +namespace te
 +{
 +  namespace core
 +  {
 +    /*!
 +      \class FileSystem
  
 +      \brief A class for handling system files and paths using UTF-8 strings.
 +     */
 +    class 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 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 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);
 +
 +    };
 +  }  // end namespace core
 +}  // end namespace te
 </​code>​ </​code>​
  
 ===== Examples ===== ===== Examples =====
  
 +Here is a simple example using the functions provided by **FileSystem** class:
  
 +<code cpp>
 +// STL
 +#include <​string>​
 +#include <​fstream>​
 +#include <​cstdlib>​
 +#include <​iostream>​
 +
 +// TerraLib
 +#include <​terralib/​core/​encoding/​CharEncoding.h>​
 +#include <​terralib/​core/​filesystem/​FileSystem.h>​
 +
 +int main(int argc, char *argv[])
 +{
 +
 +  /* Initialize an utf8 string with a path */
 +  std::string utf8_path =
 +      te::​core::​CharEncoding::​toUTF8("​../​example/​filesystem"​);​
 +
 +  /* Create a directory and make some verifications about the path */
 +  if (te::​core::​FileSystem::​createDirectory(utf8_path))
 +    std::cout << "​Directory created!"​ << std::endl;
 +
 +  if (te::​core::​FileSystem::​exists(utf8_path))
 +    std::cout << "Path exists!"​ << std::endl;
 +
 +  if(te::​core::​FileSystem::​isDirectory(utf8_path))
 +    std::cout << "Path is a directory!"​ << std::endl;
 +
 +  if(te::​core::​FileSystem::​isEmpty(utf8_path))
 +    std::cout << "Path is empty!"​ << std::endl;
 +
 +  /* Creating files to test some functions */
 +  std::string file1_str = utf8_path + "/​file1.txt",​
 +              file2_str = utf8_path + "/​file2.sh",​
 +              file3_str = utf8_path + "/​file3.txt";​
 +  std::​ofstream file1(file1_str);​
 +  std::​ofstream file2(file2_str);​
 +  file1.close();​
 +  file2.close();​
 +
 +  /* Return the file extension */
 +  std::string stringTxt = te::​core::​FileSystem::​extension(file1_str);​
 +  std::cout << "File1 has extension: " << stringTxt << std::endl;
 +  std::string stringSh = te::​core::​FileSystem::​extension(file2_str);​
 +  std::cout << "File1 has extension: " << stringSh << std::endl;
 +
 +  /* Rename and copy files */
 +  te::​core::​FileSystem::​rename(file1_str,​ file3_str);
 +  te::​core::​FileSystem::​copyFile(file3_str,​ file1_str);
 +
 +  /* Check if is a regular file */
 +  if (te::​core::​FileSystem::​isRegularFile(file3_str))
 +    std::cout << "File3 is a regular file!" << std::endl;
 +
 +  /* Create a list with the files in directory, check the list size and remove
 +   * the files */
 +  std::​vector<​std::​string>​ files =
 +      te::​core::​FileSystem::​listDirectory(utf8_path);​
 +
 +  std::cout << "Files size is " << files.size() << std::endl;
 +
 +  for(size_t i = 0; i < files.size();​ ++i)
 +    te::​core::​FileSystem::​remove(files[i]);​
 +
 +  if (te::​core::​FileSystem::​remove(utf8_path))
 +    std::cout << "utf8 path was removed!"​ << std::endl;
 +
 +}
 +</​code>​
  
 ===== Additional References ===== ===== Additional References =====
  
-  * [[http://​www.boost.org/​doc/​libs/​1_56_0/​libs/​locale/​doc/​html/​messages_formatting.html | Boost.Locale - Messages Formatting (Translation)]]+  * [[http://​www.boost.org/​doc/​libs/​1_60_0/​libs/​filesystem/​doc/​reference.html | Boost.FileSystem]] 
 +  * [[http://​www.boost.org/​doc/​libs/​1_60_0/​libs/​locale/​doc/​html/​default_encoding_under_windows.html | Boost.Locale - Default Encoding under Microsoft Windows]] 

Trace: