ofDocsdocumentation utils ofDirectory

ofDirectory

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));
}


allowExt( ... )

void allowExt(const string &extension)

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

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

canExecute( )

bool canExecute()

Check if the current path is executable.

Returns: true if executable

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


canRead( )

bool canRead()

Check if the current path is readable.

Returns: true if readable

Returns true if the open directory can be read.


canWrite( )

bool canWrite()

Check if the current path is writeable.

Returns: true if writable

Returns true if the open directory can be written to.


close( )

void close()

Close the currently open path.

Closes the directory.


copyTo( ... )

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

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

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.


create( ... )

bool create(bool recursive=false)

Create a directory at the current path.

Parameters:

bRecursive set to true to automatically create nested directories as required

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.


createDirectory( ... )

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

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

Static method to create a directory at a given path.


doesDirectoryExist( ... )

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

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

Returns true if the directory at dirPath exists.


exists( )

bool exists()

Check if a directory exists at the current path.

Returns: true if exists

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


getAbsolutePath( )

string getAbsolutePath()

getFile( ... )

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

getName( ... )

string 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().


getOriginalDirectory( )

string getOriginalDirectory()

Returns: the current path


getPath( ... )

string getPath(size_t position)

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


getShowHidden( )

bool getShowHidden()

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


getSorted( )

ofDirectory getSorted()

Get a sorted ofDirectory instance using the current path.

Returns: sorted ofDirectory instance


isDirectory( )

bool isDirectory()

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

Returns: true if a directory

Returns true if the given path is actually a directory.


isDirectoryEmpty( ... )

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

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

Returns true if the directory at dirPath is empty.


isHidden( )

bool isHidden()

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


listDir( ... )

size_t listDir(const string &path)

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

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


listDir( )

size_t listDir()

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

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.


moveTo( ... )

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

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

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.


ofDirectory( ... )

ofDirectory(const filesystem::path &path)

Create an ofDirectory instance and attempt to open the path.

Parameters:

path directory path

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


ofDirectory( )

ofDirectory()

Create an ofDirectory instance

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

Constructs an empty directory object.


open( ... )

void open(const filesystem::path &path)

Open a directory path, clears the current file list.

Parameters:

path directory 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.


openFromCWD( ... )

void openFromCWD(const filesystem::path &path)

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 operator!=(const ofDirectory &dir)

Returns true if this directory and another have different paths.


operator<( ... )

bool operator<(const ofDirectory &dir)

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


operator<=( ... )

bool 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 operator==(const ofDirectory &dir)

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


operator[]( ... )

ofFile operator[](size_t position)

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


path( )

string path()

Get the current path.

Returns: current path

Returns the currently opened path.


remove( ... )

bool remove(bool recursive)

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

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


removeDirectory( ... )

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

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

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


renameTo( ... )

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

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

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.


reset( )

void reset()

Closes the directory.

This is for backwards compatibility with ofxDirList.

Resets the current directory. Equivalent to close().


setExecutable( ... )

void setExecutable(bool executable=true)

Set the executable flag of the current path.

Parameters:

executable set to true to make path executable

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


setReadable( ... )

void setReadable(bool readable=true)

Set the readable flag of the current path.

Parameters:

readable set to true to make path readable


setShowHidden( ... )

void setShowHidden(bool showHidden)

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


setWriteable( ... )

void setWriteable(bool writeable=true)

Set the writable flag of the current path.

Parameters:

writable set to true to make path writable

Enables or disables writeable on the current open directory.


size( )

size_t size()

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

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


sort( )

void sort()

Sort the directory contents list alphabetically.

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

Sorts the contents of the directory by filename.


sortByDate( )

void sortByDate()

Sort the directory contents list by date.

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