PCL
pcl::File Class Reference

A platform-independent interface to the local file system. More...

#include <File.h>

Classes

class  Error
 File I/O exception. More...
 
class  Find
 Directory search operation. More...
 
class  Progress
 Abstract base class of file progress objects. More...
 

Public Types

using handle = void *
 
using seek_mode = SeekMode::value_type
 

Public Member Functions

 File ()
 
 File (const File &)=delete
 
 File (const String &path, FileModes mode)
 
 File (File &&x)
 
virtual ~File ()
 
virtual bool CanRead () const
 
virtual bool CanWrite () const
 
virtual void Close ()
 
virtual void Create (const String &path)
 
virtual void CreateForWriting (const String &path)
 
const StringFileName () const
 
const StringFilePath () const
 
void Flush ()
 
bool IsEOF () const
 
bool IsOpen () const
 
FileModes Mode () const
 
virtual void Open (const String &path, FileModes mode=FileMode::Read|FileMode::Open)
 
virtual void OpenForReading (const String &path)
 
virtual void OpenForReadWrite (const String &path)
 
void OpenOrCreate (const String &path)
 
Fileoperator= (const File &)=delete
 
Fileoperator= (File &&x)
 
void OutText (const char *i, const char *j)
 
void OutText (const char *s)
 
void OutText (const char16_type *i, const char16_type *j)
 
void OutText (const char16_type *s)
 
void OutText (const IsoString &s)
 
void OutText (const String &s)
 
void OutTextLn ()
 
void OutTextLn (const char *i, const char *j)
 
void OutTextLn (const char *s)
 
void OutTextLn (const char16_type *i, const char16_type *j)
 
void OutTextLn (const char16_type *s)
 
void OutTextLn (const IsoString &s)
 
void OutTextLn (const String &s)
 
virtual fpos_type Position () const
 
void Read (bool &b)
 
void Read (IsoString &s)
 
void Read (String &s)
 
template<typename T >
void Read (T &x)
 
virtual void Read (void *buffer, fsize_type len)
 
template<typename T >
void ReadArray (T *a, size_type n)
 
template<typename T >
void ReadI32 (T &x)
 
template<typename T >
void ReadI64 (T &x)
 
template<typename T >
void ReadUI32 (T &x)
 
template<typename T >
void ReadUI64 (T &x)
 
virtual void Resize (fsize_type length)
 
void Rewind ()
 
fpos_type Seek (fpos_type dist, seek_mode mode=SeekMode::FromCurrent)
 
fpos_type SeekEnd ()
 
virtual void SetPosition (fpos_type pos)
 
virtual fsize_type Size () const
 
void Write (const bool &b)
 
void Write (const char *i, const char *j)
 
void Write (const char *s)
 
void Write (const char16_type *i, const char16_type *j)
 
void Write (const char16_type *s)
 
void Write (const IsoString &s)
 
void Write (const String &s)
 
template<typename T >
void Write (const T &x)
 
virtual void Write (const void *buffer, fsize_type len)
 
template<typename T >
void WriteArray (const T *a, size_type n)
 
template<typename T >
void WriteI32 (const T &x)
 
template<typename T >
void WriteI64 (const T &x)
 
template<typename T >
void WriteUI32 (const T &x)
 
template<typename T >
void WriteUI64 (const T &x)
 

Static Public Member Functions

static String AppendToName (const String &filePath, const String &postfix)
 
static String ChangeExtension (const String &filePath, const String &ext)
 
static void CopyFile (const String &targetFilePath, const String &sourceFilePath, File::Progress *progress=nullptr)
 
static void CopyLink (const String &targetLinkPath, const String &sourceLinkPath)
 
static void CopyTimesAndPermissions (const String &targetPath, const String &sourcePath)
 
static void CreateDirectory (const String &dirPath, bool createIntermediateDirectories=true)
 
static File CreateFile (const String &path)
 
static File CreateFileForWriting (const String &path)
 
static bool DirectoryExists (const String &dirPath)
 
static UniqueFileChecks EnsureNewUniqueDirectory (String &dirPath)
 
static UniqueFileChecks EnsureNewUniqueFile (String &filePath, bool canOverwrite=false)
 
static bool Exists (const String &filePath)
 
static String ExtractCompleteSuffix (const String &path)
 
static String ExtractDirectory (const String &path)
 
static String ExtractDrive (const String &path)
 
static String ExtractExtension (const String &path)
 
static String ExtractName (const String &path)
 
static String ExtractNameAndExtension (const String &path)
 
static String ExtractNameAndSuffix (const String &path)
 
static String ExtractSuffix (const String &path)
 
static IsoString FileURI (const String &path)
 
static size_type FindCompleteSuffix (const String &path)
 
static size_type FindDrive (const String &path)
 
static size_type FindExtension (const String &path)
 
static size_type FindName (const String &path)
 
static size_type FindSuffix (const String &path)
 
static String FullPath (const String &path)
 
static uint64 GetAvailableSpace (const String &dirPath, uint64 *totalBytes=nullptr, uint64 *freeBytes=nullptr)
 
static String HomeDirectory ()
 
static bool IsReadOnly (const String &filePath)
 
static void Move (const String &filePath, const String &newFilePath)
 
static void MoveFile (const String &targetFilePath, const String &sourceFilePath, File::Progress *progress=nullptr)
 
static File OpenFileForReading (const String &path)
 
static File OpenFileForReadWrite (const String &path)
 
static File OpenOrCreateFile (const String &path)
 
static String PrependToName (const String &filePath, const String &prefix)
 
template<typename E >
static void Read (Flags< E > &f)
 
static ByteArray ReadFile (const String &filePath)
 
static IsoStringList ReadLines (const String &filePath, ReadTextOptions options=ReadTextOptions())
 
static IsoString ReadTextFile (const String &filePath)
 
template<typename E >
static void ReadUI32 (Flags< E > &f)
 
static void Remove (const String &filePath)
 
static void RemoveDirectory (const String &dirPath)
 
static bool SameDevice (const String &path1, const String &path2)
 
static bool SameFile (const String &path1, const String &path2)
 
static size_type ScanLines (const String &filePath, bool(*callback)(char *, void *), void *data=nullptr, ReadTextOptions options=ReadTextOptions())
 
static void SetPermissions (const String &targetPath, FileAttributes permissions)
 
static void SetReadOnly (const String &filePath, bool rdOnly=true)
 
static void SetReadWrite (const String &filePath)
 
static String SizeAsString (fsize_type sizeInBytes, int precision=3, bool alsoShowBytes=false)
 
static String SystemCacheDirectory ()
 
static String SystemTempDirectory ()
 
static String UniqueFileName (const String &directory=String(), int n=12, const String &prefix=String(), const String &postfix=String())
 
static String UnixPathToWindows (const String &path)
 
static String WindowsPathToUnix (const String &path)
 
template<typename E >
static void Write (Flags< E > f)
 
static void WriteFile (const String &filePath, const ByteArray &contents)
 
static void WriteFile (const String &filePath, const ByteArray &contents, size_type start, size_type size)
 
static void WriteFile (const String &filePath, const void *data, size_type size)
 
static void WriteTextFile (const String &filePath, const IsoString &text)
 
template<typename E >
static void WriteUI32 (Flags< E > f)
 

Detailed Description

TODO: Write a detailed description for File.

Definition at line 343 of file File.h.

Member Typedef Documentation

◆ handle

using pcl::File::handle = void*

Represents a low-level opaque handle to a file.

Definition at line 350 of file File.h.

◆ seek_mode

using pcl::File::seek_mode = SeekMode::value_type

Represents a file seek mode.

Definition at line 355 of file File.h.

Constructor & Destructor Documentation

◆ File() [1/4]

pcl::File::File ( )
inline

Constructs a File object that does not represent an existing file.

Definition at line 713 of file File.h.

◆ File() [2/4]

pcl::File::File ( const String path,
FileModes  mode 
)
inline

Constructs a File object that opens a file at a given path with the specified mode.

Definition at line 722 of file File.h.

References pcl::GenericString< T, R, A >::IsEmpty().

◆ File() [3/4]

pcl::File::File ( File &&  x)
inline

Move constructor.

Definition at line 732 of file File.h.

◆ ~File()

virtual pcl::File::~File ( )
inlinevirtual

Virtual destructor. If this instance represents an open file, it is closed automatically upon destruction.

Definition at line 763 of file File.h.

◆ File() [4/4]

pcl::File::File ( const File )
delete

Copy constructor. This constructor is disabled because files are unique objects.

Member Function Documentation

◆ AppendToName()

static String pcl::File::AppendToName ( const String filePath,
const String postfix 
)
static

Appends a postfix string to the current file name in the specified filePath. Returns the resulting path.

◆ CanRead()

virtual bool pcl::File::CanRead ( ) const
inlinevirtual

Returns true iff this file allows read access.

Definition at line 820 of file File.h.

◆ CanWrite()

virtual bool pcl::File::CanWrite ( ) const
inlinevirtual

Returns true iff this file allows write access.

Definition at line 828 of file File.h.

◆ ChangeExtension()

static String pcl::File::ChangeExtension ( const String filePath,
const String ext 
)
static

Changes the current file extension in filePath to a new extension ext. If it is not an empty string, the specified extension must include the initial dot separator.

If the specified new extension ext is an empty string, this function returns filePath with its extension (if any) removed.

Returns the resulting path after changing the file extension to the specified value.

◆ Close()

virtual void pcl::File::Close ( )
virtual

Closes an open file. If this file has not been opened, calling this member function has no effect.

◆ CopyFile()

static void pcl::File::CopyFile ( const String targetFilePath,
const String sourceFilePath,
File::Progress progress = nullptr 
)
static

Copies a single file.

Parameters
targetFilePathPath to the target file, which must not exist. If the specified file exists, an Error exception will be thrown.
sourceFilePathPath to the source file. This file must exist and must be different from the specified target file.
progressPointer 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 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 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.

◆ CopyLink()

static void pcl::File::CopyLink ( const String targetLinkPath,
const String sourceLinkPath 
)
static

Copies a symbolic link.

Parameters
targetLinkPathPath 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.
sourceLinkPathPath 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, 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.

◆ CopyTimesAndPermissions()

static void pcl::File::CopyTimesAndPermissions ( const String targetPath,
const String sourcePath 
)
static

Copies access and modification times and access permissions from one file or directory item to another.

Parameters
targetPathPath to the target item whose times and permissions will be changed.
sourcePathPath to the source item whose times and permissions will be copied to the target item.

◆ Create()

virtual void pcl::File::Create ( const String path)
inlinevirtual

Creates a file at the specified path for exclusive read/write access. If a file already exists at the same path, its contents will be truncated to zero length.

Definition at line 1326 of file File.h.

Referenced by CreateFile().

◆ CreateDirectory()

static void pcl::File::CreateDirectory ( const String dirPath,
bool  createIntermediateDirectories = true 
)
static

Creates a new directory at the specified dirPath.

If createIntermediateDirectories is true (the default value) and dirPath specifies one or more parent directories that don't exist, they are created automatically.

◆ CreateFile()

static File pcl::File::CreateFile ( const String path)
inlinestatic

Returns a newly created file at the specified path, ready for exclusive read/write access. If a file already exists at the same path, its contents will be truncated to zero length.

Definition at line 1336 of file File.h.

References Create().

◆ CreateFileForWriting()

static File pcl::File::CreateFileForWriting ( const String path)
inlinestatic

Returns a newly created file at the specified path, ready for exclusive write-only access. If a file already exists at the same path, its contents will be truncated to zero length.

Definition at line 1358 of file File.h.

References CreateForWriting().

◆ CreateForWriting()

virtual void pcl::File::CreateForWriting ( const String path)
inlinevirtual

Creates a file at the specified path for exclusive write-only access. If a file already exists at the same path, its contents will be truncated to zero length.

Definition at line 1348 of file File.h.

Referenced by CreateFileForWriting().

◆ DirectoryExists()

static bool pcl::File::DirectoryExists ( const String dirPath)
static

Returns true iff a directory at the specified dirPath exists.

◆ EnsureNewUniqueDirectory()

static UniqueFileChecks pcl::File::EnsureNewUniqueDirectory ( String dirPath)
static

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.

Parameters
[in,out]dirPathPath 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 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 exists member indicates whether the specified dirPath corresponds to an already existing directory upon calling this function, and the overwrite member is always false, reflecting the fact that a directory cannot be overwritten.

If the specified directory already exists, the string referenced by 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:

String dirPath = "/path/to/foobar"; // this directory exists
static UniqueFileChecks EnsureNewUniqueDirectory(String &dirPath)

then the 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 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 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.

◆ EnsureNewUniqueFile()

static UniqueFileChecks pcl::File::EnsureNewUniqueFile ( String filePath,
bool  canOverwrite = false 
)
static

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.

Parameters
[in,out]filePathPath 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 canOverwrite parameter and the description below for further details.
canOverwriteIf this parameter is false and the specified filePath corresponds to an already existing file, the string referenced by 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 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 filePath variable is guaranteed to exist, either because such file already existed when the function was called and the 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 exists member indicates whether the specified filePath corresponds to an already existing file upon calling this function, and the overwrite member is true iff an existing file can be overwritten because the specified canOverwrite parameter is true.

When the 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:

String filePath = "/path/to/foo.bar"; // this file exists
EnsureNewUniqueFile( filePath );
static UniqueFileChecks EnsureNewUniqueFile(String &filePath, bool canOverwrite=false)

then the 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 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.

◆ Exists()

static bool pcl::File::Exists ( const String filePath)
static

Returns true iff a file at the specified filePath exists.

◆ ExtractCompleteSuffix()

static String pcl::File::ExtractCompleteSuffix ( const String path)
static

Extracts the complete file suffix from the specified path.

Returns the extracted complete suffix, or an empty string if no file suffix was found. The returned string includes the initial dot separator.

The complete suffix is the ending substring of the file identifier in the specified path, starting with the first occurrence of a dot character. For example, in 'foo.tar.gz' the complete suffix is '.tar.gz'.

See also
ExtractSuffix()

◆ ExtractDirectory()

static String pcl::File::ExtractDirectory ( const String path)
static

Extracts a directory specification from the specified 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'.

◆ ExtractDrive()

static String pcl::File::ExtractDrive ( const String path)
static

Extracts a Windows drive specification from the specified 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.

◆ ExtractExtension()

static String pcl::File::ExtractExtension ( const String path)
static

Extracts a file extension from the specified path.

Returns the extracted extension, or an empty string if no file extension was found. The returned extension includes the initial dot separator.

Examples:

In '/foo/bar.tar.gz' the extension is '.gz'. In 'C:/Foo/Bar.txt' the extension is '.txt'.

See also
ExtractCompleteSuffix()

◆ ExtractName()

static String pcl::File::ExtractName ( const String path)
static

Extracts a file name from the specified 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'.

◆ ExtractNameAndExtension()

static String pcl::File::ExtractNameAndExtension ( const String path)
static

Extracts the file name and extension from the specified path. Calling this member function is functionally equivalent to:

File::ExtractName( path ) + File::ExtractExtension( path )

◆ ExtractNameAndSuffix()

static String pcl::File::ExtractNameAndSuffix ( const String path)
inlinestatic

A synonym for ExtractNameAndExtension().

Definition at line 2172 of file File.h.

◆ ExtractSuffix()

static String pcl::File::ExtractSuffix ( const String path)
inlinestatic

A synonym for ExtractExtension().

Definition at line 2141 of file File.h.

◆ FileName()

const String& pcl::File::FileName ( ) const
inline

Returns the path of the file represented by this File object.

Deprecated:
This member function has been deprecated. Use FilePath() in newly produced code.

Definition at line 804 of file File.h.

◆ FilePath()

const String& pcl::File::FilePath ( ) const
inline

Returns the path of the file represented by this File object. Returned file paths are always absolute, full file paths.

Definition at line 793 of file File.h.

◆ FileURI()

static IsoString pcl::File::FileURI ( const String path)
static

Returns a valid URI with the "file" scheme corresponding to the specified local 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 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

References:

https://tools.ietf.org/html/rfc1738
https://tools.ietf.org/html/rfc8089

◆ FindCompleteSuffix()

static size_type pcl::File::FindCompleteSuffix ( const String path)
static

Finds the complete file suffix in the specified path.

Returns the character index position of the complete suffix found, or String::notFound.

The complete suffix is the rightmost substring of the path starting with the first occurrence of a dot character. For example, in 'foo.tar.gz' the complete suffix is '.tar.gz'.

See also
FindSuffix()

◆ FindDrive()

static size_type pcl::File::FindDrive ( const String path)
static

Finds a Windows drive specification in the specified 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.

◆ FindExtension()

static size_type pcl::File::FindExtension ( const String path)
static

Finds a file extension in the specified path.

Returns the character index position of the extension found, or String::notFound.

The file extension, or file suffix, is the rightmost substring of path starting with the last occurrence of a dot character. For example, in 'foo.tar.gz' the file extension is '.gz'.

See also
FindCompleteSuffix()

◆ FindName()

static size_type pcl::File::FindName ( const String path)
static

Finds a file name in the specified 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'.

◆ FindSuffix()

static size_type pcl::File::FindSuffix ( const String path)
inlinestatic

A synonym for FindExtension().

Definition at line 2064 of file File.h.

◆ Flush()

void pcl::File::Flush ( )

Commits any pending write operations.

◆ FullPath()

◆ GetAvailableSpace()

static uint64 pcl::File::GetAvailableSpace ( const String dirPath,
uint64 totalBytes = nullptr,
uint64 freeBytes = nullptr 
)
static

Retrieves the storage space available on the device that supports a specified directory.

Parameters
dirPathA 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.
[out]totalBytesIf non-null, the address of a variable that receives the total capacity in bytes of the device that supports the specified directory.
[out]freeBytesIf 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.

◆ HomeDirectory()

static String pcl::File::HomeDirectory ( )
static

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.

◆ IsEOF()

bool pcl::File::IsEOF ( ) const
inline

Returns true iff the file pointer has been moved beyond the end of the file.

Definition at line 880 of file File.h.

◆ IsOpen()

bool pcl::File::IsOpen ( ) const
inline

Returns true iff this File object represents an open file.

Definition at line 784 of file File.h.

◆ IsReadOnly()

static bool pcl::File::IsReadOnly ( const String filePath)
static

Returns true iff the file at filePath exists and the current user has read-only access to it.

◆ Mode()

FileModes pcl::File::Mode ( ) const
inline

Returns the file mode for this File object.

Definition at line 812 of file File.h.

◆ Move()

static void pcl::File::Move ( const String filePath,
const String newFilePath 
)
static

Moves and/or renames a file.

Parameters
filePathCurrent path of the file to move/rename
newFilePathNew path. If the directory in newFilePath is the same as in 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.

◆ MoveFile()

static void pcl::File::MoveFile ( const String targetFilePath,
const String sourceFilePath,
File::Progress progress = nullptr 
)
static

Moves a single file.

Parameters
targetFilePathPath to the target file, which must not exist. If the specified file exists, an Error exception will be thrown.
sourceFilePathPath to the source file. This file must exist and must be different from the specified target file.
progressPointer 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 nullptr.

For file move operations within the same physical device, this function implements a simple rename operation. In these cases, the 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 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.

◆ Open()

virtual void pcl::File::Open ( const String path,
FileModes  mode = FileMode::Read|FileMode::Open 
)
virtual

Opens or creates a file.

Parameters
pathThe path to the file to be opened or created.
modeDesired file access, share (Windows only) and opening/creation mode. By default, an existing file will be opened for (exclusive on Windows) read-only access.

◆ OpenFileForReading()

static File pcl::File::OpenFileForReading ( const String path)
inlinestatic

Returns an open existing file at the specified 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').

Definition at line 1295 of file File.h.

References OpenForReading().

◆ OpenFileForReadWrite()

static File pcl::File::OpenFileForReadWrite ( const String path)
inlinestatic

Returns an open existing file at the specified path, ready for exclusive read/write access.

Definition at line 1314 of file File.h.

References OpenForReadWrite().

◆ OpenForReading()

virtual void pcl::File::OpenForReading ( const String path)
inlinevirtual

Opens an existing file at the specified 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').

Definition at line 1284 of file File.h.

Referenced by OpenFileForReading().

◆ OpenForReadWrite()

virtual void pcl::File::OpenForReadWrite ( const String path)
inlinevirtual

Opens an existing file at path for exclusive read/write access.

Definition at line 1305 of file File.h.

Referenced by OpenFileForReadWrite().

◆ OpenOrCreate()

void pcl::File::OpenOrCreate ( const String path)
inline

Opens a file at the specified path if it exists, or creates it otherwise. The file will be opened in exclusive read/write mode.

Definition at line 1369 of file File.h.

Referenced by OpenOrCreateFile().

◆ OpenOrCreateFile()

static File pcl::File::OpenOrCreateFile ( const String path)
inlinestatic

Returns an open file at the specified path if it already exists, or a newly created file otherwise, ready for exclusive read/write access.

Definition at line 1378 of file File.h.

References OpenOrCreate().

◆ operator=() [1/2]

File& pcl::File::operator= ( const File )
delete

Copy assignment. This operator is disabled because files are unique objects.

◆ operator=() [2/2]

File& pcl::File::operator= ( File &&  x)
inline

Move assignment operator. Returns a reference to this object.

Definition at line 744 of file File.h.

◆ OutText() [1/6]

void pcl::File::OutText ( const char *  i,
const char *  j 
)
inline

Writes a sequence of 8-bit characters, defined by the range [i,j), as plain text.

Definition at line 1145 of file File.h.

◆ OutText() [2/6]

void pcl::File::OutText ( const char *  s)
inline

Writes a null-terminated 8-bit string as plain text.

Definition at line 1154 of file File.h.

References pcl::IsoCharTraits::Length().

◆ OutText() [3/6]

void pcl::File::OutText ( const char16_type i,
const char16_type j 
)
inline

Writes a sequence of UTF-16 characters, defined by the range [i,j), as plain text.

Definition at line 1171 of file File.h.

◆ OutText() [4/6]

void pcl::File::OutText ( const char16_type s)
inline

Writes a null-terminated UTF-16 string as plain text.

Definition at line 1180 of file File.h.

References pcl::CharTraits::Length().

◆ OutText() [5/6]

void pcl::File::OutText ( const IsoString s)
inline

Writes a dynamic 8-bit string as plain text.

Definition at line 1162 of file File.h.

References pcl::GenericString< T, R, A >::Begin(), and pcl::GenericString< T, R, A >::End().

◆ OutText() [6/6]

void pcl::File::OutText ( const String s)
inline

Writes a dynamic UTF16 string as plain text.

Definition at line 1188 of file File.h.

References pcl::GenericString< T, R, A >::Begin(), and pcl::GenericString< T, R, A >::End().

◆ OutTextLn() [1/7]

void pcl::File::OutTextLn ( )
inline

Writes an 8-bit newline character ('
').

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:

OutTextLn( String() );
void OutTextLn()
Definition: File.h:1222


to generate a newline in UTF-16 format.

Definition at line 1222 of file File.h.

◆ OutTextLn() [2/7]

void pcl::File::OutTextLn ( const char *  i,
const char *  j 
)
inline

Writes a sequence of 8-bit characters, defined by the range [i,j), as plain text. Then writes a newline character.

Definition at line 1197 of file File.h.

◆ OutTextLn() [3/7]

void pcl::File::OutTextLn ( const char *  s)
inline

Writes a null-terminated 8-bit string as plain text and appends a newline character.

Definition at line 1206 of file File.h.

◆ OutTextLn() [4/7]

void pcl::File::OutTextLn ( const char16_type i,
const char16_type j 
)
inline

Writes a sequence of UTF-16 characters, defined by the range [i,j), as plain text. Then writes a newline character.

Definition at line 1240 of file File.h.

◆ OutTextLn() [5/7]

void pcl::File::OutTextLn ( const char16_type s)
inline

Writes a null-terminated UTF-16 string as plain text and appends a newline character.

Definition at line 1249 of file File.h.

◆ OutTextLn() [6/7]

void pcl::File::OutTextLn ( const IsoString s)
inline

Writes a dynamic 8-bit string as plain text and appends a newline character.

Definition at line 1231 of file File.h.

◆ OutTextLn() [7/7]

void pcl::File::OutTextLn ( const String s)
inline

Writes a dynamic UTF16 string as plain text and appends a newline character.

Definition at line 1258 of file File.h.

◆ Position()

virtual fpos_type pcl::File::Position ( ) const
virtual

Returns the current file position, relative to the beginning of the file represented by this File object.

◆ PrependToName()

static String pcl::File::PrependToName ( const String filePath,
const String prefix 
)
static

Prepends a prefix string to the current file name in the specified filePath. Returns the resulting path.

◆ Read() [1/6]

void pcl::File::Read ( bool &  b)
inline

Reads a boolean variable.

This function reads a 32-bit integer and assigns true to the variable b iff the read number is nonzero.

Definition at line 1027 of file File.h.

◆ Read() [2/6]

template<typename E >
static void pcl::File::Read ( Flags< E > &  f)
inlinestatic

Reads a set of flags f.

Definition at line 1107 of file File.h.

◆ Read() [3/6]

void pcl::File::Read ( IsoString s)

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.

◆ Read() [4/6]

void pcl::File::Read ( String 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.

◆ Read() [5/6]

template<typename T >
void pcl::File::Read ( T &  x)
inline

Reads an object x of type T.

Definition at line 904 of file File.h.

◆ Read() [6/6]

virtual void pcl::File::Read ( void *  buffer,
fsize_type  len 
)
virtual

Reads a contiguous block of len bytes into the specified buffer.

◆ ReadArray()

template<typename T >
void pcl::File::ReadArray ( T *  a,
size_type  n 
)
inline

Reads a set of n consecutive objects of type T into the array pointed to by a.

This is a convenience member function, equivalent to Read( (void*)a, n*sizeof( T ) )

Definition at line 917 of file File.h.

◆ ReadFile()

static ByteArray pcl::File::ReadFile ( const String filePath)
static

Reads the contents of a file at the specified filePath and returns them as a ByteArray object.

◆ ReadI32()

template<typename T >
void pcl::File::ReadI32 ( T &  x)
inline

Reads a numeric variable as a 32-bit signed integer.

Definition at line 926 of file File.h.

◆ ReadI64()

template<typename T >
void pcl::File::ReadI64 ( T &  x)
inline

Reads a numeric variable as a 64-bit signed integer.

Definition at line 944 of file File.h.

◆ ReadLines()

static IsoStringList pcl::File::ReadLines ( const String filePath,
ReadTextOptions  options = ReadTextOptions() 
)
static

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.

Parameters
filePathPath to the source file from which text lines will be read.
optionsOptional 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).

◆ ReadTextFile()

static IsoString pcl::File::ReadTextFile ( const String filePath)
static

Reads the contents of a file at the specified 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.

◆ ReadUI32() [1/2]

template<typename E >
static void pcl::File::ReadUI32 ( Flags< E > &  f)
inlinestatic

Reads a set of flags f as an unsigned 32-bit integer.

Definition at line 1116 of file File.h.

◆ ReadUI32() [2/2]

template<typename T >
void pcl::File::ReadUI32 ( T &  x)
inline

Reads a numeric variable as a 32-bit unsigned integer.

Definition at line 935 of file File.h.

Referenced by pcl::GenericImage< P >::Read().

◆ ReadUI64()

template<typename T >
void pcl::File::ReadUI64 ( T &  x)
inline

Reads a numeric variable as a 64-bit unsigned integer.

Definition at line 953 of file File.h.

◆ Remove()

static void pcl::File::Remove ( const String filePath)
static

Removes an existing file at the specified filePath.

◆ RemoveDirectory()

static void pcl::File::RemoveDirectory ( const String dirPath)
static

Removes an existing empty directory at the specified dirPath.

The specified directory must be empty, or this function will fail.

◆ Resize()

virtual void pcl::File::Resize ( fsize_type  length)
virtual

Truncates or extends this file to the specified length.

◆ Rewind()

void pcl::File::Rewind ( )
inline

Moves the file pointer to the beginning of this file.

This is a convenience member function, equivalent to SetPosition( 0 )

Definition at line 871 of file File.h.

◆ SameDevice()

static bool pcl::File::SameDevice ( const String path1,
const String path2 
)
static

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).

◆ SameFile()

static bool pcl::File::SameFile ( const String path1,
const String path2 
)
static

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).

◆ ScanLines()

static size_type pcl::File::ScanLines ( const String filePath,
bool(*)(char *, void *)  callback,
void *  data = nullptr,
ReadTextOptions  options = ReadTextOptions() 
)
static

Iterates a function through all existing text lines in a file.

Parameters
filePathPath 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.
callbackCallback 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 data argument. The function will return true if the process can continue for the next text line; false to stop the iteration.
dataA void* that will be passed to the callback function as its second argument on each call. The default value is nullptr.
optionsOptional 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).

◆ Seek()

fpos_type pcl::File::Seek ( fpos_type  dist,
seek_mode  mode = SeekMode::FromCurrent 
)

Moves the file pointer. Returns the resulting pointer position from the file beginning.

Parameters
distDistance to move in bytes.
modeSeek mode. See the SeekMode namespace for valid modes.

◆ SeekEnd()

fpos_type pcl::File::SeekEnd ( )
inline

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 )

Definition at line 861 of file File.h.

◆ SetPermissions()

static void pcl::File::SetPermissions ( const String targetPath,
FileAttributes  permissions 
)
static

Changes the access permissions of a file or directory.

Parameters
targetPathPath to the existing file or directory whose permissions will be modified.
permissionsAn 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.

◆ SetPosition()

virtual void pcl::File::SetPosition ( fpos_type  pos)
virtual

Sets the file position relative to the file beginning.

◆ SetReadOnly()

static void pcl::File::SetReadOnly ( const String filePath,
bool  rdOnly = true 
)
static

Enables or disables read-only access to a file at the specified filePath.

◆ SetReadWrite()

static void pcl::File::SetReadWrite ( const String filePath)
inlinestatic

Disables or enables read-only access to a file at the specified filePath.

This is a convenience member function, equivalent to SetReadOnly( filePath, false )

Definition at line 1561 of file File.h.

◆ Size()

virtual fsize_type pcl::File::Size ( ) const
virtual

Returns the length in bytes of this file.

◆ SizeAsString()

static String pcl::File::SizeAsString ( fsize_type  sizeInBytes,
int  precision = 3,
bool  alsoShowBytes = false 
)
static

Returns a readable textual representation of a file size with automatic units conversion.

Parameters
sizeInBytesThe file size in bytes.
precisionThe number of decimal digits used to represent floating point numbers. The default value is 3.
alsoShowBytesWhether to add the size in bytes to the string representation, irrespective of the units used. The default value is false.

Examples:

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"
static String SizeAsString(fsize_type sizeInBytes, int precision=3, bool alsoShowBytes=false)

◆ SystemCacheDirectory()

static String pcl::File::SystemCacheDirectory ( )
static

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.

◆ SystemTempDirectory()

static String pcl::File::SystemTempDirectory ( )
static

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.

◆ UniqueFileName()

static String pcl::File::UniqueFileName ( const String directory = String(),
int  n = 12,
const String prefix = String(),
const String postfix = String() 
)
static

Returns a nonexistent, randomly generated file name.

Parameters
directoryName 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.
nNumber of random characters in the generated file name. Must be at least five characters. The default value is twelve characters.
prefixAn optional prefix that will be prepended to the generated file name.
postfixAn 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 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.

◆ UnixPathToWindows()

static String pcl::File::UnixPathToWindows ( const String path)
static

Converts a path from UNIX to Windows. Replaces all occurrences of the '/' UNIX separator with the '\' Windows separator.

◆ WindowsPathToUnix()

static String pcl::File::WindowsPathToUnix ( const String path)
static

Converts a path from Windows to UNIX syntax. Replaces all occurrences of the '\' Windows separator with the '/' UNIX separator.

◆ Write() [1/10]

void pcl::File::Write ( const bool &  b)
inline

Writes a boolean variable.

This function writes a 32-bit integer with a value of 1 (one) if the variable b is true, zero otherwise.

Definition at line 1038 of file File.h.

◆ Write() [2/10]

void pcl::File::Write ( const char *  i,
const char *  j 
)

Writes a sequence of 8-bit characters, defined by the range [i,j), as binary data.

◆ Write() [3/10]

void pcl::File::Write ( const char *  s)
inline

Writes a null-terminated 8-bit string as binary data.

Definition at line 1066 of file File.h.

◆ Write() [4/10]

void pcl::File::Write ( const char16_type i,
const char16_type j 
)

Writes a sequence of UTF-16 characters, defined by the range [i,j), as binary data.

◆ Write() [5/10]

void pcl::File::Write ( const char16_type s)
inline

Writes a null-terminated string of UTF-16 characters as binary data.

Definition at line 1088 of file File.h.

◆ Write() [6/10]

void pcl::File::Write ( const IsoString s)
inline

Writes a dynamic 8-bit string as binary data.

Definition at line 1074 of file File.h.

◆ Write() [7/10]

void pcl::File::Write ( const String s)
inline

Writes a dynamic UTF-16 string as binary data.

Definition at line 1096 of file File.h.

◆ Write() [8/10]

template<typename T >
void pcl::File::Write ( const T &  x)
inline

Writes an object x of type T.

Definition at line 967 of file File.h.

◆ Write() [9/10]

virtual void pcl::File::Write ( const void *  buffer,
fsize_type  len 
)
virtual

Writes a contiguous block of len bytes from the specified buffer.

◆ Write() [10/10]

template<typename E >
static void pcl::File::Write ( Flags< E >  f)
inlinestatic

Writes a set of flags f.

Definition at line 1125 of file File.h.

◆ WriteArray()

template<typename T >
void pcl::File::WriteArray ( const T *  a,
size_type  n 
)
inline

Writes a set of n consecutive objects of type T from the array pointed to by a.

This is a convenience member function, equivalent to Write( (const void*)a, n*sizeof( T ) )

Definition at line 980 of file File.h.

◆ WriteFile() [1/3]

static void pcl::File::WriteFile ( const String filePath,
const ByteArray contents 
)
static

Creates a file with the specified contents.

Parameters
filePathPath to the file that will be created.
contentsReference 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:

void CopyFile( const String& targetFilePath, const String& sourceFilePath )
{
File::WriteFile( targetFilePath, File::ReadFile( sourceFilePath ) );
}
static void CopyFile(const String &targetFilePath, const String &sourceFilePath, File::Progress *progress=nullptr)
static void WriteFile(const String &filePath, const ByteArray &contents)
static ByteArray ReadFile(const String &filePath)
Warning
If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ WriteFile() [2/3]

static void pcl::File::WriteFile ( const String filePath,
const ByteArray contents,
size_type  start,
size_type  size 
)
static

Creates a file with a subset of a ByteArray container.

Parameters
filePathPath to the file that will be created.
contentsReference to a ByteArray object providing the contents that will be written to the newly created file.
startZero-based index of the first byte to be written.
sizeNumber 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.

◆ WriteFile() [3/3]

static void pcl::File::WriteFile ( const String filePath,
const void *  data,
size_type  size 
)
static

Creates a file with the specified contents.

Parameters
filePathPath to the file that will be created.
dataPointer to the first byte to be written to the newly created file.
sizeNumber of contiguous bytes, starting from data, to be written.
Warning
If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ WriteI32()

template<typename T >
void pcl::File::WriteI32 ( const T &  x)
inline

Writes a numeric variable as a 32-bit signed integer.

Definition at line 989 of file File.h.

◆ WriteI64()

template<typename T >
void pcl::File::WriteI64 ( const T &  x)
inline

Writes a numeric variable as a 64-bit signed integer.

Definition at line 1007 of file File.h.

◆ WriteTextFile()

static void pcl::File::WriteTextFile ( const String filePath,
const IsoString text 
)
static

Creates a file with the specified plain text content.

Parameters
filePathPath to the file that will be created.
textReference 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.

◆ WriteUI32() [1/2]

template<typename T >
void pcl::File::WriteUI32 ( const T &  x)
inline

Writes a numeric variable as a 32-bit unsigned integer.

Definition at line 998 of file File.h.

◆ WriteUI32() [2/2]

template<typename E >
static void pcl::File::WriteUI32 ( Flags< E >  f)
inlinestatic

Writes a set of flags f as an unsigned 32-bit integer.

Definition at line 1134 of file File.h.

◆ WriteUI64()

template<typename T >
void pcl::File::WriteUI64 ( const T &  x)
inline

Writes a numeric variable as a 64-bit unsigned integer.

Definition at line 1016 of file File.h.


The documentation for this class was generated from the following file: