juce_File.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
#if ! DOXYGEN && (JUCE_MAC || JUCE_IOS)
 using OSType = unsigned int;
#endif
 
//==============================================================================
class JUCE_API  File final
{
public:
    //==============================================================================
    File() = default;

    File (const String& absolutePath);

    File (const File&);

    ~File() = default;

    File& operator= (const String& newAbsolutePath);

    File& operator= (const File& otherFile);

    File (File&&) noexcept;

    File& operator= (File&&) noexcept;
 
    //==============================================================================
    bool exists() const;

    bool existsAsFile() const;

    bool isDirectory() const;

    bool isRoot() const;

    int64 getSize() const;

    static String descriptionOfSizeInBytes (int64 bytes);
 
    //==============================================================================
    const String& getFullPathName() const noexcept          { return fullPath; }

    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 hasReadAccess() 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;
 
    //==============================================================================
    enum TypesOfFileToFind
    {
        findDirectories             = 1,    
        findFiles                   = 2,    
        findFilesAndDirectories     = 3,    
        ignoreHiddenFiles           = 4     
    };
 
    enum class FollowSymlinks
    {
        no,

        noCycles,

        yes
    };

    Array<File> findChildFiles (int whatToLookFor,
                                bool searchRecursively,
                                const String& wildCardPattern = "*",
                                FollowSymlinks followSymlinks = FollowSymlinks::yes) const;

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

    int getNumberOfChildFiles (int whatToLookFor,
                               const String& wildCardPattern = "*") const;

    bool containsSubDirectories() const;
 
    //==============================================================================
    std::unique_ptr<FileInputStream> createInputStream() const;

    std::unique_ptr<FileOutputStream> createOutputStream (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;
 
    //==============================================================================
    static void findFileSystemRoots (Array<File>& results);

    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;
 
    //==============================================================================
    enum SpecialLocationType
    {
        userHomeDirectory,

        userDocumentsDirectory,

        userDesktopDirectory,

        userMusicDirectory,

        userMoviesDirectory,

        userPicturesDirectory,

        userApplicationDataDirectory,

        commonApplicationDataDirectory,

        commonDocumentsDirectory,

        tempDirectory,

        currentExecutableFile,

        currentApplicationFile,

        invokedExecutableFile,

        hostApplicationPath,
 
       #if JUCE_WINDOWS || DOXYGEN
        windowsSystemDirectory,
       #endif

        globalApplicationsDirectory,
 
       #if JUCE_WINDOWS || DOXYGEN
        globalApplicationsDirectoryX86,

        windowsLocalAppData
       #endif
    };

    static File JUCE_CALLTYPE getSpecialLocation (const SpecialLocationType type);
 
    //==============================================================================
    static File createTempFile (StringRef fileNameEnding);
 
    //==============================================================================
    static File getCurrentWorkingDirectory();

    bool setAsCurrentWorkingDirectory() const;
 
    //==============================================================================
    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);
 
    //==============================================================================
    bool createSymbolicLink (const File& linkFileToCreate, bool overwriteExisting) const;

    bool isSymbolicLink() const;

    File getLinkedTarget() const;

    static bool createSymbolicLink (const File& linkFileToCreate,
                                    const String& nativePathOfTarget,
                                    bool overwriteExisting);

    String getNativeLinkedTarget() const;
 
   #if JUCE_WINDOWS || DOXYGEN
    bool createShortcut (const String& description, const File& linkFileToCreate) const;

    bool isShortcut() const;
   #else
 
   #endif
 
    //==============================================================================
   #if JUCE_MAC || JUCE_IOS || DOXYGEN
    OSType getMacOSType() const;

    bool isBundle() const;
   #endif
 
   #if JUCE_MAC || DOXYGEN
    void addToDock() const;
   #endif
 
   #if JUCE_MAC || JUCE_IOS
    static File getContainerForSecurityApplicationGroupIdentifier (const String& appGroup);
   #endif
 
    //==============================================================================
    struct NaturalFileComparator
    {
        NaturalFileComparator (bool shouldPutFoldersFirst) noexcept : foldersFirst (shouldPutFoldersFirst) {}
 
        int compareElements (const File& firstFile, const File& secondFile) const
        {
            if (foldersFirst && (firstFile.isDirectory() != secondFile.isDirectory()))
                return firstFile.isDirectory() ? -1 : 1;
 
           #if NAMES_ARE_CASE_SENSITIVE
            return firstFile.getFullPathName().compareNatural (secondFile.getFullPathName(), true);
           #else
            return firstFile.getFullPathName().compareNatural (secondFile.getFullPathName(), false);
           #endif
        }
 
        bool foldersFirst;
    };
 
   #if JUCE_ALLOW_STATIC_NULL_VARIABLES && ! defined (DOXYGEN)
    /* These static objects are deprecated because it's too easy to accidentally use them indirectly
       during a static constructor, which leads to very obscure order-of-initialisation bugs.
       Use File::getSeparatorChar() and File::getSeparatorString(), and instead of File::nonexistent,
       just use File() or {}.
    */
    [[deprecated]] static const juce_wchar separator;
    [[deprecated]] static const StringRef separatorString;
    [[deprecated]] static const File nonexistent;
   #endif
 
private:
    //==============================================================================
    String fullPath;
 
    static String parseAbsolutePath (const String&);
    String getPathUpToLastSlash() const;
 
    Result createDirectoryInternal (const String&) const;
    bool copyInternal (const File&) const;
    bool moveInternal (const File&) const;
    bool replaceInternal (const File&) const;
    bool setFileTimesInternal (int64 m, int64 a, int64 c) const;
    void getFileTimesInternal (int64& m, int64& a, int64& c) const;
    bool setFileReadOnlyInternal (bool) const;
    bool setFileExecutableInternal (bool) const;
};
 
} // namespace juce