`filelib.h`

This file exports a standardized set of tools for working with files. The library offers at least some portability across the file systems used in the three supported platforms: Mac OSX, Windows, and Linux. Directory and search paths are allowed to contain separators in any of the supported styles, which usually makes it possible to use the same code on different platforms.

Functions
createDirectory(`path`)	Creates a new directory for the specified path.
createDirectoryPath(`path`)	Creates a new directory for the specified path.
defaultExtension(`filename`, `ext`)	Adds an extension to a file name if none already exists.
deleteFile(`filename`)	Deletes the specified file.
expandPathname(`filename`)	Expands a filename into a canonical name for the platform.
fileExists(`filename`)	Returns `true` if the specified file exists.
findOnPath(`path`, `filename`)	Returns the canonical name of a file found using a search path.
getCurrentDirectory()	Returns an absolute filename for the current directory.
getDirectoryPathSeparator()	Returns the standard directory path separator used on this platform.
getExtension(`filename`)	Returns the extension of `filename`.
getHead(`filename`)	Returns all but the last component of a path name.
getRoot(`filename`)	Returns the root of `filename`.
getSearchPathSeparator()	Returns the standard search path separator used on this platform.
getTail(`filename`)	Returns the last component of a path name.
getTempDirectory()	Returns the operating system's temporary directory path as a string.
isDirectory(`filename`)	Returns `true` if the specified file is a directory.
isFile(`filename`)	Returns `true` if the specified file is a regular file.
isSymbolicLink(`filename`)	Returns `true` if the specified file is a symbolic link.
listDirectory(`path`) listDirectory(`path`, `v`)	Returns an alphabetized vector of the files in the specified directory, or adds them to the given existing vector `v`.
matchFilenamePattern(`filename`, `pattern`)	Determines whether the filename matches the specified pattern.
openFile(`stream`, `filename`)	Opens the filestream `stream` using the specified filename.
openFileDialog(`stream`) openFileDialog(`stream`, `title`) openFileDialog(`stream`, `title`, `path`)	Opens a dialog that allows the user to choose the file.
openOnPath(`stream`, `path`, `filename`)	Opens a file using a search path.
promptUserForFile(`stream`, `prompt`) promptUserForFile(`prompt`)	Asks the user for the name of a file.
readEntireFile(`is`, `v`)	Reads the entire contents of the specified input stream into the string vector `lines`.
readEntireFile(`filename`)	Reads the entire contents of the specified file and returns them as a `string`.
renameFile(`oldname`, `newname`)	Renames a file.
rewindStream(`stream`)	Moves an input stream back to its beginning so it can be read again.
setCurrentDirectory(`filename`)	Changes the current directory to the specified path.
writeEntireFile(`filename`, `text`, `append`)	Writes the given text to the specified file.

Function detail

bool openFile(ifstream& stream, string filename);
bool openFile(ofstream& stream, string filename);

Opens the filestream stream using the specified filename. This function is similar to the open method of the stream classes, but uses a C++ string object instead of the older C-style string. If the operation succeeds, openFile returns true; if it fails, openFile sets the failure flag in the stream and returns false.

Usage:

if (openFile(stream, filename)) ...

string promptUserForFile(ifstream& stream, string prompt = "", string reprompt = "");
string promptUserForFile(ofstream& stream, string prompt = "", string reprompt = "");
string promptUserForFile(string prompt = "", string reprompt = "");

Asks the user for the name of a file. The file is opened using the reference parameter stream, and the function returns the name of the file. If the requested file cannot be opened, the user is given additional chances to enter a valid file.

The optional prompt argument provides an input prompt for the user.

The also optional reprompt argument provides an output message displayed each time if the user types a file that is not found. If no value is passed it defaults to, "Unable to open that file. Try again.".

If no stream reference is passed, it is up to you to create an ifstream object and open it upon return from this function.

Usage:

string filename = promptUserForFile(stream, prompt);

string openFileDialog(ifstream& stream);
string openFileDialog(ifstream& stream, string title);
string openFileDialog(ifstream& stream, string title, string path);
string openFileDialog(ofstream& stream);
string openFileDialog(ofstream& stream, string title);
string openFileDialog(ofstream& stream, string title, string path);

Opens a dialog that allows the user to choose the file. The title parameter is displayed in the dialog title. The path parameter is used to set the working directory; if path does not appear, openFileDialog uses the current directory.

Usage:

string filename = openFileDialog(stream);
string filename = openFileDialog(stream, title);
string filename = openFileDialog(stream, title, path);

void readEntireFile(istream& is, Vector<string>& lines);
void readEntireFile(istream& is, vector<string>& lines);

Reads the entire contents of the specified input stream into the string vector lines. The client is responsible for opening and closing the stream. The vector can be either an STL vector or a Vector as defined in the Stanford C++ libraries.

Usage:

readEntireFile(is, lines);

string readEntireFile(string filename);

Reads the entire contents of the specified file and returns them as a string. If the file cannot be opened or read, throws an error.

Usage:

string text = readEntireFile(filename);

string getRoot(string filename);

Returns the root of filename. The root consists of everything in filename up to the last dot and the subsequent extension. If no dot appears in the final component of the filename, getRoot returns the entire name.

Usage:

string root = getRoot(filename);

string getExtension(string filename);

Returns the extension of filename. The extension consists of the separating dot and all subsequent characters. If no dot exists in the final component, getExtension returns the empty string. These semantics ensure that concatenating the root and the extension always returns the original filename.

Usage:

ext = getExtension(filename);

string getHead(string filename);

Returns all but the last component of a path name. The components of the path name can be separated by any of the directory path separators (forward or reverse slashes). The special cases are illustrated by the following examples:

   getHead("a/b")  = "a"     getTail("a/b")   = "b"
   getHead("a")    = ""      getTail("a")     = "a"
   getHead("/a")   = "/"     getTail("/a")    = "a"
   getHead("/")    = "/"     getTail("/")     = ""

Usage:

head = getHead(filename);

string getTail(string filename);

Returns the last component of a path name. The components of the path name can be separated by any of the directory path separators (forward or reverse slashes). For details on the interpretation of special cases, see the comments for the getHead function.

Usage:

tail = getTail(filename);

string getTempDirectory();

Returns the operating system's temporary directory path as a string. For example, on a Linux system this is often "/tmp" or "/var/tmp" and on a Windows system it is often something like "C:\Users\YourUserName\Local Settings\Temp".

Usage:

string tempdir = getTempDirectory();

Available since: 2014/10/08 version of C++ library

string defaultExtension(string filename, string ext);

Adds an extension to a file name if none already exists. If the extension argument begins with a leading *, any existing extension in filename is replaced by ext.

Usage:

string newname = defaultExtension(filename, ext);

string openOnPath(ifstream& stream, string path, string filename);
string openOnPath(ofstream& stream, string path, string filename);

Opens a file using a search path. If openOnPath is successful, it returns the first path name on the search path for which stream.open succeeds. The path argument consists of a list of directories that are prepended to the filename, unless filename begins with an absolute directory marker, such as / or ~. The directories in the search path may be separated either by colons (Unix or Mac OS) or semicolons (Windows). If the file cannot be opened, the failure bit is set in the stream parameter, and the openOnPath function returns the empty string.

Usage:

string pathname = openOnPath(stream, path, filename);

string findOnPath(string path, string filename);

Returns the canonical name of a file found using a search path. The findOnPath function is similar to openOnPath, except that it doesn't actually return an open stream. If no matching file is found, findOnPath returns the empty string.

Usage:

string pathname = findOnPath(path, filename);

void deleteFile(string filename);

Deletes the specified file. Errors are reported by calling error.

Usage:

deleteFile(filename);

void renameFile(string oldname, string newname);

Renames a file. Errors are reported by calling error in the implementation.

Usage:

renameFile(oldname, newname);

bool fileExists(string filename);

Returns true if the specified file exists.

Usage:

if (fileExists(filename)) ...

bool isFile(string filename);

Returns true if the specified file is a regular file.

Usage:

if (isFile(filename)) ...

bool isSymbolicLink(string filename);

Returns true if the specified file is a symbolic link.

Usage:

if (isSymbolicLink(filename)) ...

bool isDirectory(string filename);

Returns true if the specified file is a directory.

Usage:

if (isDirectory(filename)) ...

void setCurrentDirectory(string path);

Changes the current directory to the specified path.

Usage:

setCurrentDirectory(filename);

string getCurrentDirectory();

Returns an absolute filename for the current directory.

Usage:

string filename = getCurrentDirectory();

void createDirectory(string path);

Creates a new directory for the specified path. The createDirectory function does not report an error if the directory already exists. Unlike createDirectoryPath, createDirectory does not create missing directories along the path. If some component of path does not exist, this function signals an error.

Usage:

createDirectory(path);

void createDirectoryPath(string path);

Creates a new directory for the specified path. If intermediate components of path do not exist, this function creates them as needed.

Usage:

createDirectoryPath(path);

string expandPathname(string filename);

Expands a filename into a canonical name for the platform.

Usage:

string pathname = expandPathname(filename);

Vector<string> listDirectory(string path);
void listDirectory(string path, Vector<string>& v);
void listDirectory(string path, vector<string>& v);

Adds an alphabetized list of the names of the files in the specified directory to the string vector v. This list excludes the entries . and ...

Usage:

// first form
Vector<string> files = listDirectory(path);

// second form
Vector<string> files;
listDirectory(path, files);

bool matchFilenamePattern(string filename, string pattern);

Determines whether the filename matches the specified pattern. The pattern string is interpreted in much the same way that a Unix shell expands filenames and supports the following wildcard options:

   ?      Matches any single character
   *      Matches any sequence of characters
   [...]  Matches any of the specified characters
   [^...] Matches any character except the specified ones

The last two options allow a range of characters to be specified in the form a-z.

Usage:

if (matchFilenamePattern(filename, pattern)) ...

string getDirectoryPathSeparator();

Returns the standard directory path separator used on this platform.

Usage:

string sep = getDirectoryPathSeparator();

string getSearchPathSeparator();

Returns the standard search path separator used on this platform.

Usage:

string sep = getSearchPathSeparator();

void rewindStream(istream& stream);

Moves an input stream back to its beginning so it can be read again. This function is implemented by calling the clear member function on the stream to reset any flags such as the fail flag, then calling the seekg member function to move the stream's internal cursor back to its beginning.

Usage:

rewindStream(stream);

Available since: 2014/02/01 version of C++ library

bool writeEntireFile(string filename, string text, bool append = false);

Writes the given text into the specified file. If the append parameter is passed with a true value, adds the given text to the end of the file. If append is omitted or false, overwrites any previous contents of the file. If the file cannot be opened or written, returns false, otherwise returns true.

Usage:

writeEntireFile(filename, text);

Available since: 2014/02/01 version of C++ library