Represents a local file or directory. More...

#include <juce_File.h>

Collaboration diagram for File:

Classes
struct	NaturalFileComparator

Public Types
enum	SpecialLocationType { userHomeDirectory, userDocumentsDirectory, userDesktopDirectory, userMusicDirectory, userMoviesDirectory, userPicturesDirectory, userApplicationDataDirectory, commonApplicationDataDirectory, commonDocumentsDirectory, tempDirectory, currentExecutableFile, currentApplicationFile, invokedExecutableFile, hostApplicationPath, windowsSystemDirectory, globalApplicationsDirectory, globalApplicationsDirectoryX86 }
	A set of types of location that can be passed to the getSpecialLocation() method. More...

enum	TypesOfFileToFind { findDirectories = 1, findFiles = 2, findFilesAndDirectories = 3, ignoreHiddenFiles = 4 }
	Used in file searching, to specify whether to return files, directories, or both. More...

Public Member Functions
	File () noexcept
	Creates an (invalid) file object. More...

	File (const String &absolutePath)
	Creates a file from an absolute path. More...

	File (const File &)
	Creates a copy of another file object. More...

	File (File &&) noexcept
	Move constructor. More...

	~File () noexcept
	Destructor. More...

void	addToDock () const
	OSX ONLY - Adds this file to the OSX dock. More...

bool	appendData (const void *dataToAppend, size_t numberOfBytes) const
	Appends a block of binary data to the end of the file. More...

bool	appendText (const String &textToAppend, bool asUnicode=false, bool writeUnicodeHeaderBytes=false) const
	Appends a string to the end of the file. More...

bool	containsSubDirectories () const
	Returns true if this file is a directory that contains one or more subdirectories. More...

bool	copyDirectoryTo (const File &newDirectory) const
	Copies a directory. More...

bool	copyFileTo (const File &targetLocation) const
	Copies a file. More...

Result	create () const
	Creates an empty file if it doesn't already exist. More...

Result	createDirectory () const
	Creates a new directory for this filename. More...

FileInputStream *	createInputStream () const
	Creates a stream to read from this file. More...

FileOutputStream *	createOutputStream (size_t bufferSize=0x8000) const
	Creates a stream to write to this file. More...

bool	createShortcut (const String &description, const File &linkFileToCreate) const
	Windows ONLY - Creates a win32 .LNK shortcut file that links to this file. More...

bool	createSymbolicLink (const File &linkFileToCreate, bool overwriteExisting) const
	Tries to create a symbolic link and returns a boolean to indicate success. More...

bool	deleteFile () const
	Deletes a file. More...

bool	deleteRecursively () const
	Deletes a file or directory and all its subdirectories. More...

bool	exists () const
	Checks whether the file actually exists. More...

bool	existsAsFile () const
	Checks whether the file exists and is a file rather than a directory. More...

int	findChildFiles (Array< File > &results, int whatToLookFor, bool searchRecursively, const String &wildCardPattern="*") const
	Searches inside a directory for files matching a wildcard pattern. More...

int64	getBytesFreeOnVolume () const
	Returns the number of bytes free on the drive that this file lives on. More...

File	getChildFile (StringRef relativeOrAbsolutePath) const
	Returns a file that represents a relative (or absolute) sub-path of the current one. More...

Time	getCreationTime () const
	Returns the time that this file was created. More...

String	getFileExtension () const
	Returns the file's extension. More...

uint64	getFileIdentifier () const
	Returns a unique identifier for the file, if one is available. More...

String	getFileName () const
	Returns the last section of the pathname. More...

String	getFileNameWithoutExtension () const
	Returns the last part of the filename, without its file extension. More...

const String &	getFullPathName () const noexcept
	Returns the complete, absolute path of this file. More...

Time	getLastAccessTime () const
	Returns the last time this file was accessed. More...

Time	getLastModificationTime () const
	Returns the last modification time of this file. More...

File	getLinkedTarget () const
	If this file is a link or alias, this returns the file that it points to. More...

OSType	getMacOSType () const
	OSX ONLY - Finds the OSType of a file from the its resources. More...

File	getNonexistentChildFile (const String &prefix, const String &suffix, bool putNumbersInBrackets=true) const
	Chooses a filename relative to this one that doesn't already exist. More...

File	getNonexistentSibling (bool putNumbersInBrackets=true) const
	Chooses a filename for a sibling file to this one that doesn't already exist. More...

int	getNumberOfChildFiles (int whatToLookFor, const String &wildCardPattern="*") const
	Searches inside a directory and counts how many files match a wildcard pattern. More...

File	getParentDirectory () const
	Returns the directory that contains this file or directory. More...

String	getRelativePathFrom (const File &directoryToBeRelativeTo) const
	Creates a relative path that refers to a file relatively to a given directory. More...

File	getSiblingFile (StringRef siblingFileName) const
	Returns a file which is in the same directory as this one. More...

int64	getSize () const
	Returns the size of the file in bytes. More...

String	getVersion () const
	If possible, this will try to create a version string for the given file. More...

String	getVolumeLabel () const
	Finds the name of the drive on which this file lives. More...

int	getVolumeSerialNumber () const
	Returns the serial number of the volume on which this file lives. More...

int64	getVolumeTotalSize () const
	Returns the total size of the drive that contains this file. More...

bool	hasFileExtension (StringRef extensionToTest) const
	Checks whether the file has a given extension. More...

int	hashCode () const
	Returns a 32-bit hash-code that identifies this file. More...

int64	hashCode64 () const
	Returns a 64-bit hash-code that identifies this file. More...

bool	hasIdenticalContentTo (const File &other) const
	Attempts to scan the contents of this file and compare it to another file, returning true if this is possible and they match byte-for-byte. More...

bool	hasWriteAccess () const
	Checks whether a file can be created or written to. More...

bool	isAChildOf (const File &potentialParentDirectory) const
	Checks whether a file is somewhere inside a directory. More...

bool	isBundle () const
	OSX ONLY - Returns true if this file is actually a bundle. More...

bool	isDirectory () const
	Checks whether the file is a directory that exists. More...

bool	isHidden () const
	Returns true if this file is a hidden or system file. More...

bool	isOnCDRomDrive () const
	Returns true if this file is on a CD or DVD drive. More...

bool	isOnHardDisk () const
	Returns true if this file is on a hard disk. More...

bool	isOnRemovableDrive () const
	Returns true if this file is on a removable disk drive. More...

bool	isRoot () const
	Checks whether the path of this file represents the root of a file system, irrespective of its existance. More...

bool	isShortcut () const
	Windows ONLY - Returns true if this is a win32 .LNK file. More...

bool	isSymbolicLink () const
	Returns true if this file is a link or alias that can be followed using getLinkedTarget(). More...

bool	loadFileAsData (MemoryBlock &result) const
	Loads a file's contents into memory as a block of binary data. More...

String	loadFileAsString () const
	Reads a file into memory as a string. More...

bool	moveFileTo (const File &targetLocation) const
	Moves or renames a file. More...

bool	moveToTrash () const
	Moves this file or folder to the trash. More...

bool	operator!= (const File &) const
	Compares the pathnames for two files. More...

bool	operator< (const File &) const
	Compares the pathnames for two files. More...

File &	operator= (const String &newAbsolutePath)
	Sets the file based on an absolute pathname. More...

File &	operator= (const File &otherFile)
	Copies from another file object. More...

File &	operator= (File &&) noexcept
	Move assignment operator. More...

bool	operator== (const File &) const
	Compares the pathnames for two files. More...

bool	operator> (const File &) const
	Compares the pathnames for two files. More...

void	readLines (StringArray &destLines) const
	Reads the contents of this file as text and splits it into lines, which are appended to the given StringArray. More...

bool	replaceFileIn (const File &targetLocation) const
	Replaces a file. More...

bool	replaceWithData (const void *dataToWrite, size_t numberOfBytes) const
	Replaces this file's contents with a given block of data. More...

bool	replaceWithText (const String &textToWrite, bool asUnicode=false, bool writeUnicodeHeaderBytes=false) const
	Replaces this file's contents with a given text string. More...

void	revealToUser () const
	Opens Finder, Explorer, or whatever the OS uses, to show the user this file's location. More...

bool	setAsCurrentWorkingDirectory () const
	Sets the current working directory to be this file. More...

bool	setCreationTime (Time newTime) const
	Changes the creation date for this file. More...

bool	setExecutePermission (bool shouldBeExecutable) const
	Changes the execute-permissions of a file. More...

bool	setLastAccessTime (Time newTime) const
	Changes the last-access time for this file. More...

bool	setLastModificationTime (Time newTime) const
	Changes the modification time for this file. More...

bool	setReadOnly (bool shouldBeReadOnly, bool applyRecursively=false) const
	Changes the write-permission of a file or directory. More...

bool	startAsProcess (const String &parameters=String()) const
	Launches the file as a process. More...

File	withFileExtension (StringRef newExtension) const
	Returns a version of this file with a different file extension. More...

Static Public Member Functions
static String	addTrailingSeparator (const String &path)
	Adds a separator character to the end of a path if it doesn't already have one. More...

static bool	areFileNamesCaseSensitive ()
	Indicates whether filenames are case-sensitive on the current operating system. More...

static File	createFileWithoutCheckingPath (const String &absolutePath) noexcept
	Creates a file that simply contains this string, without doing the sanity-checking that the normal constructors do. More...

static String	createLegalFileName (const String &fileNameToFix)
	Returns a version of a filename with any illegal characters removed. More...

static String	createLegalPathName (const String &pathNameToFix)
	Returns a version of a path with any illegal characters removed. More...

static File	createTempFile (StringRef fileNameEnding)
	Returns a temporary file in the system's temp directory. More...

static String	descriptionOfSizeInBytes (int64 bytes)
	Utility function to convert a file size in bytes to a neat string description. More...

static void	findFileSystemRoots (Array< File > &results)
	Creates a set of files to represent each file root. More...

static File	getCurrentWorkingDirectory ()
	Returns the current working directory. More...

static File	getSpecialLocation (const SpecialLocationType type)
	Finds the location of a special type of file or directory, such as a home folder or documents folder. More...

static bool	isAbsolutePath (StringRef path)
	Returns true if the string seems to be a fully-specified absolute path. More...

Static Public Attributes
static const juce_wchar	separator = '/'
	The system-specific file separator character. More...

static const String	separatorString
	The system-specific file separator character, as a string. More...

Private Member Functions
bool	copyInternal (const File &) const

Result	createDirectoryInternal (const String &) const

void	getFileTimesInternal (int64 &m, int64 &a, int64 &c) const

String	getPathUpToLastSlash () const

bool	moveInternal (const File &) const

bool	replaceInternal (const File &) const

bool	setFileExecutableInternal (bool) const

bool	setFileReadOnlyInternal (bool) const

bool	setFileTimesInternal (int64 m, int64 a, int64 c) const

Static Private Member Functions
static String	parseAbsolutePath (const String &)

Private Attributes
String	fullPath

Detailed Description

Represents a local file or directory.

This class encapsulates the absolute pathname of a file or directory, and has methods for finding out about the file and changing its properties.

To read or write to the file, there are methods for returning an input or output stream.

See also: FileInputStream, FileOutputStream

Member Enumeration Documentation

◆ SpecialLocationType

enum File::SpecialLocationType

A set of types of location that can be passed to the getSpecialLocation() method.

Enumerator
userHomeDirectory	The user's home folder. This is the same as using File ("~").
userDocumentsDirectory	The user's default documents folder. On Windows, this might be the user's "My Documents" folder. On the Mac it'll be their "Documents" folder. Linux doesn't tend to have one of these, so it might just return their home folder.
userDesktopDirectory	The folder that contains the user's desktop objects.
userMusicDirectory	The most likely place where a user might store their music files.
userMoviesDirectory	The most likely place where a user might store their movie files.
userPicturesDirectory	The most likely place where a user might store their picture files.
userApplicationDataDirectory	The folder in which applications store their persistent user-specific settings. On Windows, this might be "\Documents and Settings\username\Application Data". On the Mac, it might be "~/Library". If you're going to store your settings in here, always create your own sub-folder to put them in, to avoid making a mess. On GNU/Linux it is "~/.config".
commonApplicationDataDirectory	An equivalent of the userApplicationDataDirectory folder that is shared by all users of the computer, rather than just the current user. On the Mac it'll be "/Library", on Windows, it could be something like "\Documents and Settings\All Users\Application Data". On GNU/Linux it is "/opt". Depending on the setup, this folder may be read-only.
commonDocumentsDirectory	A place to put documents which are shared by all users of the machine. On Windows this may be somewhere like "C:\Users\Public\Documents", on OSX it will be something like "/Users/Shared". Other OSes may have no such concept though, so be careful.
tempDirectory	The folder that should be used for temporary files. Always delete them when you're finished, to keep the user's computer tidy!
currentExecutableFile	Returns this application's executable file. If running as a plug-in or DLL, this will (where possible) be the DLL rather than the host app. On the mac this will return the unix binary, not the package folder - see currentApplicationFile for that. See also invokedExecutableFile, which is similar, but if the exe was launched from a file link, invokedExecutableFile will return the name of the link.
currentApplicationFile	Returns this application's location. If running as a plug-in or DLL, this will (where possible) be the DLL rather than the host app. On the mac this will return the package folder (if it's in one), not the unix binary that's inside it - compare with currentExecutableFile.
invokedExecutableFile	Returns the file that was invoked to launch this executable. This may differ from currentExecutableFile if the app was started from e.g. a link - this will return the name of the link that was used, whereas currentExecutableFile will return the actual location of the target executable.
hostApplicationPath	In a plugin, this will return the path of the host executable.
windowsSystemDirectory	On a Windows machine, returns the location of the Windows/System32 folder.
globalApplicationsDirectory	The directory in which applications normally get installed. So on windows, this would be something like "C:\Program Files", on the Mac "/Applications", or "/usr" on linux.
globalApplicationsDirectoryX86	On a Windows machine, returns the directory in which 32 bit applications normally get installed. On a 64 bit machine this would be something like "C:\Program Files (x86)", whereas for 32 bit machines this would match globalApplicationsDirectory and be something like "C:\Program Files". See also globalApplicationsDirectory

◆ TypesOfFileToFind

enum File::TypesOfFileToFind

Used in file searching, to specify whether to return files, directories, or both.

Enumerator
findDirectories	Use this flag to indicate that you want to find directories.
findFiles	Use this flag to indicate that you want to find files.
findFilesAndDirectories	Use this flag to indicate that you want to find both files and directories.
ignoreHiddenFiles	Add this flag to avoid returning any hidden files in the results.

Constructor & Destructor Documentation

◆ File() [1/4]

File::File ( )

inlinenoexcept

Creates an (invalid) file object.

The file is initially set to an empty path, so getFullPathName() will return an empty string.

You can use its operator= method to point it at a proper file.

◆ File() [2/4]

File::File ( const String & absolutePath )

Creates a file from an absolute path.

If the path supplied is a relative path, it is taken to be relative to the current working directory (see File::getCurrentWorkingDirectory()), but this isn't a recommended way of creating a file, because you never know what the CWD is going to be.

On the Mac/Linux, the path can include "~" notation for referring to user home directories.

◆ File() [3/4]

File::File ( const File & )

Creates a copy of another file object.

◆ ~File()

File::~File ( )

inlinenoexcept

Destructor.

◆ File() [4/4]

File::File ( File && )

noexcept

Move constructor.

Member Function Documentation

◆ addToDock()

void File::addToDock ( ) const

OSX ONLY - Adds this file to the OSX dock.

◆ addTrailingSeparator()

static String File::addTrailingSeparator ( const String & path )

static

Adds a separator character to the end of a path if it doesn't already have one.

◆ appendData()

bool File::appendData	(	const void *	dataToAppend,
		size_t	numberOfBytes
	)		const

Appends a block of binary data to the end of the file.

This will try to write the given buffer to the end of the file.

Returns: false if it can't write to the file for some reason

◆ appendText()

bool File::appendText	(	const String &	textToAppend,
		bool	asUnicode = `false`,
		bool	writeUnicodeHeaderBytes = `false`
	)		const

Appends a string to the end of the file.

This will try to append a text string to the file, as either 16-bit unicode or 8-bit characters in the default system encoding.

It can also write the 'ff fe' unicode header bytes before the text to indicate the endianness of the file.

Any single \n characters in the string are replaced with \r\n before it is written.

See also: replaceWithText

◆ areFileNamesCaseSensitive()

static bool File::areFileNamesCaseSensitive ( )

static

Indicates whether filenames are case-sensitive on the current operating system.

◆ containsSubDirectories()

bool File::containsSubDirectories ( ) const

Returns true if this file is a directory that contains one or more subdirectories.

See also: isDirectory, findChildFiles

◆ copyDirectoryTo()

bool File::copyDirectoryTo ( const File & newDirectory ) const

Copies a directory.

Tries to copy an entire directory, recursively.

If this file isn't a directory or if any target files can't be created, this will return false.

Parameters

newDirectory the directory that this one should be copied to. Note that this is the name of the actual directory to create, not the directory into which the new one should be placed, so there must be enough write privileges to create it if it doesn't exist. Any files inside it will be overwritten by similarly named ones that are copied.

◆ copyFileTo()

bool File::copyFileTo ( const File & targetLocation ) const

Copies a file.

Tries to copy a file to a different location. If the target file already exists, this will attempt to delete it first, and will fail if this can't be done.

Returns: true if the operation succeeds

◆ copyInternal()

bool File::copyInternal ( const File & ) const

private

◆ create()

Result File::create ( ) const

Creates an empty file if it doesn't already exist.

If the file that this object refers to doesn't exist, this will create a file of zero size.

If it already exists or is a directory, this method will do nothing.

If the parent directories of the File do not exist then this method will recursively create the parent directories.

Returns: a result to indicate whether the file was created successfully, or an error message if it failed.

See also: createDirectory

◆ createDirectory()

Result File::createDirectory ( ) const

Creates a new directory for this filename.

This will try to create the file as a directory, and will also create any parent directories it needs in order to complete the operation.

Returns: a result to indicate whether the directory was created successfully, or an error message if it failed.

See also: create

◆ createDirectoryInternal()

Result File::createDirectoryInternal ( const String & fileName ) const

private

References anonymous_namespace{juce_posix_SharedCode.h}::getResultForReturnValue(), and String::toUTF8().

◆ createFileWithoutCheckingPath()

static File File::createFileWithoutCheckingPath ( const String & absolutePath )

staticnoexcept

Creates a file that simply contains this string, without doing the sanity-checking that the normal constructors do.

Best to avoid this unless you really know what you're doing.

◆ createInputStream()

FileInputStream* File::createInputStream ( ) const

Creates a stream to read from this file.

Returns: a stream that will read from this file (initially positioned at the start of the file), or nullptr if the file can't be opened for some reason

See also: createOutputStream, loadFileAsData

◆ createLegalFileName()

static String File::createLegalFileName ( const String & fileNameToFix )

static

Returns a version of a filename with any illegal characters removed.

This will return a copy of the given string after removing characters that are not allowed in a legal filename, and possibly shortening the string if it's too long.

Because this will remove slashes, don't use it on an absolute pathname - use createLegalPathName() for that.

See also: createLegalPathName

◆ createLegalPathName()

static String File::createLegalPathName ( const String & pathNameToFix )

static

Returns a version of a path with any illegal characters removed.

Similar to createLegalFileName(), but this won't remove slashes, so can be used on a complete pathname.

See also: createLegalFileName

◆ createOutputStream()

FileOutputStream* File::createOutputStream ( size_t bufferSize = 0x8000 ) const

Creates a stream to write to this file.

If the file exists, the stream that is returned will be positioned ready for writing at the end of the file, so you might want to use deleteFile() first to write to an empty file.

Returns: a stream that will write to this file (initially positioned at the end of the file), or nullptr if the file can't be opened for some reason

See also: createInputStream, appendData, appendText

◆ createShortcut()

bool File::createShortcut	(	const String &	description,
		const File &	linkFileToCreate
	)		const

Windows ONLY - Creates a win32 .LNK shortcut file that links to this file.

◆ createSymbolicLink()

bool File::createSymbolicLink	(	const File &	linkFileToCreate,
		bool	overwriteExisting
	)		const

Tries to create a symbolic link and returns a boolean to indicate success.

◆ createTempFile()

static File File::createTempFile ( StringRef fileNameEnding )

static

Returns a temporary file in the system's temp directory.

This will try to return the name of a non-existent temp file. To get the temp folder, you can use getSpecialLocation (File::tempDirectory).

◆ deleteFile()

bool File::deleteFile ( ) const

Deletes a file.

If this file is actually a directory, it may not be deleted correctly if it contains files. See deleteRecursively() as a better way of deleting directories.

Returns: true if the file has been successfully deleted (or if it didn't exist to begin with).

See also: deleteRecursively

Referenced by CameraDevice::Pimpl::createFileCaptureFilter(), getVolumeSerialNumber(), moveInternal(), and CameraDevice::Pimpl::startRecordingToFile().

◆ deleteRecursively()

bool File::deleteRecursively ( ) const

Deletes a file or directory and all its subdirectories.

If this file is a directory, this will try to delete it and all its subfolders. If it's just a file, it will just try to delete the file.

Returns: true if the file and all its subfolders have been successfully deleted (or if it didn't exist to begin with).

See also: deleteFile

◆ descriptionOfSizeInBytes()

static String File::descriptionOfSizeInBytes ( int64 bytes )

static

Utility function to convert a file size in bytes to a neat string description.

So for example 100 would return "100 bytes", 2000 would return "2 KB", 2000000 would produce "2 MB", etc.

◆ exists()

bool File::exists ( ) const

Checks whether the file actually exists.

Returns: true if the file exists, either as a file or a directory.

See also: existsAsFile, isDirectory

Referenced by anonymous_namespace{juce_posix_SharedCode.h}::juce_doStatFS().

◆ existsAsFile()

bool File::existsAsFile ( ) const

Checks whether the file exists and is a file rather than a directory.

Returns: true only if this is a real file, false if it's a directory or doesn't exist

See also: exists, isDirectory

◆ findChildFiles()

int File::findChildFiles	(	Array< File > &	results,
		int	whatToLookFor,
		bool	searchRecursively,
		const String &	wildCardPattern = `"*"`
	)		const

Searches inside a directory for files matching a wildcard pattern.

Assuming that this file is a directory, this method will search it for either files or subdirectories whose names match a filename pattern.

Parameters

results	an array to which File objects will be added for the files that the search comes up with
whatToLookFor	a value from the TypesOfFileToFind enum, specifying whether to return files, directories, or both. If the ignoreHiddenFiles flag is also added to this value, hidden files won't be returned
searchRecursively	if true, all subdirectories will be recursed into to do an exhaustive search
wildCardPattern	the filename pattern to search for, e.g. "*.txt"

Returns: the number of results that have been found

See also: getNumberOfChildFiles, DirectoryIterator

◆ findFileSystemRoots()

static void File::findFileSystemRoots ( Array< File > & results )

static

Creates a set of files to represent each file root.

e.g. on Windows this will create files for "c:\", "d:\" etc according to which ones are available. On the Mac/Linux, this will probably just add a single entry for "/".

◆ getBytesFreeOnVolume()

int64 File::getBytesFreeOnVolume ( ) const

Returns the number of bytes free on the drive that this file lives on.

Returns: the number of bytes free, or 0 if there's a problem finding this out

See also: getVolumeTotalSize

References anonymous_namespace{juce_posix_SharedCode.h}::juce_doStatFS().

◆ getChildFile()

File File::getChildFile ( StringRef relativeOrAbsolutePath ) const

Returns a file that represents a relative (or absolute) sub-path of the current one.

This will find a child file or directory of the current object.

e.g. File ("/moose/fish").getChildFile ("foo.txt") will produce "/moose/fish/foo.txt". File ("/moose/fish").getChildFile ("haddock/foo.txt") will produce "/moose/fish/haddock/foo.txt". File ("/moose/fish").getChildFile ("../foo.txt") will produce "/moose/foo.txt".

If the string is actually an absolute path, it will be treated as such, e.g. File ("/moose/fish").getChildFile ("/foo.txt") will produce "/foo.txt"

See also: getSiblingFile, getParentDirectory, getRelativePathFrom, isAChildOf

Referenced by juce_getExecutableFile().

◆ getCreationTime()

Time File::getCreationTime ( ) const

Returns the time that this file was created.

Returns: the time, or an invalid time if the file doesn't exist.

See also: getLastModificationTime, getLastAccessTime

◆ getCurrentWorkingDirectory()

File File::getCurrentWorkingDirectory ( )

static

Returns the current working directory.

See also: setAsCurrentWorkingDirectory

References HeapBlock< ElementType, throwOnFailure >::malloc().

Referenced by ChildProcess::ActiveProcess::ActiveProcess(), and juce_getExecutableFile().

◆ getFileExtension()

String File::getFileExtension ( ) const

Returns the file's extension.

Returns the file extension of this file, also including the dot.

e.g. "/moose/fish/foo.txt" would return ".txt"

See also: hasFileExtension, withFileExtension, getFileNameWithoutExtension

◆ getFileIdentifier()

uint64 File::getFileIdentifier ( ) const

Returns a unique identifier for the file, if one is available.

Depending on the OS and file-system, this may be a unix inode number or a win32 file identifier, or 0 if it fails to find one. The number will be unique on the filesystem, but not globally.

References anonymous_namespace{juce_posix_SharedCode.h}::juce_stat().

◆ getFileName()

String File::getFileName ( ) const

Returns the last section of the pathname.

Returns just the final part of the path - e.g. if the whole path is "/moose/fish/foo.txt" this will return "foo.txt".

For a directory, it returns the final part of the path - e.g. for the directory "/moose/fish" it'll return "fish".

If the filename begins with a dot, it'll return the whole filename, e.g. for "/moose/.fish", it'll return ".fish"

See also: getFullPathName, getFileNameWithoutExtension

Referenced by PluginHostType::getHostType().

◆ getFileNameWithoutExtension()

String File::getFileNameWithoutExtension ( ) const

Returns the last part of the filename, without its file extension.

e.g. for "/moose/fish/foo.txt" this will return "foo".

See also: getFileName, getFileExtension, hasFileExtension, withFileExtension

◆ getFileTimesInternal()

void File::getFileTimesInternal	(	int64 &	m,
		int64 &	a,
		int64 &	c
	)		const

private

References anonymous_namespace{juce_posix_SharedCode.h}::juce_stat().

◆ getFullPathName()

const String& File::getFullPathName ( ) const

inlinenoexcept

Returns the complete, absolute path of this file.

This includes the filename and all its parent folders. On Windows it'll also include the drive letter prefix; on Mac or Linux it'll be a complete path starting from the root folder.

If you just want the file's name, you should use getFileName() or getFileNameWithoutExtension().

See also: getFileName, getRelativePathFrom

References anonymous_namespace{juce_posix_SharedCode.h}::getCreationTime(), operator!=(), juce::operator<(), operator==(), and juce::operator>().

Referenced by File::NaturalFileComparator::compareElements(), CameraDevice::Pimpl::createFileCaptureFilter(), anonymous_namespace{juce_osx_ObjCHelpers.h}::createNSURLFromFile(), PluginHostType::getHostPath(), getVolumeLabel(), getVolumeSerialNumber(), anonymous_namespace{juce_posix_SharedCode.h}::juce_doStatFS(), VideoComponent::Pimpl::load(), moveInternal(), MemoryMappedFile::openInternal(), and StandalonePluginHolder::setLastFile().

◆ getLastAccessTime()

Time File::getLastAccessTime ( ) const

Returns the last time this file was accessed.

Returns: the time, or an invalid time if the file doesn't exist.

See also: setLastAccessTime, getLastModificationTime, getCreationTime

◆ getLastModificationTime()

Time File::getLastModificationTime ( ) const

Returns the last modification time of this file.

Returns: the time, or an invalid time if the file doesn't exist.

See also: setLastModificationTime, getLastAccessTime, getCreationTime

◆ getLinkedTarget()

File File::getLinkedTarget ( ) const

If this file is a link or alias, this returns the file that it points to.

If the file isn't actually link, it'll just return itself.

◆ getMacOSType()

OSType File::getMacOSType ( ) const

OSX ONLY - Finds the OSType of a file from the its resources.

◆ getNonexistentChildFile()

File File::getNonexistentChildFile	(	const String &	prefix,
		const String &	suffix,
		bool	putNumbersInBrackets = `true`
	)		const

Chooses a filename relative to this one that doesn't already exist.

If this file is a directory, this will return a child file of this directory that doesn't exist, by adding numbers to a prefix and suffix until it finds one that isn't already there.

If the prefix + the suffix doesn't exist, it won't bother adding a number.

e.g. File ("/moose/fish").getNonexistentChildFile ("foo", ".txt", true) might return "/moose/fish/foo(2).txt" if there's already a file called "foo.txt".

Parameters

prefix	the string to use for the filename before the number
suffix	the string to add to the filename after the number
putNumbersInBrackets	if true, this will create filenames in the format "prefix(number)suffix", if false, it will leave the brackets out.

◆ getNonexistentSibling()

File File::getNonexistentSibling ( bool putNumbersInBrackets = true ) const

Chooses a filename for a sibling file to this one that doesn't already exist.

If this file doesn't exist, this will just return itself, otherwise it will return an appropriate sibling that doesn't exist, e.g. if a file "/moose/fish/foo.txt" exists, this might return "/moose/fish/foo(2).txt".

Parameters

putNumbersInBrackets whether to add brackets around the numbers that get appended to the new filename.

◆ getNumberOfChildFiles()

int File::getNumberOfChildFiles	(	int	whatToLookFor,
		const String &	wildCardPattern = `"*"`
	)		const

Searches inside a directory and counts how many files match a wildcard pattern.

Assuming that this file is a directory, this method will search it for either files or subdirectories whose names match a filename pattern, and will return the number of matches found.

This isn't a recursive call, and will only search this directory, not its children.

Parameters

whatToLookFor	a value from the TypesOfFileToFind enum, specifying whether to count files, directories, or both. If the ignoreHiddenFiles flag is also added to this value, hidden files won't be counted
wildCardPattern	the filename pattern to search for, e.g. "*.txt"

Returns: the number of matches found

See also: findChildFiles, DirectoryIterator

◆ getParentDirectory()

File File::getParentDirectory ( ) const

Returns the directory that contains this file or directory.

e.g. for "/moose/fish/foo.txt" this will return "/moose/fish".

Referenced by getVolumeLabel(), and anonymous_namespace{juce_posix_SharedCode.h}::juce_doStatFS().

◆ getPathUpToLastSlash()

String File::getPathUpToLastSlash ( ) const

private

◆ getRelativePathFrom()

String File::getRelativePathFrom ( const File & directoryToBeRelativeTo ) const

Creates a relative path that refers to a file relatively to a given directory.

e.g. File ("/moose/foo.txt").getRelativePathFrom (File ("/moose/fish/haddock")) would return "../../foo.txt".

If it's not possible to navigate from one file to the other, an absolute path is returned. If the paths are invalid, an empty string may also be returned.

Parameters

directoryToBeRelativeTo the directory which the resultant string will be relative to. If this is actually a file rather than a directory, its parent directory will be used instead. If it doesn't exist, it's assumed to be a directory.

See also: getChildFile, isAbsolutePath

◆ getSiblingFile()

File File::getSiblingFile ( StringRef siblingFileName ) const

Returns a file which is in the same directory as this one.

This is equivalent to getParentDirectory().getChildFile (name).

See also: getChildFile, getParentDirectory

◆ getSize()

int64 File::getSize ( ) const

Returns the size of the file in bytes.

Returns: the number of bytes in the file, or 0 if it doesn't exist.

References anonymous_namespace{juce_posix_SharedCode.h}::juce_stat().

◆ getSpecialLocation()

static File File::getSpecialLocation ( const SpecialLocationType type )

static

Finds the location of a special type of file or directory, such as a home folder or documents folder.

See also: SpecialLocationType

Referenced by PluginHostType::getHostPath(), StandalonePluginHolder::getLastFile(), and getVolumeSerialNumber().

◆ getVersion()

String File::getVersion ( ) const

If possible, this will try to create a version string for the given file.

The OS may be able to look at the file and give a version for it - e.g. with executables, bundles, dlls, etc. If no version is available, this will return an empty string.

◆ getVolumeLabel()

String File::getVolumeLabel ( ) const

Finds the name of the drive on which this file lives.

Returns: the volume label of the drive, or an empty string if this isn't possible

References String::fromUTF8(), getFullPathName(), getParentDirectory(), String::toUTF8(), and zerostruct().

◆ getVolumeSerialNumber()

int File::getVolumeSerialNumber ( ) const

Returns the serial number of the volume on which this file lives.

Returns: the serial number, or zero if there's a problem doing this

References deleteFile(), getFullPathName(), getSpecialLocation(), Random::getSystemRandom(), juce::ignoreUnused(), loadFileAsString(), tempDirectory, String::toHexString(), and String::toUTF8().

◆ getVolumeTotalSize()

int64 File::getVolumeTotalSize ( ) const

Returns the total size of the drive that contains this file.

Returns: the total number of bytes that the volume can hold

See also: getBytesFreeOnVolume

References anonymous_namespace{juce_posix_SharedCode.h}::juce_doStatFS().

◆ hasFileExtension()

bool File::hasFileExtension ( StringRef extensionToTest ) const

Checks whether the file has a given extension.

Parameters

extensionToTest the extension to look for - it doesn't matter whether or not this string has a dot at the start, so ".wav" and "wav" will have the same effect. To compare with multiple extensions, this parameter can contain multiple strings, separated by semi-colons - so, for example: hasFileExtension (".jpeg;png;gif") would return true if the file has any of those three extensions.

See also: getFileExtension, withFileExtension, getFileNameWithoutExtension

◆ hashCode()

int File::hashCode ( ) const

Returns a 32-bit hash-code that identifies this file.

This is based on the filename. Obviously it's possible, although unlikely, that two files will have the same hash-code.

◆ hashCode64()

int64 File::hashCode64 ( ) const

Returns a 64-bit hash-code that identifies this file.

This is based on the filename. Obviously it's possible, although unlikely, that two files will have the same hash-code.

◆ hasIdenticalContentTo()

bool File::hasIdenticalContentTo ( const File & other ) const

Attempts to scan the contents of this file and compare it to another file, returning true if this is possible and they match byte-for-byte.

◆ hasWriteAccess()

bool File::hasWriteAccess ( ) const

Checks whether a file can be created or written to.

Returns: true if it's possible to create and write to this file. If the file doesn't already exist, this will check its parent directory to see if writing is allowed.

See also: setReadOnly

References hasEffectiveRootFilePermissions().

◆ isAbsolutePath()

static bool File::isAbsolutePath ( StringRef path )

static

Returns true if the string seems to be a fully-specified absolute path.

◆ isAChildOf()

bool File::isAChildOf ( const File & potentialParentDirectory ) const

Checks whether a file is somewhere inside a directory.

Returns true if this file is somewhere inside a subdirectory of the directory that is passed in. Neither file actually has to exist, because the function just checks the paths for similarities.

e.g. File ("/moose/fish/foo.txt").isAChildOf ("/moose") is true. File ("/moose/fish/foo.txt").isAChildOf ("/moose/fish") is also true.

◆ isBundle()

bool File::isBundle ( ) const

OSX ONLY - Returns true if this file is actually a bundle.

◆ isDirectory()

bool File::isDirectory ( ) const

Checks whether the file is a directory that exists.

Returns: true only if the file is a directory which actually exists, so false if it's a file or doesn't exist at all

See also: exists, existsAsFile

References anonymous_namespace{juce_posix_SharedCode.h}::juce_stat().

Referenced by File::NaturalFileComparator::compareElements().

◆ isHidden()

bool File::isHidden ( ) const

Returns true if this file is a hidden or system file.

The criteria for deciding whether a file is hidden are platform-dependent.

◆ isOnCDRomDrive()

bool File::isOnCDRomDrive ( ) const

Returns true if this file is on a CD or DVD drive.

◆ isOnHardDisk()

bool File::isOnHardDisk ( ) const

Returns true if this file is on a hard disk.

This will fail if it's a network drive, but will still be true for removable hard-disks.

◆ isOnRemovableDrive()

bool File::isOnRemovableDrive ( ) const

Returns true if this file is on a removable disk drive.

This might be a usb-drive, a CD-rom, or maybe a network drive.

◆ isRoot()

bool File::isRoot ( ) const

Checks whether the path of this file represents the root of a file system, irrespective of its existance.

This will return true for "C:", "D:", etc on Windows and "/" on other platforms.

◆ isShortcut()

bool File::isShortcut ( ) const

Windows ONLY - Returns true if this is a win32 .LNK file.

◆ isSymbolicLink()

bool File::isSymbolicLink ( ) const

Returns true if this file is a link or alias that can be followed using getLinkedTarget().

◆ loadFileAsData()

bool File::loadFileAsData ( MemoryBlock & result ) const

Loads a file's contents into memory as a block of binary data.

Of course, trying to load a very large file into memory will blow up, so it's better to check first.

Parameters

result the data block to which the file's contents should be appended - note that if the memory block might already contain some data, you might want to clear it first

Returns: true if the file could all be read into memory

Referenced by StandalonePluginHolder::askUserToLoadState().

◆ loadFileAsString()

String File::loadFileAsString ( ) const

Reads a file into memory as a string.

Attempts to load the entire file as a zero-terminated string.

This makes use of InputStream::readEntireStreamAsString, which can read either UTF-16 or UTF-8 file formats.

Referenced by getVolumeSerialNumber().

◆ moveFileTo()

bool File::moveFileTo ( const File & targetLocation ) const

Moves or renames a file.

Tries to move a file to a different location. If the target file already exists, this will attempt to delete it first, and will fail if this can't be done.

Note that the destination file isn't the directory to put it in, it's the actual filename that you want the new file to have.

Also note that on some OSes (e.g. Windows), moving files between different volumes may not be possible.

Returns: true if the operation succeeds

◆ moveInternal()

bool File::moveInternal ( const File & dest ) const

private

References deleteFile(), getFullPathName(), and String::toUTF8().

◆ moveToTrash()

bool File::moveToTrash ( ) const

Moves this file or folder to the trash.

Returns: true if the operation succeeded. It could fail if the trash is full, or if the file is write-protected, so you should check the return value and act appropriately.

◆ operator!=()

bool File::operator!= ( const File & ) const

Compares the pathnames for two files.

◆ operator<()

bool File::operator< ( const File & ) const

Compares the pathnames for two files.

◆ operator=() [1/3]

File& File::operator= ( const String & newAbsolutePath )

Sets the file based on an absolute pathname.

If the path supplied is a relative path, it is taken to be relative to the current working directory (see File::getCurrentWorkingDirectory()), but this isn't a recommended way of creating a file, because you never know what the CWD is going to be.

On the Mac/Linux, the path can include "~" notation for referring to user home directories.

◆ operator=() [2/3]

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

Copies from another file object.

◆ operator=() [3/3]

File& File::operator= ( File && )

noexcept

Move assignment operator.

◆ operator==()

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

Compares the pathnames for two files.

◆ operator>()

bool File::operator> ( const File & ) const

Compares the pathnames for two files.

◆ parseAbsolutePath()

static String File::parseAbsolutePath ( const String & )

staticprivate

◆ readLines()

void File::readLines ( StringArray & destLines ) const

Reads the contents of this file as text and splits it into lines, which are appended to the given StringArray.

Referenced by readPosixConfigFileValue().

◆ replaceFileIn()

bool File::replaceFileIn ( const File & targetLocation ) const

Replaces a file.

Replace the file in the given location, assuming the replaced files identity. Depending on the file system this will preserve file attributes such as creation date, short file name, etc.

If replacement succeeds the original file is deleted.

Returns: true if the operation succeeds

◆ replaceInternal()

bool File::replaceInternal ( const File & dest ) const

private

◆ replaceWithData()

bool File::replaceWithData	(	const void *	dataToWrite,
		size_t	numberOfBytes
	)		const

Replaces this file's contents with a given block of data.

This will delete the file and replace it with the given data.

A nice feature of this method is that it's safe - instead of deleting the file first and then re-writing it, it creates a new temporary file, writes the data to that, and then moves the new file to replace the existing file. This means that if the power gets pulled out or something crashes, you're a lot less likely to end up with a corrupted or unfinished file..

Returns true if the operation succeeds, or false if it fails.

See also: appendText

Referenced by StandalonePluginHolder::askUserToSaveState().

◆ replaceWithText()

bool File::replaceWithText	(	const String &	textToWrite,
		bool	asUnicode = `false`,
		bool	writeUnicodeHeaderBytes = `false`
	)		const

Replaces this file's contents with a given text string.

This will delete the file and replace it with the given text.

A nice feature of this method is that it's safe - instead of deleting the file first and then re-writing it, it creates a new temporary file, writes the text to that, and then moves the new file to replace the existing file. This means that if the power gets pulled out or something crashes, you're a lot less likely to end up with an empty file..

For an explanation of the parameters here, see the appendText() method.

Returns true if the operation succeeds, or false if it fails.

See also: appendText

◆ revealToUser()

void File::revealToUser ( ) const

Opens Finder, Explorer, or whatever the OS uses, to show the user this file's location.

See also: startAsProcess

◆ setAsCurrentWorkingDirectory()

bool File::setAsCurrentWorkingDirectory ( ) const

Sets the current working directory to be this file.

For this to work the file must point to a valid directory.

Returns: true if the current directory has been changed.

See also: getCurrentWorkingDirectory

◆ setCreationTime()

bool File::setCreationTime ( Time newTime ) const

Changes the creation date for this file.

Parameters

newTime the time to apply to the file

Returns: true if it manages to change the file's time.

See also: getCreationTime, setLastModificationTime, setLastAccessTime

◆ setExecutePermission()

bool File::setExecutePermission ( bool shouldBeExecutable ) const

Changes the execute-permissions of a file.

Parameters

shouldBeExecutable whether to add or remove execute-permission

Returns: true if it manages to change the file's permissions.

◆ setFileExecutableInternal()

bool File::setFileExecutableInternal ( bool shouldBeExecutable ) const

private

References setFileModeFlags().

◆ setFileReadOnlyInternal()

bool File::setFileReadOnlyInternal ( bool shouldBeReadOnly ) const

private

References setFileModeFlags().

◆ setFileTimesInternal()

bool File::setFileTimesInternal	(	int64	m,
		int64	a,
		int64	c
	)		const

private

References anonymous_namespace{juce_posix_SharedCode.h}::juce_stat().

◆ setLastAccessTime()

bool File::setLastAccessTime ( Time newTime ) const

Changes the last-access time for this file.

Parameters

newTime the time to apply to the file

Returns: true if it manages to change the file's time.

See also: getLastAccessTime, setLastModificationTime, setCreationTime

◆ setLastModificationTime()

bool File::setLastModificationTime ( Time newTime ) const

Changes the modification time for this file.

Parameters

newTime the time to apply to the file

Returns: true if it manages to change the file's time.

See also: getLastModificationTime, setLastAccessTime, setCreationTime

◆ setReadOnly()

bool File::setReadOnly	(	bool	shouldBeReadOnly,
		bool	applyRecursively = `false`
	)		const

Changes the write-permission of a file or directory.

Parameters

shouldBeReadOnly	whether to add or remove write-permission
applyRecursively	if the file is a directory and this is true, it will recurse through all the subfolders changing the permissions of all files

Returns: true if it manages to change the file's permissions.

See also: hasWriteAccess

◆ startAsProcess()

bool File::startAsProcess ( const String & parameters = String() ) const

Launches the file as a process.

if the file is executable, this will run it.
if it's a document of some kind, it will launch the document with its default viewer application.
if it's a folder, it will be opened in Explorer, Finder, or equivalent.

See also: revealToUser

◆ withFileExtension()

File File::withFileExtension ( StringRef newExtension ) const

Returns a version of this file with a different file extension.

e.g. File ("/moose/fish/foo.txt").withFileExtension ("html") returns "/moose/fish/foo.html"

Parameters

newExtension the new extension, either with or without a dot at the start (this doesn't make any difference). To get remove a file's extension altogether, pass an empty string into this function.

See also: getFileName, getFileExtension, hasFileExtension, getFileNameWithoutExtension

Member Data Documentation

◆ fullPath

String File::fullPath

private

◆ separator

const juce_wchar File::separator = '/'

static

The system-specific file separator character.

On Windows, this will be '\', on Mac/Linux, it'll be '/'

Referenced by ChildProcess::ActiveProcess::ActiveProcess().

◆ separatorString

const String File::separatorString

static

The system-specific file separator character, as a string.

On Windows, this will be '\', on Mac/Linux, it'll be '/'

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ SpecialLocationType

◆ TypesOfFileToFind

Constructor & Destructor Documentation

◆ File() [1/4]

◆ File() [2/4]

◆ File() [3/4]

◆ ~File()

◆ File() [4/4]

Member Function Documentation

◆ addToDock()

◆ addTrailingSeparator()

◆ appendData()

◆ appendText()

◆ areFileNamesCaseSensitive()

◆ containsSubDirectories()

◆ copyDirectoryTo()

◆ copyFileTo()

◆ copyInternal()

◆ create()

◆ createDirectory()

◆ createDirectoryInternal()

◆ createFileWithoutCheckingPath()

◆ createInputStream()

◆ createLegalFileName()

◆ createLegalPathName()

◆ createOutputStream()

◆ createShortcut()

◆ createSymbolicLink()

◆ createTempFile()

◆ deleteFile()

◆ deleteRecursively()

◆ descriptionOfSizeInBytes()

◆ exists()

◆ existsAsFile()

◆ findChildFiles()

◆ findFileSystemRoots()

◆ getBytesFreeOnVolume()

◆ getChildFile()

◆ getCreationTime()

◆ getCurrentWorkingDirectory()

◆ getFileExtension()

◆ getFileIdentifier()

◆ getFileName()

◆ getFileNameWithoutExtension()

◆ getFileTimesInternal()

◆ getFullPathName()

◆ getLastAccessTime()

◆ getLastModificationTime()

◆ getLinkedTarget()

◆ getMacOSType()

◆ getNonexistentChildFile()

◆ getNonexistentSibling()

◆ getNumberOfChildFiles()

◆ getParentDirectory()

◆ getPathUpToLastSlash()

◆ getRelativePathFrom()

◆ getSiblingFile()

◆ getSize()

◆ getSpecialLocation()

◆ getVersion()

◆ getVolumeLabel()

◆ getVolumeSerialNumber()

◆ getVolumeTotalSize()

◆ hasFileExtension()

◆ hashCode()

◆ hashCode64()

◆ hasIdenticalContentTo()

◆ hasWriteAccess()

◆ isAbsolutePath()

◆ isAChildOf()