OpenShot Audio Library | OpenShotAudio 0.3.2
Loading...
Searching...
No Matches
juce::File Class Referencefinal

#include <juce_File.h>

Classes

struct  NaturalFileComparator
 

Public Types

enum  TypesOfFileToFind { findDirectories = 1 , findFiles = 2 , findFilesAndDirectories = 3 , ignoreHiddenFiles = 4 }
 
enum  SpecialLocationType {
  userHomeDirectory , userDocumentsDirectory , userDesktopDirectory , userMusicDirectory ,
  userMoviesDirectory , userPicturesDirectory , userApplicationDataDirectory , commonApplicationDataDirectory ,
  commonDocumentsDirectory , tempDirectory , currentExecutableFile , currentApplicationFile ,
  invokedExecutableFile , hostApplicationPath , globalApplicationsDirectory
}
 

Public Member Functions

 File ()=default
 
 File (const String &absolutePath)
 
 File (const File &)
 
 ~File ()=default
 
Fileoperator= (const String &newAbsolutePath)
 
Fileoperator= (const File &otherFile)
 
 File (File &&) noexcept
 
Fileoperator= (File &&) noexcept
 
bool exists () const
 
bool existsAsFile () const
 
bool isDirectory () const
 
bool isRoot () const
 
int64 getSize () const
 
const StringgetFullPathName () const noexcept
 
String getFileName () const
 
String getRelativePathFrom (const File &directoryToBeRelativeTo) const
 
String getFileExtension () const
 
bool hasFileExtension (StringRef extensionToTest) const
 
File withFileExtension (StringRef newExtension) const
 
String getFileNameWithoutExtension () const
 
int hashCode () const
 
int64 hashCode64 () const
 
File getChildFile (StringRef relativeOrAbsolutePath) const
 
File getSiblingFile (StringRef siblingFileName) const
 
File getParentDirectory () const
 
bool isAChildOf (const File &potentialParentDirectory) const
 
File getNonexistentChildFile (const String &prefix, const String &suffix, bool putNumbersInBrackets=true) const
 
File getNonexistentSibling (bool putNumbersInBrackets=true) const
 
bool operator== (const File &) const
 
bool operator!= (const File &) const
 
bool operator< (const File &) const
 
bool operator> (const File &) const
 
bool hasWriteAccess () const
 
bool setReadOnly (bool shouldBeReadOnly, bool applyRecursively=false) const
 
bool setExecutePermission (bool shouldBeExecutable) const
 
bool isHidden () const
 
uint64 getFileIdentifier () const
 
Time getLastModificationTime () const
 
Time getLastAccessTime () const
 
Time getCreationTime () const
 
bool setLastModificationTime (Time newTime) const
 
bool setLastAccessTime (Time newTime) const
 
bool setCreationTime (Time newTime) const
 
String getVersion () const
 
Result create () const
 
Result createDirectory () const
 
bool deleteFile () const
 
bool deleteRecursively (bool followSymlinks=false) const
 
bool moveToTrash () const
 
bool moveFileTo (const File &targetLocation) const
 
bool copyFileTo (const File &targetLocation) const
 
bool replaceFileIn (const File &targetLocation) const
 
bool copyDirectoryTo (const File &newDirectory) const
 
Array< FilefindChildFiles (int whatToLookFor, bool searchRecursively, const String &wildCardPattern="*") const
 
int findChildFiles (Array< File > &results, int whatToLookFor, bool searchRecursively, const String &wildCardPattern="*") const
 
int getNumberOfChildFiles (int whatToLookFor, const String &wildCardPattern="*") const
 
bool containsSubDirectories () const
 
FileInputStreamcreateInputStream () const
 
FileOutputStreamcreateOutputStream (size_t bufferSize=0x8000) const
 
bool loadFileAsData (MemoryBlock &result) const
 
String loadFileAsString () const
 
void readLines (StringArray &destLines) const
 
bool appendData (const void *dataToAppend, size_t numberOfBytes) const
 
bool replaceWithData (const void *dataToWrite, size_t numberOfBytes) const
 
bool appendText (const String &textToAppend, bool asUnicode=false, bool writeUnicodeHeaderBytes=false, const char *lineEndings="\r\n") const
 
bool replaceWithText (const String &textToWrite, bool asUnicode=false, bool writeUnicodeHeaderBytes=false, const char *lineEndings="\r\n") const
 
bool hasIdenticalContentTo (const File &other) const
 
String getVolumeLabel () const
 
int getVolumeSerialNumber () const
 
int64 getBytesFreeOnVolume () const
 
int64 getVolumeTotalSize () const
 
bool isOnCDRomDrive () const
 
bool isOnHardDisk () const
 
bool isOnRemovableDrive () const
 
bool startAsProcess (const String &parameters=String()) const
 
void revealToUser () const
 
bool setAsCurrentWorkingDirectory () const
 
bool createSymbolicLink (const File &linkFileToCreate, bool overwriteExisting) const
 
bool isSymbolicLink () const
 
File getLinkedTarget () const
 
String getNativeLinkedTarget () const
 

Static Public Member Functions

static String descriptionOfSizeInBytes (int64 bytes)
 
static void findFileSystemRoots (Array< File > &results)
 
static File JUCE_CALLTYPE getSpecialLocation (const SpecialLocationType type)
 
static File createTempFile (StringRef fileNameEnding)
 
static File getCurrentWorkingDirectory ()
 
static juce_wchar getSeparatorChar ()
 
static StringRef getSeparatorString ()
 
static String createLegalFileName (const String &fileNameToFix)
 
static String createLegalPathName (const String &pathNameToFix)
 
static bool areFileNamesCaseSensitive ()
 
static bool isAbsolutePath (StringRef path)
 
static File createFileWithoutCheckingPath (const String &absolutePath) noexcept
 
static String addTrailingSeparator (const String &path)
 
static bool createSymbolicLink (const File &linkFileToCreate, const String &nativePathOfTarget, bool overwriteExisting)
 

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

Definition at line 40 of file juce_File.h.

Member Enumeration Documentation

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

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.

Definition at line 829 of file juce_File.h.

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

Definition at line 547 of file juce_File.h.

Constructor & Destructor Documentation

◆ File() [1/4]

juce::File::File ( )
default

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.

Referenced by getChildFile().

◆ File() [2/4]

juce::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.

Definition at line 26 of file juce_File.cpp.

◆ File() [3/4]

juce::File::File ( const File other)

Creates a copy of another file object.

Definition at line 38 of file juce_File.cpp.

◆ ~File()

juce::File::~File ( )
default

Destructor.

◆ File() [4/4]

juce::File::File ( File &&  other)
noexcept

Move constructor

Definition at line 55 of file juce_File.cpp.

Member Function Documentation

◆ addTrailingSeparator()

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

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

Definition at line 227 of file juce_File.cpp.

Referenced by getChildFile(), and getRelativePathFrom().

◆ appendData()

bool juce::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

Definition at line 748 of file juce_File.cpp.

◆ appendText()

bool juce::File::appendText ( const String textToAppend,
bool  asUnicode = false,
bool  writeUnicodeHeaderBytes = false,
const char lineEndings = "\r\n" 
) 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.

If lineEndings is nullptr, then line endings in the text won't be modified. If you pass "\\n" or "\\r\\n" then this function will replace any existing line feeds.

See also
replaceWithText

Definition at line 771 of file juce_File.cpp.

◆ areFileNamesCaseSensitive()

bool juce::File::areFileNamesCaseSensitive ( )
static

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

Definition at line 238 of file juce_File.cpp.

◆ containsSubDirectories()

bool juce::File::containsSubDirectories ( ) const

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

See also
isDirectory, findChildFiles

Definition at line 596 of file juce_File.cpp.

◆ copyDirectoryTo()

bool juce::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
newDirectorythe 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.

Definition at line 328 of file juce_File.cpp.

◆ copyFileTo()

bool juce::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

Definition at line 307 of file juce_File.cpp.

◆ create()

Result juce::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

Definition at line 492 of file juce_File.cpp.

Referenced by juce::FileLogger::FileLogger().

◆ createDirectory()

Result juce::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

Definition at line 513 of file juce_File.cpp.

Referenced by juce::PropertiesFile::save().

◆ createFileWithoutCheckingPath()

File juce::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.

Definition at line 31 of file juce_File.cpp.

Referenced by getParentDirectory(), and juce::DirectoryIterator::next().

◆ createInputStream()

FileInputStream * juce::File::createInputStream ( ) const

Creates a stream to read from this file.

Note that this is an old method, and actually it's usually best to avoid it and instead use an RAII pattern with an FileInputStream directly, e.g.

if (input.openedOk())
{
input.read (etc...
}
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

Definition at line 729 of file juce_File.cpp.

Referenced by juce::URL::createInputStream(), juce::AiffAudioFormat::createMemoryMappedReader(), juce::WavAudioFormat::createMemoryMappedReader(), and juce::AudioFormatManager::createReaderFor().

◆ createLegalFileName()

String juce::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

Definition at line 838 of file juce_File.cpp.

Referenced by juce::PropertiesFile::Options::getDefaultFile().

◆ createLegalPathName()

String juce::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

Definition at line 823 of file juce_File.cpp.

◆ createOutputStream()

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

Creates a stream to write to this file.

Note that this is an old method, and actually it's usually best to avoid it and instead use an RAII pattern with an FileOutputStream directly, e.g.

if (output.openedOk())
{
output.read etc...
}

If the file exists, the stream that is returned will be positioned ready for writing at the end of the file. If you want to write to the start of the file, replacing the existing content, then you can do the following:

if (output.openedOk())
{
output.setPosition (0);
output.truncate();
...
}
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

Definition at line 739 of file juce_File.cpp.

◆ createSymbolicLink() [1/2]

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

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

Definition at line 998 of file juce_File.cpp.

Referenced by createSymbolicLink(), and juce::ZipFile::uncompressEntry().

◆ createSymbolicLink() [2/2]

bool juce::File::createSymbolicLink ( const File linkFileToCreate,
const String nativePathOfTarget,
bool  overwriteExisting 
)
static

Create a symbolic link to a native path and return a boolean to indicate success.

Use this method if you want to create a link to a relative path or a special native file path (such as a device file on Windows).

Definition at line 958 of file juce_File.cpp.

◆ createTempFile()

File juce::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).

Definition at line 946 of file juce_File.cpp.

Referenced by createTempFile().

◆ deleteFile()

bool juce::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.

If this file is a symlink, then the symlink will be deleted and not the target of the symlink.

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

Referenced by deleteRecursively(), replaceFileIn(), replaceWithData(), and juce::FileLogger::trimFileSize().

◆ deleteRecursively()

bool juce::File::deleteRecursively ( bool  followSymlinks = false) 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.

Parameters
followSymlinksIf true, then any symlink pointing to a directory will also recursively delete the contents of that directory
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

Definition at line 279 of file juce_File.cpp.

◆ descriptionOfSizeInBytes()

String juce::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.

Definition at line 477 of file juce_File.cpp.

◆ exists()

bool juce::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 copyFileTo(), create(), juce::FileLogger::FileLogger(), getNonexistentSibling(), moveFileTo(), juce::PropertiesFile::reload(), and startAsProcess().

◆ existsAsFile()

bool juce::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

Referenced by hasIdenticalContentTo(), loadFileAsData(), loadFileAsString(), and juce::dsp::Convolution::loadImpulseResponse().

◆ findChildFiles() [1/2]

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

Searches inside a directory for files matching a wildcard pattern. Note that there's a newer, better version of this method which returns the results array, and in almost all cases, you should use that one instead! This one is kept around mainly for legacy code to use.

Definition at line 573 of file juce_File.cpp.

◆ findChildFiles() [2/2]

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

Searches this 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. Note that the order in which files are returned is completely undefined!

Parameters
whatToLookFora 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
searchRecursivelyif true, all subdirectories will be recursed into to do an exhaustive search
wildCardPatternthe filename pattern to search for, e.g. "*.txt"
Returns
the set of files that were found
See also
getNumberOfChildFiles, DirectoryIterator

Definition at line 566 of file juce_File.cpp.

Referenced by copyDirectoryTo(), deleteRecursively(), juce::FileSearchPath::findChildFiles(), findChildFiles(), and setReadOnly().

◆ findFileSystemRoots()

static void juce::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 juce::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

◆ getChildFile()

File juce::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

Definition at line 414 of file juce_File.cpp.

Referenced by getChildFile(), getNonexistentChildFile(), and getSiblingFile().

◆ getCreationTime()

Time juce::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

Definition at line 534 of file juce_File.cpp.

◆ getCurrentWorkingDirectory()

static File juce::File::getCurrentWorkingDirectory ( )
static

Returns the current working directory.

See also
setAsCurrentWorkingDirectory

◆ getFileExtension()

String juce::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

Definition at line 669 of file juce_File.cpp.

Referenced by getNonexistentSibling().

◆ getFileIdentifier()

uint64 juce::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.

Referenced by juce::SystemStats::getDeviceIdentifiers().

◆ getFileName()

String juce::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

Definition at line 366 of file juce_File.cpp.

Referenced by juce::ZipFile::Builder::addFile(), and withFileExtension().

◆ getFileNameWithoutExtension()

String juce::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

Definition at line 371 of file juce_File.cpp.

Referenced by getNonexistentSibling().

◆ getFullPathName()

const String & juce::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

Definition at line 149 of file juce_File.h.

Referenced by createSymbolicLink(), and juce::dsp::Convolution::loadImpulseResponse().

◆ getLastAccessTime()

Time juce::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

Definition at line 533 of file juce_File.cpp.

◆ getLastModificationTime()

Time juce::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

Definition at line 532 of file juce_File.cpp.

Referenced by juce::ZipFile::Builder::addFile().

◆ getLinkedTarget()

File juce::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.

Definition at line 1004 of file juce_File.cpp.

◆ getNativeLinkedTarget()

String juce::File::getNativeLinkedTarget ( ) const

This returns the native path that the symbolic link points to. The returned path is a native path of the current OS and can be a relative, absolute or special path.

Referenced by getLinkedTarget().

◆ getNonexistentChildFile()

File juce::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
prefixthe string to use for the filename before the number
suffixthe string to add to the filename after the number
putNumbersInBracketsif true, this will create filenames in the format "prefix(number)suffix", if false, it will leave the brackets out.

Definition at line 606 of file juce_File.cpp.

Referenced by getNonexistentSibling().

◆ getNonexistentSibling()

File juce::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
putNumbersInBracketswhether to add brackets around the numbers that get appended to the new filename.

Definition at line 658 of file juce_File.cpp.

◆ getNumberOfChildFiles()

int juce::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
whatToLookFora 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
wildCardPatternthe filename pattern to search for, e.g. "*.txt"
Returns
the number of matches found
See also
findChildFiles, DirectoryIterator

Definition at line 586 of file juce_File.cpp.

Referenced by juce::DirectoryIterator::getEstimatedProgress().

◆ getParentDirectory()

File juce::File::getParentDirectory ( ) const

Returns the directory that contains this file or directory.

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

If you are already at the root directory ("/" or "C:") then this method will return the root directory.

Definition at line 360 of file juce_File.cpp.

Referenced by create(), createDirectory(), getNonexistentSibling(), getSiblingFile(), isAChildOf(), isRoot(), and juce::PropertiesFile::save().

◆ getRelativePathFrom()

String juce::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
directoryToBeRelativeTothe 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

Definition at line 882 of file juce_File.cpp.

◆ getSeparatorChar()

static juce_wchar juce::File::getSeparatorChar ( )
static

The system-specific file separator character. On Windows, this will be '\', on Mac/Linux, it'll be '/'

Referenced by addTrailingSeparator(), getChildFile(), getFileExtension(), getFileName(), getFileNameWithoutExtension(), getRelativePathFrom(), hasFileExtension(), isAbsolutePath(), and juce::ZipFile::uncompressEntry().

◆ getSeparatorString()

static StringRef juce::File::getSeparatorString ( )
static

The system-specific file separator character, as a string. On Windows, this will be '\', on Mac/Linux, it'll be '/'

Referenced by createDirectory().

◆ getSiblingFile()

File juce::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

Definition at line 471 of file juce_File.cpp.

Referenced by getLinkedTarget(), and withFileExtension().

◆ getSize()

int64 juce::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.

Referenced by hasIdenticalContentTo(), loadFileAsData(), and juce::FileLogger::trimFileSize().

◆ getSpecialLocation()

static File JUCE_CALLTYPE juce::File::getSpecialLocation ( const SpecialLocationType  type)
static

◆ getVersion()

String juce::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 juce::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

◆ getVolumeSerialNumber()

int juce::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

◆ getVolumeTotalSize()

int64 juce::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

◆ hasFileExtension()

bool juce::File::hasFileExtension ( StringRef  extensionToTest) const

Checks whether the file has a given extension.

Parameters
extensionToTestthe 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

Definition at line 679 of file juce_File.cpp.

Referenced by juce::AudioFormat::canHandleFile(), and hasFileExtension().

◆ hashCode()

int juce::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.

Definition at line 398 of file juce_File.cpp.

◆ hashCode64()

int64 juce::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.

Definition at line 399 of file juce_File.cpp.

◆ hasIdenticalContentTo()

bool juce::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.

Definition at line 788 of file juce_File.cpp.

◆ hasWriteAccess()

bool juce::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

◆ isAbsolutePath()

bool juce::File::isAbsolutePath ( StringRef  path)
static

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

Definition at line 402 of file juce_File.cpp.

Referenced by getChildFile().

◆ isAChildOf()

bool juce::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.

Definition at line 382 of file juce_File.cpp.

Referenced by isAChildOf().

◆ isDirectory()

bool juce::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

Referenced by containsSubDirectories(), copyDirectoryTo(), createDirectory(), createSymbolicLink(), deleteRecursively(), juce::FileSearchPath::removeNonExistentPaths(), juce::PropertiesFile::save(), and setReadOnly().

◆ isHidden()

bool juce::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 juce::File::isOnCDRomDrive ( ) const

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

◆ isOnHardDisk()

bool juce::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 juce::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 juce::File::isRoot ( ) const

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

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

Definition at line 127 of file juce_File.cpp.

◆ isSymbolicLink()

bool juce::File::isSymbolicLink ( ) const

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

Referenced by deleteRecursively(), and getLinkedTarget().

◆ loadFileAsData()

bool juce::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
resultthe 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

Definition at line 541 of file juce_File.cpp.

◆ loadFileAsString()

String juce::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.

Definition at line 550 of file juce_File.cpp.

Referenced by juce::JSON::parse(), and readLines().

◆ moveFileTo()

bool juce::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

Definition at line 290 of file juce_File.cpp.

Referenced by replaceFileIn().

◆ moveToTrash()

bool juce::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 juce::File::operator!= ( const File other) const

Compares the pathnames for two files.

Definition at line 257 of file juce_File.cpp.

◆ operator<()

bool juce::File::operator< ( const File other) const

Compares the pathnames for two files.

Definition at line 258 of file juce_File.cpp.

◆ operator=() [1/3]

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

Copies from another file object.

Definition at line 49 of file juce_File.cpp.

◆ operator=() [2/3]

File & juce::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.

Definition at line 43 of file juce_File.cpp.

◆ operator=() [3/3]

File & juce::File::operator= ( File &&  other)
noexcept

Move assignment operator

Definition at line 60 of file juce_File.cpp.

◆ operator==()

bool juce::File::operator== ( const File other) const

Compares the pathnames for two files.

Definition at line 256 of file juce_File.cpp.

◆ operator>()

bool juce::File::operator> ( const File other) const

Compares the pathnames for two files.

Definition at line 259 of file juce_File.cpp.

◆ readLines()

void juce::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.

Definition at line 560 of file juce_File.cpp.

◆ replaceFileIn()

bool juce::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

Definition at line 313 of file juce_File.cpp.

◆ replaceWithData()

bool juce::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

Definition at line 760 of file juce_File.cpp.

◆ replaceWithText()

bool juce::File::replaceWithText ( const String textToWrite,
bool  asUnicode = false,
bool  writeUnicodeHeaderBytes = false,
const char lineEndings = "\r\n" 
) 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

Definition at line 781 of file juce_File.cpp.

◆ revealToUser()

void juce::File::revealToUser ( ) const

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

See also
startAsProcess

◆ setAsCurrentWorkingDirectory()

bool juce::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 juce::File::setCreationTime ( Time  newTime) const

Changes the creation date for this file.

Parameters
newTimethe time to apply to the file
Returns
true if it manages to change the file's time.
See also
getCreationTime, setLastModificationTime, setLastAccessTime

Definition at line 538 of file juce_File.cpp.

◆ setExecutePermission()

bool juce::File::setExecutePermission ( bool  shouldBeExecutable) const

Changes the execute-permissions of a file.

Parameters
shouldBeExecutablewhether to add or remove execute-permission
Returns
true if it manages to change the file's permissions.

Definition at line 274 of file juce_File.cpp.

◆ setLastAccessTime()

bool juce::File::setLastAccessTime ( Time  newTime) const

Changes the last-access time for this file.

Parameters
newTimethe time to apply to the file
Returns
true if it manages to change the file's time.
See also
getLastAccessTime, setLastModificationTime, setCreationTime

Definition at line 537 of file juce_File.cpp.

◆ setLastModificationTime()

bool juce::File::setLastModificationTime ( Time  newTime) const

Changes the modification time for this file.

Parameters
newTimethe time to apply to the file
Returns
true if it manages to change the file's time.
See also
getLastModificationTime, setLastAccessTime, setCreationTime

Definition at line 536 of file juce_File.cpp.

◆ setReadOnly()

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

Changes the write-permission of a file or directory.

Parameters
shouldBeReadOnlywhether to add or remove write-permission
applyRecursivelyif 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

Definition at line 262 of file juce_File.cpp.

◆ startAsProcess()

bool juce::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

Definition at line 723 of file juce_File.cpp.

◆ withFileExtension()

File juce::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
newExtensionthe 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

Definition at line 704 of file juce_File.cpp.


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