ofDirectory

class methods

ofDirectory is a class for reading and manipulating directories on the file system through openFrameworks.

Here is a common way to use it:

//some path, may be absolute or relative to bin/data
string path = "/my/path/file"; 
ofDirectory dir(path);
//only show png files
dir.allowExt("png");
//populate the directory object
dir.listDir();

//go through and print out all the paths
for(int i = 0; i < dir.size(); i++){
    ofLogNotice(dir.getPath(i));
}

Documentation from code comments


Path to a directory. Can be used to query file and directory contents.

ofDirectory()

ofDirectory::ofDirectory()

Constructs an empty directory object.

Documentation from code comments


Create an ofDirectory instance

Does not refer to a specific directory until you either open or create a directory path.

ofDirectory(...)

ofDirectory::ofDirectory(const filesystem::path &path)

Constructs a directory object and calls open() on the provided path. The contents of the path are not accessible until listDir() is called.

Documentation from code comments


Create an ofDirectory instance and attempt to open the path.

Parameters:

path directory path

allowExt(...)

void ofDirectory::allowExt(const string &extension)

Adds an allowed extension to the list of filters when listing directories. Use this to set any number of filters before calling listDir().

For example if you wanted to only get images in a directory, you may set several filters:

string path = "/path/to/images";
ofDirectory dir(path);
dir.allowExt("png");
dir.allowExt("jpg");
dir.allowExt("gif");
dir.listDir();

Documentation from code comments


Allow a file extension when listing the contents the current directory path.

Setting an allowed extension enables a whitelist mode which only lists extensions which have been explicitly allowed.

Parameters:

extension file type extension ie. "jpg", "png", "txt", etc

begin()

vector< ofFile >::const_iterator ofDirectory::begin()

canExecute()

bool ofDirectory::canExecute()

Returns true if the current directory is executable. An executable directory can be entered into with command such as cd.

Documentation from code comments


Check if the current path is executable.

Returns: true if executable

canRead()

bool ofDirectory::canRead()

Returns true if the open directory can be read.

Documentation from code comments


Check if the current path is readable.

Returns: true if readable

canWrite()

bool ofDirectory::canWrite()

Returns true if the open directory can be written to.

Documentation from code comments


Check if the current path is writeable.

Returns: true if writable

close()

void ofDirectory::close()

Closes the directory.

Documentation from code comments


Close the currently open path.

copyTo(...)

bool ofDirectory::copyTo(const filesystem::path &path, bool bRelativeToData=true, bool overwrite=false)

Copies the directory into path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the copy.

Documentation from code comments


Copy the current file or directory path to a new path.

Copies relative to the data path & does not overwrite by default does not change the current path & assumes the new path is in the data directory.

Parameters:

path destination file or directory path

bRelativeToData set to false if you are working with paths that are not in the data directory

overwrite set to true if you want to overwrite the file or directory at the new path

Returns: true if the copy was successful

create(...)

bool ofDirectory::create(bool recursive=false)

Creates the directory if it doesn't exist already. A common reason to use create is to ensure that you are able to write files to a known path, like so

string path = "/path/to/file";
ofDirectory dir(path);
if(!dir.exists()){
    dir.create(true);
}
//now you can be sure that path exists

The recursive boolean flag will indicate if you'd like to create directories all the directories required to reach the given path. In our example, if "/path/to" didn't already exist, the call to create() would also create these. If recursive were set to false, the directory would not be created.

Documentation from code comments


Create a directory at the current path.

Parameters:

bRecursive set to true to automatically create nested directories as required

createDirectory(...)

bool ofDirectory::createDirectory(const filesystem::path &dirPath, bool bRelativeToData=true, bool recursive=false)

Static method to create a directory at a given path.

Documentation from code comments


Create a directory at a given path.

Creates relative to the data path by default.

Parameters:

dirPath directory path

bRelativeToData set to false if you are working with paths that are not in the data directory

bRecursive set to true to automatically create nested directories as required

Returns: true if directory was created successfully

doesDirectoryExist(...)

bool ofDirectory::doesDirectoryExist(const filesystem::path &dirPath, bool bRelativeToData=true)

Returns true if the directory at dirPath exists.

Documentation from code comments


Check if a directory exists at a given path.

Assumes directory path is relative to the data path by default.

Parameters:

dirPath directory path

bRelativeToData set to false if you are working with paths that are not in the data directory

Returns: true if the directory exists

end()

vector< ofFile >::const_iterator ofDirectory::end()

exists()

bool ofDirectory::exists()

Returns true if the open directory exists. Great to be used in conjunction with ofDirectory::create()

Documentation from code comments


Check if a directory exists at the current path.

Returns: true if exists

getAbsolutePath()

string ofDirectory::getAbsolutePath()

Documentation from code comments


Get the absolute, full path of the directory, ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images".

\return current path as an absolute path

getFile(...)

ofFile ofDirectory::getFile(size_t position, ofFile::Mode mode=Reference, bool binary=true)

Documentation from code comments


Open an ofFile instance using the path a given position in the directory contents list.

Opens as a binary file with readonly access by default.

Warning: Call listDir() before using this function or the directory contents list will be empty. \throw Throws an out of bounds exception if position >= the number of listed directory contents.

Parameters:

position array index in the directory contents list

mode file access mode depending on how you plan to use the file (read only, read write, etc)

binary set to false if you are working with a text file & want lines split at endline characters automatically

Returns: ofFile instance

getFiles()

const vector< ofFile > & ofDirectory::getFiles()

Returns a vector of ofFile objects populated by a prior call to listDir(). The files are opened in ofFile::Reference mode.

Documentation from code comments


Get files and directories in the directory contents list.

Directory contents are automatically listed.

Returns: vector of files in the directory

getName(...)

string ofDirectory::getName(size_t position)

Returns the file name,(eg "mypicture.png") with extension but not the enclosing path at a given index. Position must be less than the result of numFiles().

Documentation from code comments


Get the filename at a given position in the directory contents list, ie. "duck.jpg".

Warning: Call listDir() before using this function or the directory contents list will be empty. \throws Throws an out of bounds exception if position >= the number of listed directory contents.

Parameters:

position array index in the directory contents list

Returns: file or directory name

getOriginalDirectory()

string ofDirectory::getOriginalDirectory()

Documentation from code comments


Returns: the current path

getPath(...)

string ofDirectory::getPath(size_t position)

Returns the absolute path,(eg "/path/to/files/mypicture.png"). Position must be less than the result of size().

Documentation from code comments


Get the full path of the file or directory at a given position in the directory contents list.

Warning: Call listDir() before using this function or the directory contents list will be empty. \throws Throws an out of bounds exception if position >= the number of listed directory contents.

Parameters:

position array index in the directory contents list

Returns: file or directory name including the current path

getShowHidden()

bool ofDirectory::getShowHidden()

Returns if hidden files are set to be shown or not.

Documentation from code comments


Check whether hidden files & directories are included when listing files.

Mac & Linux denote hidden directories by prepending a period -> ".hello".

Returns: true if hidden files are shown

getSorted()

ofDirectory ofDirectory::getSorted()

Documentation from code comments


Get a sorted ofDirectory instance using the current path.

Returns: sorted ofDirectory instance

isDirectory()

bool ofDirectory::isDirectory()

Returns true if the given path is actually a directory.

Documentation from code comments


Check if the current path is indeed a directory and not a file.

Returns: true if a directory

isDirectoryEmpty(...)

bool ofDirectory::isDirectoryEmpty(const filesystem::path &dirPath, bool bRelativeToData=true)

Returns true if the directory at dirPath is empty.

Documentation from code comments


Check if a directory at a given path is empty.

Assumes directory path is relative to the data path by default.

Parameters:

dirPath directory path

bRelativeToData set to false if you are working with paths that are not in the data directory

Returns: true if the directory is empty aka contains no files or directories

isHidden()

bool ofDirectory::isHidden()

Returns true if the directory is hidden in the file system.

Documentation from code comments


Check if the current path is hidden.

Works on Mac & Linux which denote hidden directories by prepending a period -> ".hello", however always returns false on Windows.

Returns: true if hidden

listDir()

size_t ofDirectory::listDir()

Populates the directory with files. Call this after opening a directory and setting filters. After this call, size(), getPath(position), and getName(position) can be used to access the contents of the directory.

Documentation from code comments


Open and read the contents of the current directory.

Uses allowed extension whitelist to ignore unwanted file types if allowExt() has been called.

Returns: number of paths found

listDir(...)

size_t ofDirectory::listDir(const string &path)

Opens and populates the directory with files. Returns the number of files found.

Documentation from code comments


Open and read the contents of a directory.

Uses allowed extension whitelist to ignore unwanted file types if allowExt() has been called.

Parameters:

path directory path

Returns: number of paths found

moveTo(...)

bool ofDirectory::moveTo(const filesystem::path &path, bool bRelativeToData=true, bool overwrite=false)

Moves the directory into another directory at path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the move.

Documentation from code comments


Move the current file or directory path to a new path.

Moves relative to the data path & does not overwrite by default does not change the current path & assumes the new path is in the data directory.

Parameters:

path destination file or directory path

bRelativeToData set to false if you are working with paths that are not in the data directory

overwrite set to true if you want to overwrite the file or directory at the new path

Returns: true if the copy was successful

open(...)

void ofDirectory::open(const filesystem::path &path)

Opens a path. At this point you can see if the directory exists by calling exists() but the contents of the path are not accessible until listDir() is called.

Documentation from code comments


Open a directory path, clears the current file list.

Parameters:

path directory path

openFromCWD(...)

void ofDirectory::openFromCWD(const filesystem::path &path)

Documentation from code comments


Open a directory path relative to the current working directory without calling ofToDataPath internally, clears the current file list.

Parameters:

path directory path

operator!=(...)

bool ofDirectory::operator!=(const ofDirectory &dir)

Returns true if this directory and another have different paths.

operator

bool ofDirectory::operator

Returns true if the right hand side directory is alphabetically after the left hand side directory.

operator<=(...)

bool ofDirectory::operator<=(const ofDirectory &dir)

Returns true if the right hand side directory is alphabetically after or equal to the left hand side directory.

operator==(...)

bool ofDirectory::operator==(const ofDirectory &dir)

Returns true if this directory and another have the same path.

operator>(...)

bool ofDirectory::operator>(const ofDirectory &dir)

Returns true if the left hand side directory is alphabetically after the right hand side directory.

operator>=(...)

bool ofDirectory::operator>=(const ofDirectory &dir)

Returns true if the left hand side directory is alphabetically after or equal to the right hand side directory;

operator[](...)

ofFile ofDirectory::operator[](size_t position)

Operator for accessing files with array notation syntax. Call is equivalent to ofFile::getFile(position).

Documentation from code comments


Access directory contents via th array operator.

Warning: Call listDir() before using this function or the directory contents list will be empty. \throw Throws an out of bounds exception if position >= the number of listed directory contents.

Parameters:

position array index in the directory contents list

Returns: opened ofFile instance

path()

string ofDirectory::path()

Returns the currently opened path.

Documentation from code comments


Get the current path.

Returns: current path

rbegin()

vector< ofFile >::const_reverse_iterator ofDirectory::rbegin()

remove(...)

bool ofDirectory::remove(bool recursive)

Deletes the directory. If recursive is set to false and this directory contains others the remove will fail.

Documentation from code comments


Removes the file or directory at the current path.

Does not remove non-empty directories by default.

Warning: Be careful! This deletes a file or folder. :)

Parameters:

recursive set to true to remove a non-empty directory and its contents

Returns: true if the path was removed successfully

removeDirectory(...)

bool ofDirectory::removeDirectory(const filesystem::path &path, bool deleteIfNotEmpty, bool bRelativeToData=true)

Removes a directory. If deleteIfNotEmpty is set to false and the directory contains files the call will fail.

Documentation from code comments


remove a directory at a given path

Parameters:

deleteIfNotEmpty set to true if you want to recursively delete the directory and its contents

bRelativeToData set to false if you are working with paths that are not in the data directory

Returns: true if the path was removed successfully

renameTo(...)

bool ofDirectory::renameTo(const filesystem::path &path, bool bRelativeToData=true, bool overwrite=false)

Renames the directory to the path path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the rename.

Documentation from code comments


Rename the current file or directory path to a new path.

Renames relative to the data path & does not overwrite by default does not change the current path & assumes the new path is in the data directory.

Parameters:

path destination file or directory path

bRelativeToData set to false if you are working with paths that are not in the data folder

overwrite set to true if you want to overwrite the file or directory at the new path

Returns: true if the copy was successful

rend()

vector< ofFile >::const_reverse_iterator ofDirectory::rend()

reset()

void ofDirectory::reset()

Resets the current directory. Equivalent to close().

Documentation from code comments


Closes the directory.

This is for backwards compatibility with ofxDirList.

setExecutable(...)

void ofDirectory::setExecutable(bool executable=true)

Enables or disables execution on the current open directory. If the directory is executable then it can be entered through commands such as cd.

Documentation from code comments


Set the executable flag of the current path.

Parameters:

executable set to true to make path executable

setReadable(...)

void ofDirectory::setReadable(bool readable=true)

Documentation from code comments


Set the readable flag of the current path.

Parameters:

readable set to true to make path readable

setShowHidden(...)

void ofDirectory::setShowHidden(bool showHidden)

Sets whether or not the call to listDir() will return hidden files.

Documentation from code comments


Show hidden files & directories when listing files?

Mac & Linux denote hidden directories by prepending a period -> ".hello".

Parameters:

showHidden set to true to show hidden files

setWriteable(...)

void ofDirectory::setWriteable(bool writeable=true)

Enables or disables writeable on the current open directory.

Documentation from code comments


Set the writable flag of the current path.

Parameters:

writable set to true to make path writable

size()

size_t ofDirectory::size()

Returns the number of files contained within the directory. Set after listDir() is called.

Documentation from code comments


Get the number of paths in the current directory list.

Warning: Call listDir() before using this function or it will return 0 since the directory list will be empty.

Returns: number of paths

sort()

void ofDirectory::sort()

Sorts the contents of the directory by filename.

Documentation from code comments


Sort the directory contents list alphabetically.

Warning: Call listDir() before using this function or there will be nothing to sort.

sortByDate()

void ofDirectory::sortByDate()

Documentation from code comments


Sort the directory contents list by date.

Warning: Call listDir() before using this function or there will be nothing to sort.

If you have any doubt about the usage of this module you can ask in the forum.

If you want to contribute better documentation or start documenting this section you can do so here

If you find anything wrong with this docs you can report any error by opening an issue