====== 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 =====
==== C++ ====
The API for system paths in TerraLib is defined by **FileSystem** class, shown below:
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 listDirectory(const std::string& path);
};
} // end namespace core
} // end namespace te
===== Examples =====
Here is a simple example using the functions provided by **FileSystem** class:
// STL
#include
#include
#include
#include
// TerraLib
#include
#include
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 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;
}
===== Additional References =====
* [[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]]