2416 lines
78 KiB
C++
2416 lines
78 KiB
C++
// ____ ______ __
|
|
// / __ \ / ____// /
|
|
// / /_/ // / / /
|
|
// / ____// /___ / /___ PixInsight Class Library
|
|
// /_/ \____//_____/ PCL 2.4.23
|
|
// ----------------------------------------------------------------------------
|
|
// pcl/File.h - Released 2022-03-12T18:59:29Z
|
|
// ----------------------------------------------------------------------------
|
|
// This file is part of the PixInsight Class Library (PCL).
|
|
// PCL is a multiplatform C++ framework for development of PixInsight modules.
|
|
//
|
|
// Copyright (c) 2003-2022 Pleiades Astrophoto S.L. All Rights Reserved.
|
|
//
|
|
// Redistribution and use in both source and binary forms, with or without
|
|
// modification, is permitted provided that the following conditions are met:
|
|
//
|
|
// 1. All redistributions of source code must retain the above copyright
|
|
// notice, this list of conditions and the following disclaimer.
|
|
//
|
|
// 2. All redistributions in binary form must reproduce the above copyright
|
|
// notice, this list of conditions and the following disclaimer in the
|
|
// documentation and/or other materials provided with the distribution.
|
|
//
|
|
// 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
|
|
// of their contributors, may be used to endorse or promote products derived
|
|
// from this software without specific prior written permission. For written
|
|
// permission, please contact info@pixinsight.com.
|
|
//
|
|
// 4. All products derived from this software, in any form whatsoever, must
|
|
// reproduce the following acknowledgment in the end-user documentation
|
|
// and/or other materials provided with the product:
|
|
//
|
|
// "This product is based on software from the PixInsight project, developed
|
|
// by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
|
|
//
|
|
// Alternatively, if that is where third-party acknowledgments normally
|
|
// appear, this acknowledgment must be reproduced in the product itself.
|
|
//
|
|
// THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
|
|
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
|
|
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
// EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
|
|
// INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
|
|
// DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
// POSSIBILITY OF SUCH DAMAGE.
|
|
// ----------------------------------------------------------------------------
|
|
|
|
#ifndef __PCL_File_h
|
|
#define __PCL_File_h
|
|
|
|
/// \file pcl/File.h
|
|
|
|
#include <pcl/Defs.h>
|
|
#include <pcl/Diagnostics.h>
|
|
|
|
#include <pcl/ByteArray.h>
|
|
#include <pcl/Exception.h>
|
|
#include <pcl/Flags.h>
|
|
#include <pcl/StringList.h>
|
|
|
|
#ifndef __PCL_FILE_DONT_REMOVE_PREVIOUS_DECLARATION
|
|
|
|
/*
|
|
* Remove conflicting identifiers from Win32 SDK headers.
|
|
*/
|
|
|
|
#ifdef CreateFile
|
|
#undef CreateFile
|
|
#endif
|
|
|
|
#ifdef CopyFile
|
|
#undef CopyFile
|
|
#endif
|
|
|
|
#ifdef MoveFile
|
|
#undef MoveFile
|
|
#endif
|
|
|
|
#ifdef CreateDirectory
|
|
#undef CreateDirectory
|
|
#endif
|
|
|
|
#ifdef RemoveDirectory
|
|
#undef RemoveDirectory
|
|
#endif
|
|
|
|
#endif // !__PCL_FILE_DONT_REMOVE_PREVIOUS_DECLARATION
|
|
|
|
namespace pcl
|
|
{
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \defgroup file_utilities File Support Classes and Functions
|
|
*/
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \namespace pcl::FileMode
|
|
* \brief File access, share and opening/creation modes.
|
|
*
|
|
* <table border="1" cellpadding="4" cellspacing="0">
|
|
* <tr><td>FileMode::Read</td> <td>Read access enabled</td></tr>
|
|
* <tr><td>FileMode::Write</td> <td>Write access enabled</td></tr>
|
|
* <tr><td>FileMode::AccessMode</td> <td>Mask to isolate read/write flags</td></tr>
|
|
* <tr><td>FileMode::ShareRead</td> <td>(Windows only) Sharing for reading enabled</td></tr>
|
|
* <tr><td>FileMode::ShareWrite</td> <td>(Windows only) Sharing for writing enabled</td></tr>
|
|
* <tr><td>FileMode::ShareMode</td> <td>(Windows only) Mask to isolate share read/write flags</td></tr>
|
|
* <tr><td>FileMode::Open</td> <td>Open an existing file</td></tr>
|
|
* <tr><td>FileMode::Create</td> <td>Create a new file or truncate an existing file</td></tr>
|
|
* <tr><td>FileMode::OpenMode</td> <td>Mask to isolate open/creation flags</td></tr>
|
|
* </table>
|
|
*
|
|
* \ingroup file_utilities
|
|
*/
|
|
namespace FileMode
|
|
{
|
|
enum mask_type
|
|
{
|
|
Zero = 0x00000000,
|
|
|
|
/*
|
|
* Access mode
|
|
*/
|
|
Read = 0x00000001,
|
|
Write = 0x00000002,
|
|
AccessMode = 0x0000000F,
|
|
|
|
/*
|
|
* Share mode (Windows only)
|
|
*/
|
|
ShareRead = 0x00000010,
|
|
ShareWrite = 0x00000020,
|
|
ShareMode = 0x000000F0,
|
|
|
|
/*
|
|
* Open/create mode
|
|
*/
|
|
Open = 0x00000100,
|
|
Create = 0x00000200,
|
|
OpenMode = 0x00000F00
|
|
};
|
|
}
|
|
|
|
/*!
|
|
* \class pcl::FileModes
|
|
* \brief A combination of file access, share and opening/creation mode flags
|
|
* \ingroup file_utilities
|
|
*/
|
|
typedef Flags<FileMode::mask_type> FileModes;
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \namespace pcl::SeekMode
|
|
* \brief File seek modes.
|
|
*
|
|
* <table border="1" cellpadding="4" cellspacing="0">
|
|
* <tr><td>SeekMode::FromBegin</td> <td>Move file pointer relative to the beginning of the file</td></tr>
|
|
* <tr><td>SeekMode::FromCurrent</td> <td>Move file pointer from the current position</td></tr>
|
|
* <tr><td>SeekMode::FromEnd</td> <td>Move file pointer relative to the end of the file</td></tr>
|
|
* </table>
|
|
*
|
|
* \ingroup file_utilities
|
|
*/
|
|
namespace SeekMode
|
|
{
|
|
enum value_type
|
|
{
|
|
FromBegin, // Move relative to the beginning of the file
|
|
FromCurrent, // Move from current position
|
|
FromEnd, // Move relative to the end of the file
|
|
NumberOfSeekModes
|
|
};
|
|
}
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \namespace pcl::FileAttribute
|
|
* \brief File attributes
|
|
*
|
|
* <table border="1" cellpadding="4" cellspacing="0">
|
|
* <tr><td colspan="2"><b>File type</b></td></tr>
|
|
* <tr><td>FileAttribute::Block</td> <td>Block special</td></tr>
|
|
* <tr><td>FileAttribute::Character</td> <td>Character special</td></tr>
|
|
* <tr><td>FileAttribute::FIFO</td> <td>FIFO special</td></tr>
|
|
* <tr><td>FileAttribute::Regular</td> <td>Regular file</td></tr>
|
|
* <tr><td>FileAttribute::Directory</td> <td>Directory</td></tr>
|
|
* <tr><td>FileAttribute::SymbolicLink</td> <td>Symbolic link</td></tr>
|
|
* <tr><td>FileAttribute::Socket</td> <td>Socket</td></tr>
|
|
* <tr><td>FileAttribute::FileType</td> <td>Mask to isolate file type flags</td></tr>
|
|
* <tr><td colspan="2"><b>File attributes</b>\n
|
|
* <em>These are Windows-exclusive, except ReadOnly and Hidden, which we emulate on UNIX and Linux platforms.</em></td></tr>
|
|
* <tr><td>FileAttribute::Archive</td> <td>File is archived</td></tr>
|
|
* <tr><td>FileAttribute::Compressed</td> <td>File is compressed</td></tr>
|
|
* <tr><td>FileAttribute::Encrypted</td> <td>File is encrypted</td></tr>
|
|
* <tr><td>FileAttribute::Hidden</td> <td>File is hidden</td></tr>
|
|
* <tr><td>FileAttribute::ReadOnly</td> <td>File is read-only</td></tr>
|
|
* <tr><td>FileAttribute::System</td> <td>File is a system file</td></tr>
|
|
* <tr><td>FileAttribute::Temporary</td> <td>File is a temporary file</td></tr>
|
|
* <tr><td>FileAttribute::FileAttributes</td> <td>Mask to isolate file attributes flags</td></tr>
|
|
* <tr><td colspan="2"><b>File permissions</b></td></tr>
|
|
* <tr><td>FileAttribute::Read</td> <td>Owner can read</td></tr>
|
|
* <tr><td>FileAttribute::Write</td> <td>Owner can write</td></tr>
|
|
* <tr><td>FileAttribute::Execute</td> <td>Owner can execute/search</td></tr>
|
|
* <tr><td>FileAttribute::ReadGroup</td> <td>Group can read</td></tr>
|
|
* <tr><td>FileAttribute::WriteGroup</td> <td>Group can write</td></tr>
|
|
* <tr><td>FileAttribute::ExecuteGroup</td> <td>Group can execute/search</td></tr>
|
|
* <tr><td>FileAttribute::ReadOthers</td> <td>Others can read</td></tr>
|
|
* <tr><td>FileAttribute::WriteOthers</td> <td>Others can write</td></tr>
|
|
* <tr><td>FileAttribute::ExecuteOthers</td> <td>Others can execute/search</td></tr>
|
|
* <tr><td>FileAttribute::FilePermissions</td> <td>Mask to isolate file permission flags</td></tr>
|
|
* </table>
|
|
*
|
|
* \ingroup file_utilities
|
|
*/
|
|
namespace FileAttribute
|
|
{
|
|
enum mask_type
|
|
{
|
|
/*
|
|
* File type.
|
|
*/
|
|
Block = 0x00000001, // Block special
|
|
Character = 0x00000002, // Character special
|
|
FIFO = 0x00000004, // FIFO special
|
|
Regular = 0x00000008, // Regular file
|
|
Directory = 0x00000010, // Directory
|
|
SymbolicLink = 0x00000020, // Symbolic link
|
|
Socket = 0x00000040, // Socket
|
|
FileType = 0x000000FF,
|
|
|
|
/*
|
|
* File attributes.
|
|
* These are Windows-exclusive, except ReadOnly and Hidden, which we
|
|
* emulate on UNIX and Linux.
|
|
*/
|
|
Archive = 0x00001000, // File is archived
|
|
Compressed = 0x00002000, // File is compressed
|
|
Encrypted = 0x00004000, // File is encrypted
|
|
Hidden = 0x00008000, // File is hidden
|
|
ReadOnly = 0x00010000, // File is read-only
|
|
System = 0x00020000, // File is a system file
|
|
Temporary = 0x00040000, // File is a temporary file
|
|
FileAttributes = 0x000FF000,
|
|
|
|
/*
|
|
* File permissions.
|
|
*/
|
|
Read = 0x00100000, // Owner can read
|
|
Write = 0x00200000, // Owner can write
|
|
Execute = 0x00400000, // Owner can execute/search
|
|
ReadGroup = 0x01000000, // Group can read
|
|
WriteGroup = 0x02000000, // Group can write
|
|
ExecuteGroup = 0x04000000, // Group can execute/search
|
|
ReadOthers = 0x10000000, // Others can read
|
|
WriteOthers = 0x20000000, // Others can write
|
|
ExecuteOthers = 0x40000000, // Others can execute/search
|
|
FilePermissions= 0xFFF00000
|
|
};
|
|
}
|
|
|
|
/*!
|
|
* \class pcl::FileAttributes
|
|
* \brief A combination of file type, attribute and access mode flags
|
|
* \ingroup file_utilities
|
|
*/
|
|
typedef Flags<FileAttribute::mask_type> FileAttributes;
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \struct FileTime
|
|
* \brief File date and time
|
|
*
|
|
* %FileTime is used to represent the creation, last access and last
|
|
* modification times of a file or directory. On most file systems, this object
|
|
* represents a time point in the Coordinated Universal Time (UTC) time scale.
|
|
* \ingroup file_utilities
|
|
*/
|
|
struct FileTime
|
|
{
|
|
uint16 year : 16; //!< Year
|
|
uint8 month : 4; //!< Month [1,12]
|
|
uint8 day : 5; //!< Day [1,31]
|
|
uint8 hour : 5; //!< Hour [0,23]
|
|
int : 2;
|
|
uint8 minute : 6; //!< Minute [0,59]
|
|
uint8 second : 6; //!< Second [0,59]
|
|
int : 4;
|
|
uint16 milliseconds : 10; //!< Milliseconds [0,999]
|
|
int : 6;
|
|
|
|
/*!
|
|
* Returns true iff this file time is equal to another object \a t.
|
|
*/
|
|
bool operator ==( const FileTime& t ) const
|
|
{
|
|
return second == t.second && minute == t.minute && hour == t.hour &&
|
|
day == t.day && month == t.month && year == t.year &&
|
|
milliseconds == t.milliseconds;
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this file time precedes another object \a t.
|
|
*/
|
|
bool operator <( const FileTime& t ) const
|
|
{
|
|
if ( year != t.year ) return year < t.year;
|
|
if ( month != t.month ) return month < t.month;
|
|
if ( day != t.day ) return day < t.day;
|
|
if ( hour != t.hour ) return hour < t.hour;
|
|
if ( minute != t.minute ) return minute < t.minute;
|
|
if ( second != t.second ) return second < t.second;
|
|
if ( milliseconds != t.milliseconds ) return milliseconds < t.milliseconds;
|
|
return false;
|
|
}
|
|
|
|
/*!
|
|
* Returns this file date and time as a Julian day number. The returned
|
|
* value represents a time point in the UTC time scale on most file systems.
|
|
*/
|
|
double ToJD() const;
|
|
|
|
/*!
|
|
* Returns the elapsed time in days since the standard UNIX epoch (1970
|
|
* January 1.0 UTC).
|
|
*/
|
|
double DaysSinceEpoch() const
|
|
{
|
|
return ToJD() - 2440587.5;
|
|
}
|
|
|
|
/*!
|
|
* Returns the elapsed time in seconds since the standard UNIX epoch (1970
|
|
* January 1.0 UTC).
|
|
*/
|
|
double SecondsSinceEpoch() const
|
|
{
|
|
return 86400*DaysSinceEpoch();
|
|
}
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \struct FindFileInfo
|
|
* \brief %File information structure used by File::Find
|
|
* \ingroup file_utilities
|
|
* \sa pcl::File::Find
|
|
*/
|
|
struct FindFileInfo
|
|
{
|
|
String name; //!< File or directory name, including the file name extension.
|
|
FileAttributes attributes; //!< Item attributes.
|
|
fsize_type size; //!< File size in bytes.
|
|
int numberOfLinks; //!< Number of existing hard links to this file.
|
|
int userId; //!< User id of the file owner.
|
|
int groupId; //!< Group id of the file owner.
|
|
FileTime created; //!< Creation time.
|
|
FileTime lastAccessed; //!< Time of last access.
|
|
FileTime lastModified; //!< Time of last change.
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a directory.
|
|
*/
|
|
bool IsDirectory() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Directory );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::Archive attribute set.
|
|
*/
|
|
bool IsArchive() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Archive );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::Compressed attribute set.
|
|
*/
|
|
bool IsCompressed() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Compressed );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::Encrypted attribute set.
|
|
*/
|
|
bool IsEncrypted() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Encrypted );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::Hidden attribute set.
|
|
*/
|
|
bool IsHidden() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Hidden );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::ReadOnly attribute set.
|
|
*/
|
|
bool IsReadOnly() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::ReadOnly );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::System attribute set.
|
|
*/
|
|
bool IsSystem() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::System );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to a file with the
|
|
* FileAttribute::Temporary attribute set.
|
|
*/
|
|
bool IsTemporary() const
|
|
{
|
|
return attributes.IsFlagSet( FileAttribute::Temporary );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this %FindFileInfo structure corresponds to an empty file.
|
|
*/
|
|
bool IsEmpty() const
|
|
{
|
|
return size == 0;
|
|
}
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \namespace pcl::ReadTextOption
|
|
* \brief File text reading options.
|
|
*
|
|
* <table border="1" cellpadding="4" cellspacing="0">
|
|
* <tr><td>RemoveEmptyLines</td> <td>Discard empty text lines (after trimming whitespace, when applicable).</td></tr>
|
|
* <tr><td>TrimTrailingSpaces</td> <td>Delete trailing whitespace characters from input text lines.</td></tr>
|
|
* <tr><td>TrimLeadingSpaces</td> <td>Delete leading whitespace characters from input text lines.</td></tr>
|
|
* <tr><td>TrimSpaces</td> <td>Delete both leading and trailing whitespace characters from input text lines.</td></tr>
|
|
* </table>
|
|
*
|
|
* \ingroup file_utilities
|
|
* \sa File::ReadLines(), File::ScanLines()
|
|
*/
|
|
namespace ReadTextOption
|
|
{
|
|
enum mask_type
|
|
{
|
|
RemoveEmptyLines = 0x0001,
|
|
TrimTrailingSpaces = 0x0002,
|
|
TrimLeadingSpaces = 0x0004,
|
|
TrimSpaces = TrimTrailingSpaces | TrimLeadingSpaces
|
|
};
|
|
}
|
|
|
|
/*!
|
|
* \class pcl::ReadTextOptions
|
|
* \brief A combination of file text reading mode flags
|
|
* \ingroup file_utilities
|
|
* \sa File::ReadLines(), File::ScanLines()
|
|
*/
|
|
typedef Flags<ReadTextOption::mask_type> ReadTextOptions;
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \struct UniqueFileChecks
|
|
* \brief A simple POD structure to hold file uniqueness and overwrite
|
|
* verification results.
|
|
* \ingroup file_utilities
|
|
* \sa File::EnsureNewUniqueFilePath()
|
|
*/
|
|
struct UniqueFileChecks
|
|
{
|
|
bool exists = false;
|
|
bool overwrite = false;
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* \class File
|
|
* \brief A platform-independent interface to the local file system
|
|
*
|
|
* ### TODO: Write a detailed description for %File.
|
|
*
|
|
* \ingroup file_utilities
|
|
*/
|
|
class PCL_CLASS File
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
* Represents a low-level opaque handle to a file.
|
|
*/
|
|
typedef void* handle;
|
|
|
|
/*!
|
|
* Represents a file seek mode.
|
|
*/
|
|
typedef SeekMode::value_type seek_mode;
|
|
|
|
/*!
|
|
* \class pcl::File::Error
|
|
* \brief File I/O exception
|
|
* \ingroup file_utilities
|
|
*/
|
|
class PCL_CLASS Error : public pcl::Error
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
* Constructs a %File::Error object with the specified full file
|
|
* \a path and error \a message.
|
|
*/
|
|
Error( const String& filePath, const String& message )
|
|
: pcl::Error( message )
|
|
, m_filePath( filePath )
|
|
{
|
|
}
|
|
|
|
/*!
|
|
* Copy constructor.
|
|
*/
|
|
Error( const Error& ) = default;
|
|
|
|
/*!
|
|
*/
|
|
String ExceptionClass() const override
|
|
{
|
|
return "File I/O Error";
|
|
}
|
|
|
|
/*!
|
|
* Returns the full file path associated to this file error.
|
|
*/
|
|
virtual String FilePath() const
|
|
{
|
|
return m_filePath;
|
|
}
|
|
|
|
/*!
|
|
*/
|
|
virtual String ErrorMessage() const
|
|
{
|
|
return m_message;
|
|
}
|
|
|
|
/*!
|
|
*/
|
|
String Message() const override
|
|
{
|
|
String filePath = FilePath();
|
|
String message = m_message;
|
|
if ( !filePath.IsEmpty() )
|
|
{
|
|
message += ": ";
|
|
message += filePath;
|
|
}
|
|
return message;
|
|
}
|
|
|
|
private:
|
|
|
|
String m_filePath;
|
|
};
|
|
|
|
/*!
|
|
* \class pcl::File::Find
|
|
* \brief Directory search operation
|
|
*
|
|
* This class can be used as an iterator to find all files and
|
|
* subdirectories within a directory tree.
|
|
*
|
|
* In the following example, the ProcessFiles function calls a functor
|
|
* object, specified as the \a processFile function argument, for each file
|
|
* found recursively in the specified \a dirPath directory. The functor's
|
|
* unique argument is the absolute file path of an existing file.
|
|
*
|
|
* \code
|
|
* template <class F>
|
|
* void ProcessFiles( const String& dirPath, F processFile )
|
|
* {
|
|
* StringList directories;
|
|
* pcl::FindFileInfo info;
|
|
* for ( File::Find f( dirPath + '/' + '*' ); f.NextItem( info ); )
|
|
* if ( info.IsDirectory() )
|
|
* {
|
|
* if ( info.name != "." && info.name != ".." )
|
|
* directories << info.name;
|
|
* }
|
|
* else if ( !info.attributes.IsFlagSet( FileAttribute::SymbolicLink ) )
|
|
* {
|
|
* processFile( File::FullPath( dirPath + '/' + info.name ) );
|
|
* }
|
|
* for ( const String& dir : directories )
|
|
* ProcessFiles( dirPath + '/' + dir );
|
|
* }
|
|
* \endcode
|
|
*
|
|
* \ingroup file_utilities
|
|
* \sa FindFileInfo
|
|
*/
|
|
class PCL_CLASS Find
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
* Constructs an inactive %File::Find object.
|
|
*/
|
|
Find() = default;
|
|
|
|
/*!
|
|
* Constructs a %File::Find object and starts a new directory search
|
|
* operation for the specified \a path.
|
|
*
|
|
* The specified \a path can include wildcards to define a pattern to
|
|
* search for a set of directory items.
|
|
*/
|
|
Find( const String& path )
|
|
{
|
|
Begin( path );
|
|
}
|
|
|
|
/*!
|
|
* Destroys a %File::Find object. If a directory search operation is
|
|
* currently active, it is finalized.
|
|
*/
|
|
~Find()
|
|
{
|
|
End();
|
|
}
|
|
|
|
/*!
|
|
* Copy constructor. This constructor is disabled because %File::Find
|
|
* instances are unique.
|
|
*/
|
|
Find( const Find& ) = delete;
|
|
|
|
/*!
|
|
* Copy assignment. This operator is disabled because %File::Find
|
|
* instances are unique.
|
|
*/
|
|
Find& operator =( const Find& ) = delete;
|
|
|
|
/*!
|
|
* Starts a new directory search operation for the specified \a path.
|
|
*
|
|
* The specified \a path can include wildcards to define a pattern to
|
|
* search for a set of directory items.
|
|
*/
|
|
void Begin( const String& path );
|
|
|
|
/*!
|
|
* Attempts to retrieve the next item in the current directory search
|
|
* operation.
|
|
*
|
|
* Returns true if a new item has been retrieved. In such case the
|
|
* \a info structure receives the data corresponding to the retrieved
|
|
* item. Returns false if there are no more items available, signaling
|
|
* the end of the current directory search operation, or if a search
|
|
* operation has not been initiated by a previous call to Begin(). In
|
|
* such case the \a info structure is not modified.
|
|
*/
|
|
bool NextItem( FindFileInfo& info );
|
|
|
|
/*!
|
|
* Finalizes the current directory search operation, if there is one
|
|
* active.
|
|
*/
|
|
void End();
|
|
|
|
/*!
|
|
* Returns the search path of the current directory search operation.
|
|
*/
|
|
String SearchPath() const
|
|
{
|
|
return m_searchPath;
|
|
}
|
|
|
|
private:
|
|
|
|
FindFileInfo m_info;
|
|
String m_searchPath;
|
|
#ifndef __PCL_WINDOWS
|
|
String m_searchDir;
|
|
String m_searchName;
|
|
#endif
|
|
void* m_handle = nullptr;
|
|
};
|
|
|
|
/*!
|
|
* \class pcl::File::Progress
|
|
* \brief Abstract base class of file progress objects
|
|
*
|
|
* The purpose of a file progress object is to provide feedback to the user
|
|
* during potentially long file tasks, such as copying, moving and deleting
|
|
* large files or file sets. The %File::Progress class provides a simple
|
|
* template with a text line, an increasing counter, and the possibility to
|
|
* abort a long operation.
|
|
*
|
|
* \ingroup file_utilities
|
|
* \sa File::CopyFile(), File::MoveFile()
|
|
*/
|
|
class PCL_CLASS Progress
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
* Constructs a %File::Progress object.
|
|
*
|
|
* \param total Total progress count (for example, the total size
|
|
* in bytes of a file being copied, or the total
|
|
* number of files being deleted).
|
|
*
|
|
* \param initialText Initial progress text. The default value is an
|
|
* empty string.
|
|
*
|
|
* \param initialValue Initial progress value. The default value is
|
|
* zero.
|
|
*/
|
|
Progress( fsize_type total, const String& initialText = String(), fsize_type initialValue = 0 )
|
|
: m_total( Max( fsize_type( 0 ), total ) )
|
|
, m_current( Range( initialValue, fsize_type( 0 ), m_total ) )
|
|
, m_text( initialText )
|
|
{
|
|
}
|
|
|
|
/*!
|
|
* Destroys a %File::Progress object.
|
|
*/
|
|
virtual ~Progress()
|
|
{
|
|
}
|
|
|
|
/*!
|
|
* Returns the total progress count.
|
|
*/
|
|
fsize_type Total() const
|
|
{
|
|
return m_total;
|
|
}
|
|
|
|
/*!
|
|
* Returns the current progress count.
|
|
*/
|
|
fsize_type Value() const
|
|
{
|
|
return m_current;
|
|
}
|
|
|
|
/*!
|
|
* Returns the current progress text.
|
|
*/
|
|
const String& Text() const
|
|
{
|
|
return m_text;
|
|
}
|
|
|
|
/*!
|
|
* Sets the \a current progress count.
|
|
*
|
|
* This member function can abort the ongoing task. In such case, a
|
|
* ProcessAborted exception is thrown and the IsAborted() member function
|
|
* returns true.
|
|
*/
|
|
void SetValue( fsize_type current )
|
|
{
|
|
if ( current >= m_current )
|
|
{
|
|
m_current = current;
|
|
|
|
if ( !ValueChanged() )
|
|
{
|
|
m_abort = true;
|
|
throw ProcessAborted();
|
|
}
|
|
}
|
|
}
|
|
|
|
/*!
|
|
* Adds \a delta items to the current progress count.
|
|
*
|
|
* This member function can abort the ongoing task. In such case, a
|
|
* ProcessAborted exception is thrown and the IsAborted() member function
|
|
* returns true.
|
|
*/
|
|
void Add( fsize_type delta )
|
|
{
|
|
if ( delta >= 0 )
|
|
{
|
|
m_current += delta;
|
|
|
|
if ( !ValueChanged() )
|
|
{
|
|
m_abort = true;
|
|
throw ProcessAborted();
|
|
}
|
|
}
|
|
}
|
|
|
|
/*!
|
|
* Changes the current progress \a text.
|
|
*
|
|
* This member function can abort the ongoing task. In such case, a
|
|
* ProcessAborted exception is thrown and the IsAborted() member function
|
|
* returns true.
|
|
*/
|
|
void SetText( const String& text )
|
|
{
|
|
m_text = text;
|
|
|
|
if ( !TextChanged() )
|
|
{
|
|
m_abort = true;
|
|
throw ProcessAborted();
|
|
}
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this object aborted a running task.
|
|
*/
|
|
bool IsAborted() const
|
|
{
|
|
return m_abort;
|
|
}
|
|
|
|
protected:
|
|
|
|
fsize_type m_total;
|
|
fsize_type m_current;
|
|
String m_text;
|
|
bool m_abort = false;
|
|
|
|
/*!
|
|
* Function called when the current progress count has been changed.
|
|
* Returns true to continue the running task; false to abort.
|
|
*
|
|
* This is a pure virtual function that must be reimplemented by derived
|
|
* classes.
|
|
*/
|
|
virtual bool ValueChanged() = 0;
|
|
|
|
/*!
|
|
* Function called when the current progress text has been changed.
|
|
* Returns true to continue the running task; false to abort.
|
|
*
|
|
* This is a pure virtual function that must be reimplemented by derived
|
|
* classes.
|
|
*/
|
|
virtual bool TextChanged() = 0;
|
|
};
|
|
|
|
// -------------------------------------------------------------------------
|
|
|
|
/*!
|
|
* Constructs a %File object that does not represent an existing file.
|
|
*/
|
|
File()
|
|
{
|
|
Initialize();
|
|
}
|
|
|
|
/*!
|
|
* Constructs a %File object that opens a file at a given \a path with the
|
|
* specified \a mode.
|
|
*/
|
|
File( const String& path, FileModes mode )
|
|
{
|
|
PCL_PRECONDITION( !path.IsEmpty() )
|
|
Initialize();
|
|
Open( path, mode );
|
|
}
|
|
|
|
/*!
|
|
* Move constructor.
|
|
*/
|
|
File( File&& x )
|
|
: m_fileHandle( x.m_fileHandle )
|
|
, m_filePath( std::move( x.m_filePath ) )
|
|
, m_fileMode( x.m_fileMode )
|
|
{
|
|
x.m_fileHandle = s_invalidHandle;
|
|
x.m_fileMode = FileMode::Zero;
|
|
}
|
|
|
|
/*!
|
|
* Move assignment operator. Returns a reference to this object.
|
|
*/
|
|
File& operator =( File&& x )
|
|
{
|
|
if ( &x != this )
|
|
{
|
|
if ( IsOpen() )
|
|
Close();
|
|
m_fileHandle = x.m_fileHandle;
|
|
m_filePath = std::move( x.m_filePath );
|
|
m_fileMode = x.m_fileMode;
|
|
x.m_fileHandle = s_invalidHandle;
|
|
x.m_fileMode = FileMode::Zero;
|
|
}
|
|
return *this;
|
|
}
|
|
|
|
/*!
|
|
* Destroys a %File object. If this instance represents an open file, it is
|
|
* closed upon destruction.
|
|
*/
|
|
virtual ~File()
|
|
{
|
|
if ( IsOpen() )
|
|
Close();
|
|
}
|
|
|
|
/*!
|
|
* Copy constructor. This constructor is disabled because files are unique
|
|
* objects.
|
|
*/
|
|
File( const File& ) = delete;
|
|
|
|
/*!
|
|
* Copy assignment. This operator is disabled because files are unique
|
|
* objects.
|
|
*/
|
|
File& operator =( const File& ) = delete;
|
|
|
|
/*!
|
|
* Returns true iff this %File object represents an open file.
|
|
*/
|
|
bool IsOpen() const
|
|
{
|
|
return IsValidHandle( m_fileHandle );
|
|
}
|
|
|
|
/*!
|
|
* Returns the path of the file represented by this %File object.
|
|
* Returned file paths are always absolute, full file paths.
|
|
*/
|
|
const String& FilePath() const
|
|
{
|
|
return m_filePath;
|
|
}
|
|
|
|
/*!
|
|
* Returns the path of the file represented by this %File object.
|
|
*
|
|
* \deprecated This member function has been deprecated. Use FilePath() in
|
|
* newly produced code.
|
|
*/
|
|
const String& FileName() const
|
|
{
|
|
return FilePath();
|
|
}
|
|
|
|
/*!
|
|
* Returns the file mode for this %File object.
|
|
*/
|
|
FileModes Mode() const
|
|
{
|
|
return m_fileMode;
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this file allows read access.
|
|
*/
|
|
virtual bool CanRead() const
|
|
{
|
|
return m_fileMode.IsFlagSet( FileMode::Read );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff this file allows write access.
|
|
*/
|
|
virtual bool CanWrite() const
|
|
{
|
|
return m_fileMode.IsFlagSet( FileMode::Write );
|
|
}
|
|
|
|
/*!
|
|
* Returns the current file position, relative to the beginning of the file
|
|
* represented by this %File object.
|
|
*/
|
|
virtual fpos_type Position() const;
|
|
|
|
/*!
|
|
* Sets the file position relative to the file beginning.
|
|
*/
|
|
virtual void SetPosition( fpos_type pos );
|
|
|
|
/*!
|
|
* Moves the file pointer. Returns the resulting pointer position from the
|
|
* file beginning.
|
|
*
|
|
* \param dist Distance to move in bytes.
|
|
* \param mode Seek mode. See the SeekMode namespace for valid modes.
|
|
*/
|
|
fpos_type Seek( fpos_type dist, seek_mode mode = SeekMode::FromCurrent );
|
|
|
|
/*!
|
|
* Moves the file pointer after the end of the file.
|
|
* Returns the size of this file, that is, the absolute position of the last
|
|
* byte plus one.
|
|
*
|
|
* This is a convenience member function, equivalent to
|
|
* Seek( 0, SeekMode::FromEnd )
|
|
*/
|
|
fpos_type SeekEnd()
|
|
{
|
|
return Seek( 0, SeekMode::FromEnd );
|
|
}
|
|
|
|
/*!
|
|
* Moves the file pointer to the beginning of this file.
|
|
*
|
|
* This is a convenience member function, equivalent to SetPosition( 0 )
|
|
*/
|
|
void Rewind()
|
|
{
|
|
SetPosition( 0 );
|
|
}
|
|
|
|
/*!
|
|
* Returns true iff the file pointer has been moved beyond the end of the
|
|
* file.
|
|
*/
|
|
bool IsEOF() const
|
|
{
|
|
return Position() >= Size();
|
|
}
|
|
|
|
/*!
|
|
* Returns the length in bytes of this file.
|
|
*/
|
|
virtual fsize_type Size() const;
|
|
|
|
/*!
|
|
* Truncates or extends this file to the specified \a length.
|
|
*/
|
|
virtual void Resize( fsize_type length );
|
|
|
|
/*!
|
|
* Reads a contiguous block of \a len bytes into the specified \a buffer.
|
|
*/
|
|
virtual void Read( void* buffer, fsize_type len );
|
|
|
|
/*!
|
|
* Reads an object \a x of type T.
|
|
*/
|
|
template <typename T>
|
|
void Read( T& x )
|
|
{
|
|
Read( (void*)&x, sizeof( T ) );
|
|
}
|
|
|
|
/*!
|
|
* Reads a set of \a n consecutive objects of type T into the array pointed
|
|
* to by \a a.
|
|
*
|
|
* This is a convenience member function, equivalent to
|
|
* Read( (void*)a, n*sizeof( T ) )
|
|
*/
|
|
template <typename T>
|
|
void ReadArray( T* a, size_type n )
|
|
{
|
|
Read( (void*)a, n*sizeof( T ) );
|
|
}
|
|
|
|
/*!
|
|
* Reads a numeric variable as a 32-bit signed integer.
|
|
*/
|
|
template <typename T>
|
|
void ReadI32( T& x )
|
|
{
|
|
int32 i; Read( i ); x = T( i );
|
|
}
|
|
|
|
/*!
|
|
* Reads a numeric variable as a 32-bit unsigned integer.
|
|
*/
|
|
template <typename T>
|
|
void ReadUI32( T& x )
|
|
{
|
|
uint32 i; Read( i ); x = T( i );
|
|
}
|
|
|
|
/*!
|
|
* Reads a numeric variable as a 64-bit signed integer.
|
|
*/
|
|
template <typename T>
|
|
void ReadI64( T& x )
|
|
{
|
|
int64 i; Read( i ); x = T( i );
|
|
}
|
|
|
|
/*!
|
|
* Reads a numeric variable as a 64-bit unsigned integer.
|
|
*/
|
|
template <typename T>
|
|
void ReadUI64( T& x )
|
|
{
|
|
uint64 i; Read( i ); x = T( i );
|
|
}
|
|
|
|
/*!
|
|
* Writes a contiguous block of \a len bytes from the specified \a buffer.
|
|
*/
|
|
virtual void Write( const void* buffer, fsize_type len );
|
|
|
|
/*!
|
|
* Writes an object \a x of type T.
|
|
*/
|
|
template <typename T>
|
|
void Write( const T& x )
|
|
{
|
|
Write( (const void*)&x, sizeof( T ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a set of \a n consecutive objects of type T from the array pointed
|
|
* to by \a a.
|
|
*
|
|
* This is a convenience member function, equivalent to
|
|
* Write( (const void*)a, n*sizeof( T ) )
|
|
*/
|
|
template <typename T>
|
|
void WriteArray( const T* a, size_type n )
|
|
{
|
|
Write( (const void*)a, n*sizeof( T ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a numeric variable as a 32-bit signed integer.
|
|
*/
|
|
template <typename T>
|
|
void WriteI32( const T& x )
|
|
{
|
|
Write( int32( x ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a numeric variable as a 32-bit unsigned integer.
|
|
*/
|
|
template <typename T>
|
|
void WriteUI32( const T& x )
|
|
{
|
|
Write( uint32( x ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a numeric variable as a 64-bit signed integer.
|
|
*/
|
|
template <typename T>
|
|
void WriteI64( const T& x )
|
|
{
|
|
Write( int64( x ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a numeric variable as a 64-bit unsigned integer.
|
|
*/
|
|
template <typename T>
|
|
void WriteUI64( const T& x )
|
|
{
|
|
Write( uint64( x ) );
|
|
}
|
|
|
|
/*!
|
|
* Reads a boolean variable.
|
|
*
|
|
* This function reads a 32-bit integer and assigns true to the variable
|
|
* \a b iff the read number is nonzero.
|
|
*/
|
|
void Read( bool& b )
|
|
{
|
|
unsigned i; ReadUI32( i ); b = i != 0;
|
|
}
|
|
|
|
/*!
|
|
* Writes a boolean variable.
|
|
*
|
|
* This function writes a 32-bit integer with a value of 1 (one) if the
|
|
* variable \a b is true, zero otherwise.
|
|
*/
|
|
void Write( const bool& b )
|
|
{
|
|
WriteUI32( b ? 1 : 0 );
|
|
}
|
|
|
|
/*!
|
|
* Reads a dynamic 8-bit string stored as binary data. The data should have
|
|
* been generated by a previous call to Write( const IsoString& ) on the
|
|
* file being read.
|
|
*/
|
|
void Read( IsoString& s );
|
|
|
|
/*!
|
|
* Reads a dynamic UTF-16 string stored as binary data. The data should have
|
|
* been generated by a previous call to Write( const IsoString& ) on the
|
|
* file being read.
|
|
*/
|
|
void Read( String& s );
|
|
|
|
/*!
|
|
* Writes a sequence of 8-bit characters, defined by the range [i,j), as
|
|
* binary data.
|
|
*/
|
|
void Write( const char* i, const char* j );
|
|
|
|
/*!
|
|
* Writes a null-terminated 8-bit string as binary data.
|
|
*/
|
|
void Write( const char* s )
|
|
{
|
|
Write( s, s + IsoCharTraits::Length( s ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic 8-bit string as binary data.
|
|
*/
|
|
void Write( const IsoString& s )
|
|
{
|
|
Write( s.Begin(), s.End() );
|
|
}
|
|
|
|
/*!
|
|
* Writes a sequence of UTF-16 characters, defined by the range [i,j), as
|
|
* binary data.
|
|
*/
|
|
void Write( const char16_type* i, const char16_type* j );
|
|
|
|
/*!
|
|
* Writes a null-terminated string of UTF-16 characters as binary data.
|
|
*/
|
|
void Write( const char16_type* s )
|
|
{
|
|
Write( s, s + CharTraits::Length( s ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic UTF-16 string as binary data.
|
|
*/
|
|
void Write( const String& s )
|
|
{
|
|
Write( s.Begin(), s.End() );
|
|
}
|
|
|
|
#ifndef __PCL_NO_FLAGS_FILE_IO
|
|
|
|
/*!
|
|
* Reads a set of flags \a f.
|
|
*/
|
|
template <typename E>
|
|
static void Read( Flags<E>& f )
|
|
{
|
|
Read( f.m_flags );
|
|
}
|
|
|
|
/*!
|
|
* Reads a set of flags \a f as an unsigned 32-bit integer.
|
|
*/
|
|
template <typename E>
|
|
static void ReadUI32( Flags<E>& f )
|
|
{
|
|
ReadUI32( f.m_flags );
|
|
}
|
|
|
|
/*!
|
|
* Writes a set of flags \a f.
|
|
*/
|
|
template <typename E>
|
|
static void Write( Flags<E> f )
|
|
{
|
|
Write( f.m_flags );
|
|
}
|
|
|
|
/*!
|
|
* Writes a set of flags \a f as an unsigned 32-bit integer.
|
|
*/
|
|
template <typename E>
|
|
static void WriteUI32( Flags<E> f )
|
|
{
|
|
WriteUI32( f.m_flags );
|
|
}
|
|
|
|
#endif
|
|
|
|
/*!
|
|
* Writes a sequence of 8-bit characters, defined by the range [i,j), as
|
|
* plain text.
|
|
*/
|
|
void OutText( const char* i, const char* j )
|
|
{
|
|
if ( i < j )
|
|
Write( (const void*)i, fsize_type( j - i ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a null-terminated 8-bit string as plain text.
|
|
*/
|
|
void OutText( const char* s )
|
|
{
|
|
OutText( s, s + IsoCharTraits::Length( s ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic 8-bit string as plain text.
|
|
*/
|
|
void OutText( const IsoString& s )
|
|
{
|
|
OutText( s.Begin(), s.End() );
|
|
}
|
|
|
|
/*!
|
|
* Writes a sequence of UTF-16 characters, defined by the range [i,j), as
|
|
* plain text.
|
|
*/
|
|
void OutText( const char16_type* i, const char16_type* j )
|
|
{
|
|
if ( i < j )
|
|
Write( (const void*)i, fsize_type( j - i ) << 1 );
|
|
}
|
|
|
|
/*!
|
|
* Writes a null-terminated UTF-16 string as plain text.
|
|
*/
|
|
void OutText( const char16_type* s )
|
|
{
|
|
OutText( s, s + CharTraits::Length( s ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic UTF16 string as plain text.
|
|
*/
|
|
void OutText( const String& s )
|
|
{
|
|
OutText( s.Begin(), s.End() );
|
|
}
|
|
|
|
/*!
|
|
* Writes a sequence of 8-bit characters, defined by the range [i,j), as
|
|
* plain text. Then writes a newline character.
|
|
*/
|
|
void OutTextLn( const char* i, const char* j )
|
|
{
|
|
OutText( i, j ); Write( '\n' );
|
|
}
|
|
|
|
/*!
|
|
* Writes a null-terminated 8-bit string as plain text and appends a newline
|
|
* character.
|
|
*/
|
|
void OutTextLn( const char* s )
|
|
{
|
|
OutText( s ); Write( '\n' );
|
|
}
|
|
|
|
/*!
|
|
* Writes an 8-bit newline character ('\n').
|
|
*
|
|
* \warning Do not use this member function if you are generating plain text
|
|
* encoded as UTF-16, for example in a sequence of calls to
|
|
* OutTextLn( const String& s ). In such case you can call:\n
|
|
* \n
|
|
* \code OutTextLn( String() ); \endcode \n
|
|
* \n
|
|
* to generate a newline in UTF-16 format.
|
|
*/
|
|
void OutTextLn()
|
|
{
|
|
Write( '\n' );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic 8-bit string as plain text and appends a newline
|
|
* character.
|
|
*/
|
|
void OutTextLn( const IsoString& s )
|
|
{
|
|
OutText( s ); Write( '\n' );
|
|
}
|
|
|
|
/*!
|
|
* Writes a sequence of UTF-16 characters, defined by the range [i,j), as
|
|
* plain text. Then writes a newline character.
|
|
*/
|
|
void OutTextLn( const char16_type* i, const char16_type* j )
|
|
{
|
|
OutText( i, j ); Write( char16_type( '\n' ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a null-terminated UTF-16 string as plain text and appends a
|
|
* newline character.
|
|
*/
|
|
void OutTextLn( const char16_type* s )
|
|
{
|
|
OutText( s ); Write( char16_type( '\n' ) );
|
|
}
|
|
|
|
/*!
|
|
* Writes a dynamic UTF16 string as plain text and appends a newline
|
|
* character.
|
|
*/
|
|
void OutTextLn( const String& s )
|
|
{
|
|
OutText( s ); Write( char16_type( '\n' ) );
|
|
}
|
|
|
|
/*!
|
|
* Commits any pending write operations.
|
|
*/
|
|
void Flush();
|
|
|
|
/*!
|
|
* Opens or creates a file.
|
|
*
|
|
* \param path The path to the file to be opened or created.
|
|
*
|
|
* \param mode Desired file access, share (Windows only) and
|
|
* opening/creation mode. By default, an existing file will
|
|
* be opened for (exclusive on Windows) read-only access.
|
|
*/
|
|
virtual void Open( const String& path, FileModes mode = FileMode::Read|FileMode::Open );
|
|
|
|
/*!
|
|
* Opens an existing file at the specified \a path. On Windows, the file is
|
|
* opened for shared read-only access (on UNIX and Linux, file access is
|
|
* handled automatically, so there is no need to define 'sharing modes').
|
|
*/
|
|
virtual void OpenForReading( const String& path )
|
|
{
|
|
Open( path, FileMode::Read|FileMode::Open|FileMode::ShareRead );
|
|
}
|
|
|
|
/*!
|
|
* Returns an open existing file at the specified \a path. On Windows, the
|
|
* file is opened for shared read-only access (on UNIX and Linux, file
|
|
* access is handled automatically, so there is no need to define 'sharing
|
|
* modes').
|
|
*/
|
|
static File OpenFileForReading( const String& path )
|
|
{
|
|
File f;
|
|
f.OpenForReading( path );
|
|
return f;
|
|
}
|
|
|
|
/*!
|
|
* Opens an existing file at \a path for exclusive read/write access.
|
|
*/
|
|
virtual void OpenForReadWrite( const String& path )
|
|
{
|
|
Open( path, FileMode::Read|FileMode::Write|FileMode::Open );
|
|
}
|
|
|
|
/*!
|
|
* Returns an open existing file at the specified \a path, ready for
|
|
* exclusive read/write access.
|
|
*/
|
|
static File OpenFileForReadWrite( const String& path )
|
|
{
|
|
File f;
|
|
f.OpenForReadWrite( path );
|
|
return f;
|
|
}
|
|
|
|
/*!
|
|
* Creates a file at the specified \a path for exclusive read/write access.
|
|
* If a file already exists at the same \a path, its contents will be
|
|
* truncated to zero length.
|
|
*/
|
|
virtual void Create( const String& path )
|
|
{
|
|
Open( path, FileMode::Read|FileMode::Write|FileMode::Create );
|
|
}
|
|
|
|
/*!
|
|
* Returns a newly created file at the specified \a path, ready for
|
|
* exclusive read/write access. If a file already exists at the same
|
|
* \a path, its contents will be truncated to zero length.
|
|
*/
|
|
static File CreateFile( const String& path )
|
|
{
|
|
File f;
|
|
f.Create( path );
|
|
return f;
|
|
}
|
|
|
|
/*!
|
|
* Creates a file at the specified \a path for exclusive write-only access.
|
|
* If a file already exists at the same \a path, its contents will be
|
|
* truncated to zero length.
|
|
*/
|
|
virtual void CreateForWriting( const String& path )
|
|
{
|
|
Open( path, FileMode::Write|FileMode::Create );
|
|
}
|
|
|
|
/*!
|
|
* Returns a newly created file at the specified \a path, ready for
|
|
* exclusive write-only access. If a file already exists at the same
|
|
* \a path, its contents will be truncated to zero length.
|
|
*/
|
|
static File CreateFileForWriting( const String& path )
|
|
{
|
|
File f;
|
|
f.CreateForWriting( path );
|
|
return f;
|
|
}
|
|
|
|
/*!
|
|
* Opens a file at the specified \a path if it exists, or creates it
|
|
* otherwise. The file will be opened in exclusive read/write mode.
|
|
*/
|
|
void OpenOrCreate( const String& path )
|
|
{
|
|
Open( path, FileMode::Read|FileMode::Write|FileMode::Open|FileMode::Create );
|
|
}
|
|
|
|
/*!
|
|
* Returns an open file at the specified \a path if it already exists, or a
|
|
* newly created file otherwise, ready for exclusive read/write access.
|
|
*/
|
|
static File OpenOrCreateFile( const String& path )
|
|
{
|
|
File f;
|
|
f.OpenOrCreate( path );
|
|
return f;
|
|
}
|
|
|
|
/*!
|
|
* Closes an open file. If this file has not been opened, calling this
|
|
* member function has no effect.
|
|
*/
|
|
virtual void Close();
|
|
|
|
/*!
|
|
* Removes an existing file at the specified \a filePath.
|
|
*/
|
|
static void Remove( const String& filePath );
|
|
|
|
/*!
|
|
* Creates a new directory at the specified \a dirPath.
|
|
*
|
|
* If \a createIntermediateDirectories is true (the default value) and
|
|
* \a dirPath specifies one or more parent directories that don't exist,
|
|
* they are created automatically.
|
|
*/
|
|
static void CreateDirectory( const String& dirPath, bool createIntermediateDirectories = true );
|
|
|
|
/*!
|
|
* Removes an existing \e empty directory at the specified \a dirPath.
|
|
*
|
|
* The specified directory must be empty, or this function will fail.
|
|
*/
|
|
static void RemoveDirectory( const String& dirPath );
|
|
|
|
/*!
|
|
* Moves and/or renames a file.
|
|
*
|
|
* \param filePath Current path of the file to move/rename
|
|
*
|
|
* \param newFilePath New path. If the directory in \a newFilePath is the
|
|
* same as in \a filePath, or if no directory is specified, the
|
|
* file is just renamed. If a different directory is specified,
|
|
* the file is also moved.
|
|
*
|
|
* \warning This function can only move or rename a file to stay in the same
|
|
* physical device. To move a file across devices, use the File::MoveFile()
|
|
* static member function.
|
|
*/
|
|
static void Move( const String& filePath, const String& newFilePath );
|
|
|
|
/*!
|
|
* Returns true iff a file at the specified \a filePath exists.
|
|
*/
|
|
static bool Exists( const String& filePath );
|
|
|
|
/*!
|
|
* Returns true iff a directory at the specified \a dirPath exists.
|
|
*/
|
|
static bool DirectoryExists( const String& dirPath );
|
|
|
|
/*!
|
|
* Ensures existence of a file on the local filesystem, guaranteeing that a
|
|
* newly created file cannot replace or overwrite an already existing file,
|
|
* or clash with an existing directory.
|
|
*
|
|
* \param[in,out] filePath Path to the file that must exist with
|
|
* guaranteed uniqueness. The value of the variable referenced
|
|
* by this parameter can be modified on output; see the
|
|
* \a canOverwrite parameter and the description below for
|
|
* further details.
|
|
*
|
|
* \param canOverwrite If this parameter is false and the specified
|
|
* \a filePath corresponds to an already existing file, the
|
|
* string referenced by \a filePath will be replaced on output
|
|
* with a new path on the same directory where the file name has
|
|
* been modified to guarantee that no file existed with the same
|
|
* name upon calling this function. If this parameter is true
|
|
* the \a filePath string won't be modified in any way.
|
|
*
|
|
* After calling this function, a file at the path specified by the output
|
|
* value of the \a filePath variable is guaranteed to exist, either because
|
|
* such file already existed when the function was called and the
|
|
* \a canOverwrite parameter was true, or because a new empty file has been
|
|
* created otherwise. Already existing files are never touched or modified
|
|
* in any way by this function (beyond the fact that they are accessed to
|
|
* verify their existence).
|
|
*
|
|
* Returns a UniqueFileChecks structure where the \a exists member indicates
|
|
* whether the specified \a filePath corresponds to an already existing file
|
|
* upon calling this function, and the \a overwrite member is true iff an
|
|
* existing file can be overwritten because the specified \a canOverwrite
|
|
* parameter is true.
|
|
*
|
|
* When the \a filePath string is altered to provide a unique file name, the
|
|
* file path is made unique by appending the literal representation of an
|
|
* unsigned integer, preceded by an underscore character, to the file name
|
|
* component. For example, if this function is called as follows when the
|
|
* specified file already exists:
|
|
*
|
|
* \code
|
|
* String filePath = "/path/to/foo.bar"; // this file exists
|
|
* EnsureNewUniqueFile( filePath );
|
|
* \endcode
|
|
*
|
|
* then the \c filePath variable could have the value "/path/to/foo_1.bar",
|
|
* and a new, empty file would have been created at that path. Successive
|
|
* calls would set \c filePath equal to "/path/to/foo_2.bar",
|
|
* "/path/to/foo_3.bar", and so on, creating the corresponding new files.
|
|
*
|
|
* \note This static member function is thread-safe. It will provide
|
|
* coherent results when invoked from multiple threads running concurrently.
|
|
*/
|
|
static UniqueFileChecks EnsureNewUniqueFile( String& filePath, bool canOverwrite = false );
|
|
|
|
/*!
|
|
* Ensures existence of a directory on the local filesystem, guaranteeing
|
|
* that a new, empty directory will be created in case a file or directory
|
|
* at the specified path already existed when the function was called.
|
|
*
|
|
* \param[in,out] dirPath Path to the directory that must exist with
|
|
* guaranteed uniqueness. The value of the variable referenced
|
|
* by this parameter can be modified on output; see the
|
|
* description below for further details.
|
|
*
|
|
* After calling this function, a directory at the path specified by the
|
|
* output value of the \a dirPath variable is guaranteed to exist, either
|
|
* because such directory already existed when the function was called, or
|
|
* because a new empty directory has been created otherwise. Already
|
|
* existing directories or files are never touched or modified in any way by
|
|
* this function (beyond the fact that they are accessed to verify their
|
|
* existence).
|
|
*
|
|
* Returns a UniqueFileChecks structure where the \a exists member indicates
|
|
* whether the specified \a dirPath corresponds to an already existing
|
|
* directory upon calling this function, and the \a overwrite member is
|
|
* always false, reflecting the fact that a directory cannot be overwritten.
|
|
*
|
|
* If the specified directory already exists, the string referenced by
|
|
* \a dirPath will be altered to provide a unique directory name on the same
|
|
* parent directory. In such case the path is made unique by appending the
|
|
* literal representation of an unsigned integer, preceded by an underscore
|
|
* character, to the file name component. For example, if this function is
|
|
* called as follows when the specified directory already exists:
|
|
*
|
|
* \code
|
|
* String dirPath = "/path/to/foobar"; // this directory exists
|
|
* EnsureNewUniqueDirectory( dirPath );
|
|
* \endcode
|
|
*
|
|
* then the \c dirPath variable could have the value "/path/to/foobar_1" and
|
|
* a new, empty directory would have been created at that path. Successive
|
|
* calls would set \c dirPath equal to "/path/to/foobar_2",
|
|
* "/path/to/foobar_3", and so on, creating the corresponding new
|
|
* directories.
|
|
*
|
|
* The string referenced by the specified \a dirPath variable can optionally
|
|
* end with a directory separator character, which will be preserved in case
|
|
* the string is modified.
|
|
*
|
|
* \note This static member function is thread-safe. It will provide
|
|
* coherent results when invoked from multiple threads running concurrently.
|
|
*/
|
|
static UniqueFileChecks EnsureNewUniqueDirectory( String& dirPath );
|
|
|
|
/*!
|
|
* Returns true iff the file at \a filePath exists and the current user has
|
|
* read-only access to it.
|
|
*/
|
|
static bool IsReadOnly( const String& filePath );
|
|
|
|
/*!
|
|
* Enables or disables read-only access to a file at the specified
|
|
* \a filePath.
|
|
*/
|
|
static void SetReadOnly( const String& filePath, bool rdOnly = true );
|
|
|
|
/*!
|
|
* Disables or enables read-only access to a file at the specified
|
|
* \a filePath.
|
|
*
|
|
* This is a convenience member function, equivalent to
|
|
* SetReadOnly( filePath, false )
|
|
*/
|
|
static void SetReadWrite( const String& filePath )
|
|
{
|
|
SetReadOnly( filePath, false );
|
|
}
|
|
|
|
/*!
|
|
* Reads the contents of a file at the specified \a filePath and returns
|
|
* them as a ByteArray object.
|
|
*/
|
|
static ByteArray ReadFile( const String& filePath );
|
|
|
|
/*!
|
|
* Creates a file with the specified contents.
|
|
*
|
|
* \param filePath Path to the file that will be created.
|
|
*
|
|
* \param contents Reference to a ByteArray object providing the contents
|
|
* that will be written to the newly created file.
|
|
*
|
|
* Typically this function is used along with File::ReadFile() to implement
|
|
* a file copying routine; for example:
|
|
*
|
|
* \code
|
|
* void CopyFile( const String& targetFilePath, const String& sourceFilePath )
|
|
* {
|
|
* File::WriteFile( targetFilePath, File::ReadFile( sourceFilePath ) );
|
|
* }
|
|
* \endcode
|
|
*
|
|
* \warning If a file already exists at the specified path, its previous
|
|
* contents will be lost after calling this function.
|
|
*/
|
|
static void WriteFile( const String& filePath, const ByteArray& contents );
|
|
|
|
/*!
|
|
* Creates a file with a subset of a ByteArray container.
|
|
*
|
|
* \param filePath Path to the file that will be created.
|
|
*
|
|
* \param contents Reference to a ByteArray object providing the contents
|
|
* that will be written to the newly created file.
|
|
*
|
|
* \param start Zero-based index of the first byte to be written.
|
|
*
|
|
* \param size Number of bytes that will be written.
|
|
*
|
|
* \warning If a file already exists at the specified path, its previous
|
|
* contents will be lost after calling this function.
|
|
*/
|
|
static void WriteFile( const String& filePath, const ByteArray& contents, size_type start, size_type size );
|
|
|
|
/*!
|
|
* Creates a file with the specified contents.
|
|
*
|
|
* \param filePath Path to the file that will be created.
|
|
*
|
|
* \param data Pointer to the first byte to be written to the newly
|
|
* created file.
|
|
*
|
|
* \param size Number of contiguous bytes, starting from \a data, to
|
|
* be written.
|
|
*
|
|
* \warning If a file already exists at the specified path, its previous
|
|
* contents will be lost after calling this function.
|
|
*/
|
|
static void WriteFile( const String& filePath, const void* data, size_type size );
|
|
|
|
/*!
|
|
* Reads the contents of a file at the specified \a filePath and returns
|
|
* them as plain text stored in a dynamic 8-bit string.
|
|
*
|
|
* This function is useful to load document files encoded in UTF-8,
|
|
* ISO/IEC-8859-1 (or Latin-1), and other 8-bit encodings.
|
|
*/
|
|
static IsoString ReadTextFile( const String& filePath );
|
|
|
|
/*!
|
|
* Creates a file with the specified plain text content.
|
|
*
|
|
* \param filePath Path to the file that will be created.
|
|
*
|
|
* \param text Reference to an IsoString object providing the plain
|
|
* text that will be written to the newly created file.
|
|
*
|
|
* This function is useful to generate document files encoded in UTF-8,
|
|
* ISO/IEC-8859-1 (or Latin-1), and other 8-bit encodings.
|
|
*
|
|
* \warning If a file already exists at the specified path, its previous
|
|
* contents will be lost after calling this function.
|
|
*/
|
|
static void WriteTextFile( const String& filePath, const IsoString& text );
|
|
|
|
/*!
|
|
* Changes the access permissions of a file or directory.
|
|
*
|
|
* \param targetPath Path to the existing file or directory whose
|
|
* permissions will be modified.
|
|
*
|
|
* \param permissions An ORed combination of file permission flags. See
|
|
* the FilePermission namespace for contants.
|
|
*
|
|
* On UNIX and Linux platforms (FreeBSD, GNU Linux, Mac OS X), the read,
|
|
* write and execution permissions can be specified separately for the owner
|
|
* user, for the owner group, and for the rest of users. On Windows, only
|
|
* generic read and write permissions can be set, and there are no execution
|
|
* permissions.
|
|
*/
|
|
static void SetPermissions( const String& targetPath, FileAttributes permissions );
|
|
|
|
/*!
|
|
* Copies access and modification times and access permissions from one
|
|
* file or directory item to another.
|
|
*
|
|
* \param targetPath Path to the target item whose times and permissions
|
|
* will be changed.
|
|
*
|
|
* \param sourcePath Path to the source item whose times and permissions
|
|
* will be copied to the target item.
|
|
*/
|
|
static void CopyTimesAndPermissions( const String& targetPath, const String& sourcePath );
|
|
|
|
#ifndef __PCL_WINDOWS
|
|
/*!
|
|
* Copies a symbolic link.
|
|
*
|
|
* \param targetLinkPath Path to the target file. A new symbolic link will
|
|
* be created at this path, which will point to the
|
|
* same link target as the source link.
|
|
*
|
|
* \param sourceLinkPath Path to the source link, whose target will be
|
|
* copied to the target link.
|
|
*
|
|
* Note that this function creates a duplicate of the symbolic link itself,
|
|
* \e not of its pointed file.
|
|
*
|
|
* \note This static member function is only defined on UNIX and Linux
|
|
* platforms. It does not make sense on Windows, where POSIX symbolic links
|
|
* don't exist.
|
|
*/
|
|
static void CopyLink( const String& targetLinkPath, const String& sourceLinkPath );
|
|
#endif // !__PCL_WINDOWS
|
|
|
|
/*!
|
|
* Copies a single file.
|
|
*
|
|
* \param targetFilePath Path to the target file, which must \e not exist.
|
|
* If the specified file exists, an Error exception
|
|
* will be thrown.
|
|
*
|
|
* \param sourceFilePath Path to the source file. This file must exist and
|
|
* must be different from the specified target file.
|
|
*
|
|
* \param progress Pointer to an instance of (a derived class of)
|
|
* File::Progress. If a non-null pointer is
|
|
* specified, the object will be used to provide
|
|
* progress information and the possibility of
|
|
* aborting the file copy operation. The default
|
|
* value is \c nullptr.
|
|
*
|
|
* The file copy operation is implemented as an iterative block copying
|
|
* routine. This means that huge files can be copied with minimal
|
|
* consumption of memory resources and no specific file size limit.
|
|
*
|
|
* Along with the file contents, file access and modification times, as well
|
|
* as file access permissions, will also be copied by this function.
|
|
*
|
|
* This function does not follow symbolic links. It does not copy the file
|
|
* pointed to by a symbolic link, but the link itself. This is only relevant
|
|
* to platforms that support symbolic links (i.e., all of them but Windows).
|
|
*
|
|
* If a \a progress object is specified, it receives successive calls to
|
|
* File::Progress::Add() with increments in bytes. If the progress object
|
|
* aborts the file copy operation, this member function throws a
|
|
* ProcessAborted exception.
|
|
*/
|
|
static void CopyFile( const String& targetFilePath, const String& sourceFilePath, File::Progress* progress = nullptr );
|
|
|
|
/*!
|
|
* Moves a single file.
|
|
*
|
|
* \param targetFilePath Path to the target file, which must \e not exist.
|
|
* If the specified file exists, an Error exception
|
|
* will be thrown.
|
|
*
|
|
* \param sourceFilePath Path to the source file. This file must exist and
|
|
* must be different from the specified target file.
|
|
*
|
|
* \param progress Pointer to an instance of (a derived class of)
|
|
* File::Progress. If a non-null pointer is
|
|
* specified, the object will be used to provide
|
|
* progress information and the possibility of
|
|
* aborting the file copy operation. The default
|
|
* value is \c nullptr.
|
|
*
|
|
* For file move operations within the same physical device, this function
|
|
* implements a simple rename operation. In these cases, the \a progress
|
|
* object (if specified) receives a single call to File::Progress::Add()
|
|
* with the total file size in bytes.
|
|
*
|
|
* When a file is moved to a different device, this member function first
|
|
* copies the source file to the target location using a routine equivalent
|
|
* to Copy(). When the entire file contents have been transferred, the
|
|
* source file is removed.
|
|
*
|
|
* Along with the file contents, file access and modification times, as well
|
|
* as file access permissions, will be preserved by this function.
|
|
*
|
|
* This function does not follow symbolic links. It does not move the file
|
|
* pointed to by a symbolic link, but the link itself. This is only relevant
|
|
* to platforms that support symbolic links (i.e., all of them but Windows).
|
|
*
|
|
* If a \a progress object is specified and it aborts the file move
|
|
* operation, this member function throws a ProcessAborted exception. In
|
|
* such case the source file is guaranteed to remain intact.
|
|
*/
|
|
static void MoveFile( const String& targetFilePath, const String& sourceFilePath, File::Progress* progress = nullptr );
|
|
|
|
/*!
|
|
* Returns true iff two files or directories are mounted on the same physical
|
|
* device.
|
|
*
|
|
* This is relevant to some critical file operations. For example, moving a
|
|
* file on the same device is a simple and fast rename operation. However,
|
|
* moving a file across devices involves copying the entire file contents.
|
|
*
|
|
* This function does not follow symbolic links. It does not consider
|
|
* mounted devices for files pointed to by symbolic links, but for the links
|
|
* themselves. This is only relevant to platforms that support symbolic
|
|
* links (all of them but Windows).
|
|
*/
|
|
static bool SameDevice( const String& path1, const String& path2 );
|
|
|
|
/*!
|
|
* Returns true iff two file path specifications refer to the same file on
|
|
* the system.
|
|
*
|
|
* On UNIX and Linux platforms, this function compares the device and inode
|
|
* numbers reported by the st_dev and st_ino members of the stat structure,
|
|
* respectively. This pair of numbers uniquely identifies every file on the
|
|
* system, irrespective of file names.
|
|
*
|
|
* On Windows platforms, this function verifies the devices that support
|
|
* both files and, if they are the same, performs a case-insensitive
|
|
* comparison of the canonical absolute versions of the specified paths.
|
|
*
|
|
* This function does not follow symbolic links. It does not consider
|
|
* mounted devices for files pointed to by symbolic links, but for the links
|
|
* themselves. This is only relevant to platforms that support symbolic
|
|
* links (all of them but Windows).
|
|
*/
|
|
static bool SameFile( const String& path1, const String& path2 );
|
|
|
|
/*!
|
|
* Reads all existing text lines from a file as 8-bit strings (e.g.,
|
|
* ISO 8859-1 or UTF-8 formats) and returns them as a string list.
|
|
*
|
|
* \param filePath Path to the source file from which text lines will
|
|
* be read.
|
|
*
|
|
* \param options Optional set of flags (ORed combination) that can be
|
|
* specified to control the way text lines are
|
|
* extracted and stored. Available flags are defined in
|
|
* the ReadTextOption namespace.
|
|
*
|
|
* Returns a string list (IsoStringList) with all existing lines in the
|
|
* specified file. If the file is empty, an empty string list is returned.
|
|
*
|
|
* This routine automatically detects and processes line ending sequences
|
|
* characteristic of all supported platforms: UNIX (LF = 0x0A), Windows
|
|
* (CR+LF = 0x0D+0x0A) and legacy Mac (CR = 0x0D).
|
|
*/
|
|
static IsoStringList ReadLines( const String& filePath,
|
|
ReadTextOptions options = ReadTextOptions() );
|
|
|
|
/*!
|
|
* Iterates a function through all existing text lines in a file.
|
|
*
|
|
* \param filePath Path to the source file from which text lines will
|
|
* be read. This file is assumed to store text as a
|
|
* sequence of 8-bit characters, e.g. ASCII, ISO 8859-1
|
|
* or UTF-8.
|
|
*
|
|
* \param callback Callback function. This function will be invoked
|
|
* once for each text line. The function will receive
|
|
* two arguments: a char* with the starting address of
|
|
* an 8-bit null terminated string, and a void* which
|
|
* is the specified \a data argument. The function will
|
|
* return true if the process can continue for the next
|
|
* text line; false to stop the iteration.
|
|
*
|
|
* \param data A void* that will be passed to the callback function
|
|
* as its second argument on each call. The default
|
|
* value is \c nullptr.
|
|
*
|
|
* \param options Optional set of flags (ORed combination) that can be
|
|
* specified to control the way text lines are explored
|
|
* and passed to the callback function. Available flags
|
|
* are defined in the ReadTextOption namespace.
|
|
*
|
|
* Returns the number of text lines that have been scanned, i.e. the number
|
|
* of times the callback function has been invoked and has returned true.
|
|
*
|
|
* This routine avoids all the work associated with creating and storing new
|
|
* IsoString objects. When IsoString instances are not necessary to acquire
|
|
* the data being read, this routine can be much faster than ReadLines(),
|
|
* especially for vey large files.
|
|
*
|
|
* This routine automatically detects and processes line ending sequences
|
|
* characteristic of all supported platforms: UNIX (LF = 0x0A), Windows
|
|
* (CR+LF = 0x0D+0x0A) and legacy Mac (CR = 0x0D).
|
|
*/
|
|
static size_type ScanLines( const String& filePath,
|
|
bool (*callback)( char*, void* ), void* data = nullptr,
|
|
ReadTextOptions options = ReadTextOptions() );
|
|
|
|
/*!
|
|
* Returns the full, absolute local path to the specified \a path.
|
|
*/
|
|
static String FullPath( const String& path );
|
|
|
|
/*!
|
|
* Returns a valid URI with the "file" scheme corresponding to the specified
|
|
* local \a path.
|
|
*
|
|
* The returned URI is valid as specified by RFC 1738 and RFC 8089. The
|
|
* following characters will always be percent-encoded when present in the
|
|
* specified \a path:
|
|
*
|
|
* - Non-printable US-ASCII characters in the ranges [00-1F] and [7F-FF].
|
|
*
|
|
* - Unsafe characters: ' ', '<', '>', '#', '"', '%', '{', '}', '|', '\\',
|
|
* '^', '~', '[', ']', '`'
|
|
*
|
|
* - Reserved characters: ';', '?', ':', '@', '=', '&'.
|
|
*
|
|
* The returned URI will include the specified path transformed to a full
|
|
* absolute local path with UNIX directory separators, encoded in UTF-8,
|
|
* percent-encoded as necessary, and prefixed with the "file://" scheme.
|
|
*
|
|
* On Windows, a drive letter will always be present, prefixed with a root
|
|
* directory specifier, and the colon separator will be used; for example:
|
|
*
|
|
* file:///c:/path/to/local%20file.txt
|
|
*
|
|
* \b References:
|
|
*
|
|
* https://tools.ietf.org/html/rfc1738 \n
|
|
* https://tools.ietf.org/html/rfc8089 \n
|
|
*/
|
|
static IsoString FileURI( const String& path );
|
|
|
|
/*!
|
|
* Returns the system temporary storage directory.
|
|
*
|
|
* On FreeBSD, Linux and macOS, this function returns the value of the
|
|
* TMPDIR environment variable if it is defined, nonempty, and is a valid
|
|
* path to an existing directory. Otherwise this function returns "/tmp".
|
|
*
|
|
* On Windows, this function returns the directory designated for storage of
|
|
* temporary files. Normally this is the value of the TMP or TEMP
|
|
* environment variable. If no valid directory can be retrieved this way
|
|
* (which is extremely weird), this function attempts to return the user's
|
|
* profile directory, as reported by the USERPROFILE variable. If that also
|
|
* fails, "C:/tmp" is returned if it exists, or the current working
|
|
* directory as a last resort.
|
|
*/
|
|
static String SystemTempDirectory();
|
|
|
|
/*!
|
|
* Returns the system cache storage directory.
|
|
*
|
|
* On FreeBSD, Linux and Windows, this function is equivalent to
|
|
* SystemTempDirectory().
|
|
*
|
|
* On macOS, this function returns the user's local cache folder, namely
|
|
* "~/Library/Caches" if it exists (it must), or SystemTempDirectory()
|
|
* otherwise.
|
|
*/
|
|
static String SystemCacheDirectory();
|
|
|
|
/*!
|
|
* Returns the home directory of the current user.
|
|
*
|
|
* On FreeBSD, Linux and macOS, this function returns the value of the HOME
|
|
* environment variable if it is defined, nonempty, and is a valid path to
|
|
* an existing directory. In the extremely weird case this does not happen,
|
|
* the system root directory '/' is returned as a last resort.
|
|
*
|
|
* On Windows, this function returns the root directory of the current
|
|
* user's profile. This is normally the value of the USERPROFILE environment
|
|
* variable. In case this fails, the HOMEDRIVE, HOMEPATH and HOME variables
|
|
* are checked for validity. If everything fails, the SYSTEMDRIVE variable
|
|
* is checked and ultimately "C:/" is returned.
|
|
*/
|
|
static String HomeDirectory();
|
|
|
|
/*!
|
|
* Converts a path from Windows to UNIX syntax. Replaces all occurrences of
|
|
* the '\\' Windows separator with the '/' UNIX separator.
|
|
*/
|
|
static String WindowsPathToUnix( const String& path );
|
|
|
|
/*!
|
|
* Converts a path from UNIX to Windows. Replaces all occurrences of
|
|
* the '/' UNIX separator with the '\\' Windows separator.
|
|
*/
|
|
static String UnixPathToWindows( const String& path );
|
|
|
|
/*!
|
|
* Returns a nonexistent, randomly generated file name.
|
|
*
|
|
* \param directory Name of an existing directory where the generated file
|
|
* name is guaranteed to be unique. If empty or not
|
|
* specified, the current directory of the calling process
|
|
* will be used.
|
|
*
|
|
* \param n Number of random characters in the generated file name.
|
|
* Must be at least five characters. The default value is
|
|
* twelve characters.
|
|
*
|
|
* \param prefix An optional prefix that will be prepended to the
|
|
* generated file name.
|
|
*
|
|
* \param postfix An optional postfix that will be appended to the
|
|
* generated file name.
|
|
*
|
|
* This function returns the full absolute path of a nonexistent file name
|
|
* generated by concatenation of \a n random characters. For compatibility
|
|
* with case-insensitive file systems (FAT, NTFS), only uppercase characters
|
|
* and decimal digits are used in the generated file name.
|
|
*
|
|
* The returned file name is guaranteed to be unique on the specified
|
|
* directory (or on the current directory of the calling process if no
|
|
* directory is specified) just after this function returns. Note that since
|
|
* a high-quality random number generator is used to select file name
|
|
* characters, there is no practical chance for a race condition by calling
|
|
* this function from several threads concurrently.
|
|
*/
|
|
static String UniqueFileName( const String& directory = String(), int n = 12,
|
|
const String& prefix = String(), const String& postfix = String() );
|
|
|
|
/*!
|
|
* Retrieves the storage space available on the device that supports a
|
|
* specified directory.
|
|
*
|
|
* \param dirPath A path specification to an existing directory on the
|
|
* local filesystem. On Windows, UNC paths are fully
|
|
* supported. Symbolic links are supported on all
|
|
* platforms. If a symbolic link is specified, the
|
|
* returned values refer to the target device.
|
|
*
|
|
* \param[out] totalBytes If non-null, the address of a variable that
|
|
* receives the total capacity in bytes of the device that
|
|
* supports the specified directory.
|
|
*
|
|
* \param[out] freeBytes If non-null, the address of a variable that
|
|
* receives the total number of free bytes on the device
|
|
* that supports the specified directory.
|
|
*
|
|
* Returns the total number of bytes available on the device that supports
|
|
* the specified directory. The returned values take into account any disk
|
|
* quotas that might apply to the user associated with the calling process.
|
|
*/
|
|
static uint64 GetAvailableSpace( const String& dirPath, uint64* totalBytes = nullptr, uint64* freeBytes = nullptr );
|
|
|
|
/*!
|
|
* Finds a Windows drive specification in the specified \a path.
|
|
*
|
|
* Returns the character index position of the drive found, or
|
|
* String::notFound.
|
|
*
|
|
* This function only makes sense on Windows. On UNIX and Linux operating
|
|
* systems, this function always returns String::notFound.
|
|
*/
|
|
static size_type FindDrive( const String& path );
|
|
|
|
/*!
|
|
* Finds a file name in the specified \a path.
|
|
*
|
|
* Returns the character index position of the name found, or
|
|
* String::notFound.
|
|
*
|
|
* For example, in '/foo/bar.tar.gz' the file name is 'bar'.
|
|
*/
|
|
static size_type FindName( const String& path );
|
|
|
|
/*!
|
|
* Finds a file extension in the specified \a path.
|
|
*
|
|
* Returns the character index position of the extension found, or
|
|
* String::notFound.
|
|
*
|
|
* The file extension, or file suffix, is the rightmost substring of \a path
|
|
* starting with the last occurrence of a dot character. For example, in
|
|
* 'foo.tar.gz' the file extension is '.gz'.
|
|
*
|
|
* \sa FindCompleteSuffix()
|
|
*/
|
|
static size_type FindExtension( const String& path );
|
|
|
|
/*!
|
|
* A synonym for FindExtension().
|
|
*/
|
|
static size_type FindSuffix( const String& path )
|
|
{
|
|
return FindExtension( path );
|
|
}
|
|
|
|
/*!
|
|
* Finds the complete file suffix in the specified \a path.
|
|
*
|
|
* Returns the character index position of the complete suffix found, or
|
|
* String::notFound.
|
|
*
|
|
* The complete suffix is the rightmost substring of the \a path starting
|
|
* with the first occurrence of a dot character. For example, in
|
|
* 'foo.tar.gz' the complete suffix is '.tar.gz'.
|
|
*
|
|
* \sa FindSuffix()
|
|
*/
|
|
static size_type FindCompleteSuffix( const String& path );
|
|
|
|
/*!
|
|
* Extracts a Windows drive specification from the specified \a path.
|
|
*
|
|
* Returns the extracted drive specification as a new string, or an empty
|
|
* string if no drive was found.
|
|
*
|
|
* This function only makes sense on Windows. On UNIX and Linux operating
|
|
* systems, this function always returns an empty string.
|
|
*/
|
|
static String ExtractDrive( const String& path ); // always empty string on X
|
|
|
|
/*!
|
|
* Extracts a directory specification from the specified \a path.
|
|
*
|
|
* Returns the extracted directory specification, or an empty string if no
|
|
* directory was found. On Windows, the drive element of the path is not
|
|
* included.
|
|
*
|
|
* Examples:
|
|
*
|
|
* In '/foo.tar.gz' the directory is '/'.
|
|
* In '/foo/bar.tar.gz' the directory is '/foo'.
|
|
* In 'foo/bar.tar.gz' the directory is 'foo'.
|
|
* In 'C:/Foo/Bar.txt' the directory is '/Foo'.
|
|
*/
|
|
static String ExtractDirectory( const String& path );
|
|
|
|
/*!
|
|
* Extracts a file name from the specified \a path.
|
|
*
|
|
* Returns the extracted name, or an empty string if no file name was found.
|
|
* The file extension or suffix is not included.
|
|
*
|
|
* Examples:
|
|
*
|
|
* In '/foo/bar.tar.gz' the name is 'bar.tar'.
|
|
* In 'C:/Foo/Bar.txt' the name is 'Bar'.
|
|
*/
|
|
static String ExtractName( const String& path );
|
|
|
|
/*!
|
|
* Extracts a file extension from the specified \a path.
|
|
*
|
|
* Returns the extracted extension, or an empty string if no file extension
|
|
* was found. The returned extension \e includes the initial dot separator.
|
|
*
|
|
* Examples:
|
|
*
|
|
* In '/foo/bar.tar.gz' the extension is '.gz'.
|
|
* In 'C:/Foo/Bar.txt' the extension is '.txt'.
|
|
*
|
|
* \sa ExtractCompleteSuffix()
|
|
*/
|
|
static String ExtractExtension( const String& path );
|
|
|
|
/*!
|
|
* A synonym for ExtractExtension().
|
|
*/
|
|
static String ExtractSuffix( const String& path )
|
|
{
|
|
return ExtractExtension( path );
|
|
}
|
|
|
|
/*!
|
|
* Extracts the complete file suffix from the specified \a path.
|
|
*
|
|
* Returns the extracted complete suffix, or an empty string if no file
|
|
* suffix was found. The returned string \e includes the initial dot
|
|
* separator.
|
|
*
|
|
* The complete suffix is the ending substring of the file identifier in the
|
|
* specified \a path, starting with the first occurrence of a dot character.
|
|
* For example, in 'foo.tar.gz' the complete suffix is '.tar.gz'.
|
|
*
|
|
* \sa ExtractSuffix()
|
|
*/
|
|
static String ExtractCompleteSuffix( const String& path );
|
|
|
|
/*!
|
|
* Extracts the file name and extension from the specified \a path. Calling
|
|
* this member function is functionally equivalent to:
|
|
*
|
|
* File::ExtractName( path ) + File::ExtractExtension( path )
|
|
*/
|
|
static String ExtractNameAndExtension( const String& path );
|
|
|
|
/*!
|
|
* A synonym for ExtractNameAndExtension().
|
|
*/
|
|
static String ExtractNameAndSuffix( const String& path )
|
|
{
|
|
return ExtractNameAndExtension( path );
|
|
}
|
|
|
|
/*!
|
|
* Changes the current file extension in \a filePath to a new extension
|
|
* \a ext. If it is not an empty string, the specified extension \e must
|
|
* include the initial dot separator.
|
|
*
|
|
* If the specified new extension \a ext is an empty string, this function
|
|
* returns \a filePath with its extension (if any) removed.
|
|
*
|
|
* Returns the resulting path after changing the file extension to the
|
|
* specified value.
|
|
*/
|
|
static String ChangeExtension( const String& filePath, const String& ext );
|
|
|
|
/*!
|
|
* Appends a \a postfix string to the current file name in the specified
|
|
* \a filePath. Returns the resulting path.
|
|
*/
|
|
static String AppendToName( const String& filePath, const String& postfix );
|
|
|
|
/*!
|
|
* Prepends a \a prefix string to the current file name in the specified
|
|
* \a filePath. Returns the resulting path.
|
|
*/
|
|
static String PrependToName( const String& filePath, const String& prefix );
|
|
|
|
/*!
|
|
* Returns a readable textual representation of a file size with automatic
|
|
* units conversion.
|
|
*
|
|
* \param sizeInBytes The file size in bytes.
|
|
*
|
|
* \param precision The number of decimal digits used to represent
|
|
* floating point numbers. The default value is 3.
|
|
*
|
|
* \param alsoShowBytes Whether to add the size in bytes to the string
|
|
* representation, irrespective of the units used. The
|
|
* default value is false.
|
|
*
|
|
* Examples:
|
|
*
|
|
* \code
|
|
* String s1 = File::SizeAsString( 21771472 );
|
|
* // s1 = "20.763 MiB"
|
|
* String s2 = File::SizeAsString( 21771472, 2, true );
|
|
* // s2 = "20.76 MiB (21771472 bytes)"
|
|
* String s3 = File::SizeAsString( 4727, 4 );
|
|
* // s3 = "4.6162 KiB"
|
|
* \endcode
|
|
*/
|
|
static String SizeAsString( fsize_type sizeInBytes, int precision = 3, bool alsoShowBytes = false );
|
|
|
|
protected:
|
|
|
|
handle m_fileHandle;
|
|
String m_filePath;
|
|
FileModes m_fileMode;
|
|
|
|
static const handle s_invalidHandle;
|
|
|
|
void Initialize();
|
|
virtual bool IsValidHandle( handle h ) const;
|
|
};
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
} // pcl
|
|
|
|
#endif // __PCL_File_h
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// EOF pcl/File.h - Released 2022-03-12T18:59:29Z
|