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
chooseFilenameDialog(title, path) Opens a dialog that allows the user to choose a file from the specified path.
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.
fileSize(filename) Returns size of specified file or -1 if no such file exists.
findOnPath(searchpath, 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.
listDirectory(path) Returns an alphabetized vector of the files in the specified directory.
matchFilenamePattern(filename, pattern) Determines whether the filename matches the specified pattern.
openFile(stream, filename) Opens the filestream stream using the specified filename.
readEntire(is) Reads the entire contents of a filestream and returns them as a string.
readLines(is) Reads the entire contents of a filestream and returns them as a vector of lines.
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. If the operation succeeds, openFile returns true; if it fails, openFile sets the failure flag in the stream and returns false. If stream is of type ifstream, the file is opened for reading; if of type ofstream, it is opened for writing.

Usage:

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

string readEntire(istream& is);
Reads the entire contents of a filestream and returns them as a string. The client is responsible for opening and closing the stream.

Usage:

string data = readEntire(is);

Vector<string> readLines(istream& is);
Reads the entire contents of a filestream and returns them as a vector of lines. The client is responsible for opening and closing the stream.

Usage:

Vector<string> lines = readLines(is);

string chooseFilenameDialog(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, chooseFilenameDialog uses the current directory.

Usage:

string filename = chooseFilenameDialog("Choose a file");

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

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 findOnPath(string searchpath, string filename);
Returns the canonical name of a file found using a search path. The searchpath 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 no matching file is found, findOnPath returns the empty string.

Usage:

string pathname = findOnPath(searchpath, 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)) ...

int fileSize(string filename);
Returns size in bytes of specified file or -1 if no such file exists.

Usage:

int n = fileSize(filename);

bool isFile(string filename);
Returns true if the specified file is a regular file.

Usage:

if (isFile(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);
Returns an alphabetized list of the names of the files in the specified directory. The entries . and .. are excluded from the list.

Usage:

Vector<string> filenames = listDirectory(path);

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

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