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
typedef void *	handle

typedef SeekMode::value_type	seek_mode

Public Member Functions
	File ()

	File (const String &path, FileModes mode)

	File (File &&x)

	File (const File &)=delete

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 String &	FileName () const

const String &	FilePath () 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)

File &	operator= (File &&x)

File &	operator= (const File &)=delete

void	OutText (const char i, const char j)

void	OutText (const char *s)

void	OutText (const IsoString &s)

void	OutText (const char16_type i, const char16_type j)

void	OutText (const char16_type *s)

void	OutText (const String &s)

void	OutTextLn (const char i, const char j)

void	OutTextLn (const char *s)

void	OutTextLn ()

void	OutTextLn (const IsoString &s)

void	OutTextLn (const char16_type i, const char16_type j)

void	OutTextLn (const char16_type *s)

void	OutTextLn (const String &s)

virtual fpos_type	Position () const

virtual void	Read (void *buffer, fsize_type len)

template<typename T >
void	Read (T &x)

void	Read (bool &b)

void	Read (IsoString &s)

void	Read (String &s)

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

virtual void	Write (const void *buffer, fsize_type len)

template<typename T >
void	Write (const T &x)

void	Write (const bool &b)

void	Write (const char i, const char j)

void	Write (const char *s)

void	Write (const IsoString &s)

void	Write (const char16_type i, const char16_type j)

void	Write (const char16_type *s)

void	Write (const String &s)

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 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 496 of file File.h.

Member Typedef Documentation

◆ handle

typedef void* pcl::File::handle

Represents a low-level opaque handle to a file.

Definition at line 503 of file File.h.

◆ seek_mode

typedef SeekMode::value_type pcl::File::seek_mode

Represents a file seek mode.

Definition at line 508 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 866 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 875 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 885 of file File.h.

◆ ~File()

virtual pcl::File::~File ( )

inlinevirtual

Destroys a File object. If this instance represents an open file, it is closed upon destruction.

Definition at line 916 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 973 of file File.h.

◆ CanWrite()

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

inlinevirtual

Returns true iff this file allows write access.

Definition at line 981 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

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

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

targetPath	Path to the target item whose times and permissions will be changed.
sourcePath	Path 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 1479 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 1489 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 1511 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 1501 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.

◆ 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()

Referenced by pcl::FileInfo::CompleteSuffix().

◆ 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'.

Referenced by pcl::FileInfo::Directory().

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

Referenced by pcl::FileInfo::Drive().

◆ 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()

Referenced by pcl::FileInfo::Extension().

◆ 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'.

Referenced by pcl::FileInfo::Name().

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

Referenced by pcl::FileInfo::NameAndExtension().

◆ ExtractNameAndSuffix()

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

inlinestatic

A synonym for ExtractNameAndExtension().

Definition at line 2221 of file File.h.

◆ ExtractSuffix()

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

inlinestatic

A synonym for ExtractExtension().

Definition at line 2190 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 957 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 946 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 2113 of file File.h.

◆ Flush()

void pcl::File::Flush ( )

Commits any pending write operations.

◆ FullPath()

static String pcl::File::FullPath ( const String & path )

static

Returns the full, absolute local path to the specified path.

Referenced by pcl::DrizzleData::SetAlignmentTargetFilePath(), pcl::DrizzleData::SetCFASourceFilePath(), pcl::LocalNormalizationData::SetReferenceFilePath(), pcl::DrizzleData::SetSourceFilePath(), and pcl::LocalNormalizationData::SetTargetFilePath().

◆ 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

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

◆ 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 1033 of file File.h.

◆ IsOpen()

bool pcl::File::IsOpen ( ) const

inline

Returns true iff this File object represents an open file.

Definition at line 937 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 965 of file File.h.

◆ Move()

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

static

Moves and/or renames a file.

Parameters

filePath	Current path of the file to move/rename
newFilePath	New 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

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

path	The path to the file to be opened or created.
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.

◆ 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 1448 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 1467 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 1437 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 1458 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 1522 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 1531 of file File.h.

References OpenOrCreate().

◆ operator=() [1/2]

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

inline

Move assignment operator. Returns a reference to this object.

Definition at line 897 of file File.h.

◆ operator=() [2/2]

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

delete

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

◆ 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 1298 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 1307 of file File.h.

References pcl::IsoCharTraits::Length().

◆ OutText() [3/6]

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

inline

Writes a dynamic 8-bit string as plain text.

Definition at line 1315 of file File.h.

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

◆ OutText() [4/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 1324 of file File.h.

◆ OutText() [5/6]

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

inline

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

Definition at line 1333 of file File.h.

References pcl::CharTraits::Length().

◆ OutText() [6/6]

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

inline

Writes a dynamic UTF16 string as plain text.

Definition at line 1341 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	(	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 1350 of file File.h.

◆ OutTextLn() [2/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 1359 of file File.h.

◆ OutTextLn() [3/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() );

to generate a newline in UTF-16 format.

Definition at line 1375 of file File.h.

◆ OutTextLn() [4/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 1384 of file File.h.

◆ OutTextLn() [5/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 1393 of file File.h.

◆ OutTextLn() [6/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 1402 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 1411 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]

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

virtual

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

◆ Read() [2/6]

template<typename T >

void pcl::File::Read ( T & x )

inline

Reads an object x of type T.

Definition at line 1057 of file File.h.

◆ Read() [3/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 1180 of file File.h.

◆ Read() [4/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() [5/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() [6/6]

template<typename E >

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

inlinestatic

Reads a set of flags f.

Definition at line 1260 of file File.h.

◆ 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 1070 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 1079 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 1097 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

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

◆ 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 T >

void pcl::File::ReadUI32 ( T & x )

inline

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

Definition at line 1088 of file File.h.

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

◆ ReadUI32() [2/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 1269 of file File.h.

◆ ReadUI64()

template<typename T >

void pcl::File::ReadUI64 ( T & x )

inline

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

Definition at line 1106 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 1024 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

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

◆ 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

dist	Distance to move in bytes.
mode	Seek 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 1014 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

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

◆ 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 1610 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

sizeInBytes	The file size in bytes.
precision	The number of decimal digits used to represent floating point numbers. The default value is 3.
alsoShowBytes	Whether 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"

◆ 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

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.
n	Number of random characters in the generated file name. Must be at least five characters. The default value is twelve characters.
prefix	An optional prefix that will be prepended to the generated file name.
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 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]

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

virtual

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

◆ Write() [2/10]

template<typename T >

void pcl::File::Write ( const T & x )

inline

Writes an object x of type T.

Definition at line 1120 of file File.h.

◆ Write() [3/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 1191 of file File.h.

◆ Write() [4/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() [5/10]

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

inline

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

Definition at line 1219 of file File.h.

References pcl::IsoCharTraits::Length().

◆ Write() [6/10]

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

inline

Writes a dynamic 8-bit string as binary data.

Definition at line 1227 of file File.h.

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

◆ Write() [7/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() [8/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 1241 of file File.h.

References pcl::CharTraits::Length().

◆ Write() [9/10]

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

inline

Writes a dynamic UTF-16 string as binary data.

Definition at line 1249 of file File.h.

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

◆ Write() [10/10]

template<typename E >

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

inlinestatic

Writes a set of flags f.

Definition at line 1278 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 1133 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

filePath	Path to the file that will be created.
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:

void CopyFile( const String& targetFilePath, const String& sourceFilePath )
{
   File::WriteFile( targetFilePath, File::ReadFile( sourceFilePath ) );
}

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

filePath	Path to the file that will be created.
contents	Reference to a ByteArray object providing the contents that will be written to the newly created file.
start	Zero-based index of the first byte to be written.
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.

◆ 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

filePath	Path to the file that will be created.
data	Pointer to the first byte to be written to the newly created file.
size	Number 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 1142 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 1160 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

filePath	Path to the file that will be created.
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.

◆ 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 1151 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 1287 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 1169 of file File.h.

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

File.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

TODO: Write a detailed description for File.

Member Typedef Documentation

◆ handle

◆ seek_mode

Constructor & Destructor Documentation

◆ File() [1/4]

◆ File() [2/4]

◆ File() [3/4]

◆ ~File()

◆ File() [4/4]

Member Function Documentation

◆ AppendToName()

◆ CanRead()

◆ CanWrite()

◆ ChangeExtension()

◆ Close()

◆ CopyFile()

◆ CopyLink()

◆ CopyTimesAndPermissions()

◆ Create()

◆ CreateDirectory()

◆ CreateFile()

◆ CreateFileForWriting()

◆ CreateForWriting()

◆ DirectoryExists()

◆ Exists()

◆ ExtractCompleteSuffix()

◆ ExtractDirectory()

◆ ExtractDrive()

◆ ExtractExtension()

◆ ExtractName()

◆ ExtractNameAndExtension()

◆ ExtractNameAndSuffix()

◆ ExtractSuffix()

◆ FileName()

◆ FilePath()

◆ FileURI()

◆ FindCompleteSuffix()

◆ FindDrive()

◆ FindExtension()

◆ FindName()

◆ FindSuffix()

◆ Flush()

◆ FullPath()

◆ GetAvailableSpace()

◆ HomeDirectory()

◆ IsEOF()

◆ IsOpen()

◆ IsReadOnly()

◆ Mode()

◆ Move()

◆ MoveFile()

◆ Open()

◆ OpenFileForReading()

◆ OpenFileForReadWrite()

◆ OpenForReading()

◆ OpenForReadWrite()

◆ OpenOrCreate()

◆ OpenOrCreateFile()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OutText() [1/6]

◆ OutText() [2/6]

◆ OutText() [3/6]

◆ OutText() [4/6]

◆ OutText() [5/6]

◆ OutText() [6/6]

◆ OutTextLn() [1/7]

◆ OutTextLn() [2/7]

◆ OutTextLn() [3/7]

◆ OutTextLn() [4/7]

◆ OutTextLn() [5/7]

◆ OutTextLn() [6/7]

◆ OutTextLn() [7/7]

◆ Position()