name: Filename : public String

synopsis:

g++ [flags ...] file ...

#include <Filename.h>

Filename(const Filename& arg);
boolean transformUniquely();
boolean getBase(String& base) const;
boolean getExt(String& ext) const;
boolean makeTemp();
boolean makeTemp(const String& basename);

quick start:

String extension;

// declare the filename
//
Filename filename;
filename.assign(L"image.jpg");

// get the extension of the filename
//
filename.getExt(extension);

description:

The Filename class provides the facility to transform files and rename files. This class also helps in creating temporary file names and to find the required information about the file. This class decomposes a filename into {dirname}{basename}.{extension}. It can transform this name into a number of new forms.

For example, the filename "/home/joe.sof" has a dirname of "/home", a basename of "joe" and an extension of "sof". The transform method is capable of transforming this name into: {new_dirname}{basename}{new_suffix}.{new_extension}. Hence, "/home/joe.sof" can be transformed to "/user/files/joe_0.dat" (new_dirname="/user/files", basename="joe", new_suffix="_0", and new_extension="dat"). A variety of methods are provided to facilitate such transformations.

dependencies:

String

public constants:

define the class name:

static const String CLASS_NAME = L"Filename";

define operating system choices:

enum OS { UNIX = 0, WINDOWS, MACINTOSH, DEF_OS = UNIX };

define delimiters for a Unix filename:

const String Filename::SLASH(L"/");

const String Filename::DOT(L".");

const String Filename::UNDERSCORE(L"_");

define the default value(s) of the class data:

the DEF_CAPACITY and DEF_VALUE are inherited from the SysString class

define the default arguments to methods:

DEF_PARAM is inherited from the String class

const String Filename::DEF_EXTENSION(L"sof");

const String Filename::DEF_EXTENSION(L"sof");

const String Filename::DEF_SUFFIX(L"");

static const long DEF_DIR_PRES = 0;

error codes:

error code indicating Filename class general error:
```
static const long ERR = 45200;
```

protected data:

operating system name:

OS os_d;

a static memory manager:
```
static MemoryManager mgr_d;
```

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods: the setDebug method is inherited from the String class.
```
boolean debug(const unichar* message) const;
```

destructor/constructor(s):

~Filename();

Filename(long arg = DEF_CAPACITY);

Filename(const Filename& arg);

assign methods:
```
boolean assign(const Filename& arg);
```

operator= methods:

Filename& operator=(const Filename& arg);

i/o methods: the sofSize, readData, and writeData methods are inherited from the String class

boolean read(Sof& sof, long tag, const String& name);

boolean write(Sof& sof, long tag, const String& name) const;

equality methods:

this method is inherited from the SysString class

memory management methods: the clear method is inherited from the SysString class.

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

class-specific public methods:

constructors:

Filename(const unichar* arg, OS os = DEF_OS);

Filename(const String& arg, OS os = DEF_OS);

assign methods:

boolean assign(const String& arg);

boolean assign(const unichar* arg);

set/get methods:
```
boolean setOS(OS os);
```
```
OS getOS() const;
```

methods to transform filenames:

boolean transform(const String& new_dir, const String& new_ext, const String& new_suffix, long dir_preserve = DEF_DIR_PRES)

boolean transform(const String& new_ext, const String& new_suffix)

boolean transform(const String& old_name, const String& new_dir, const String& new_ext, const String& new_suffix, long dir_preserve = DEF_DIR_PRES)

methods to uniquely transform filenames:

boolean transformUniquely();

boolean transformUniquely(const String& old_name);

get methods:

boolean getDir(String& dir) const;

boolean getBase(String& base) const;

boolean getExt(String& ext) const;

boolean getSuffix(String& suffix) const;

boolean getName(String& filename) const;

temporary filenames:

boolean makeTemp();

boolean makeTemp(const String& basename);

build necessary subdirectories for output file:

static boolean buildPath(const String& pathname);

private methods:

directory name merging methods:

static boolean preserveDirName(String& mod_dir, const String& new_dir, const String& old_dir, long dir_preserve);

delimiter methods:

boolean getDirDelim(String& arg) const;

boolean getFileDelim(String& arg) const;

UNIX filename parsing methods:

boolean getDirUnix(String& dir) const;

boolean getBaseUnix(String& base) const;

boolean getExtUnix(String& ext) const;

boolean getNameUnix(String& name) const;

boolean getDirDelimUnix(String& arg) const;

boolean getFileDelimUnix(String& arg) const;

Windows filename parsing methods:

boolean getDirWin(String& dir) const;

boolean getBaseWin(String& base) const;

boolean getExtWin(String& ext) const;

boolean getNameWin(String& name) const;

boolean getDirDelimWin(String& arg) const;

boolean getFileDelimWin(String& arg) const;

Macintosh filename parsing methods:

boolean getDirMac(String& dir) const;

boolean getBaseMac(String& base) const;

boolean getExtMac(String& ext) const;

boolean getNameMac(String& name) const;

boolean getDirDelimMac(String& arg) const;

boolean getFileDelimMac(String& arg) const;

examples:

This exaple shows how we can change the name of a file

// declare the filename
//
Filename filename;

// we use strings to replace the name of the file
//
String old_name;
String new_name;

filename.assign(L"/examples/example.cc");
old_name.assign(L"example");
new_name.assign(L"example_02");

// replace the old_name with the new_name
//
filename.replace(old_name, new_name);

The result in this case is "/examples/example_02.cc".

This example shows how a file is transformed uniquely

// declare the filename
//
Filename tran_filename;

// declare the required string(s)
//
String filename;

filename.assign(L"example.cc");

// transform the filename uniquely
//
tran_filename.transformUniquely(filename);

If the file "example.cc" exists in the current directory, the result in this case is "example_0.cc".

notes:

The Windows and Macintosh operating systems are not yet supported.