synopsis.
The file address object (file_address_o) is used mainly as an auxiliery helper class to the file object (file_o). It belongs to the address group . This class can be regarded as belonging to the files group , but it is logically a type of address. The class object is on the threshold between these two groups.

The file address object is used to handle the addressing aspects of a file in a computer's [disk] file system. An instance of the file address class need not correspond to an actual file in a file system. The file address object closely models after the directory address object. They are siblings, both derived from address_o. This class is a bit more dirty, as the address, (ergo location of a file) involves directories. Hence, the directory address class is defined prior to file address and is heavily used by it.

String variables (string_o) are used to provide information to these objects. The syntax of the text in the strings depends on the environment (see the directory address class for more info).

A file address consists of a path, a name for the file, and an extension. The extension generally indicates the "type" of file - actaully a concept belonging to a "document", but it is only a convention and files with a given extension may, on most operating systems, actually have a different "type" (the nature of the contents within a file) than what their extension implies. This issue is taken a step further in the AS/400 (ILE) environment, where different files can have the same name and extension, but be distinguished by a "type flag" maintained in the file system. This deviation from the traditional unix / microsoft models have not been addressed [yet] by this class.

member functions (primary)

file_address_o_o()
SIGNATURE: file_address_o ()
SYNOPSIS: instantiaate a file address instance. Upon creation, this object will have no path or file name.
 

file_address_o_o(file_address_o_o)
SIGNATURE: file_address_o (const file_address_o &rhs)
SYNOPSIS:
makes an exact copy of the RHS object. If the copied object is uninitialized, the current object will be uninitialized also.
 

file_address_o_o(<args>)
SIGNATURE: file_address_o (const string_o &s)
SYNOPSIS:
creates a new file address instance and sets the directory name and the file name, given a string that contains the concatenation of the directory and file. The directory part is optional.
Examples:

    file_address_o fa0 ("/tmp/foobar"); // case 1
    file_address_o fa1 ("fubar.txt");   // case 2

In case 1, the directory component (to "/tmp") and the file name component is set (to "foobar");
In case 2, the file name component is set (to "fubar.txt") and the directory componet is in an 'unset' state.
The directory component is in the object's internal "directory_address_o" variable, 'my_dir'. The filename component is comprised of 2 string objects internal to the file address instance: 'my_name' and 'my_ext'. Note that for case 1 (above), 'my_ext' is an empty string.
 

operator = (file_address_o_o)
SIGNATURE: const file_address_o &operator = (const file_address_o &rhs)
SYNOPSIS: copies exactly the RHS object ("rhs"); any previous contents or state will be over-written.
 

operator = (file_address_o_o)
SIGNATURE: file_address_o &operator = (const string_o &s_addr)
SYNOPSIS:
assign a new address to the file object. This sets the directory name and the file name, given a string that contains the concatenation of the directory and file. The new address assigned is provided by input parameter "s_addr", in string format. The syntax of the string text should conform to that of the underlying OS's conventions.
 

destructor
SIGNATURE: ~file_address_o ()
SYNOPSIS: destructor. The address is reset to 'uninitialized'.
 

operator == (file_address_o_o)
SIGNATURE: int operator == (const file_address_o &rhs) const
SYNOPSIS:
compares current file address to 'rhs'; if equivalent, returns 1; returns 0 otherwise. To be equal, both the directory part and file name part must match.
RETURNS:
1: the file address is the same (the files have the same address)
0: the files have different addresses
 

operator != (file_address_o_o)
SIGNATURE: int operator != (const file_address_o &rhs) const
SYNOPSIS: compares current file address to 'rhs'. This is the inverse of the '==' operator.
RETURNS:
0: the file address is the same (the files have the same address)
1: the files have different addresses
 

get()
SIGNATURE: int get (string_o &s, boolean trupath = FALSE, int *pi = NULL) const
SYNOPSIS:
get the path+file, as a string. "s" is the output variable that is the recipient of this string. if trupath is TRUE, the file must exist on the local file system and the "true path" (full, expanded version) will be put into output variable "s".
PARAMETERS

• s - destination [output] string object that is to recieve the contents of the file address object.
• trupath - a flag (TRUE or FALSE) that controls whether or not the path of the object is to be expanded into a full path. if FALSE, whatever contents is in the directory path part of the object is used (equivalent to a 'get()' operation).
• pi - error indicator variable. values:
  0: success
  1: error in calling "full_path()"
  2: error in calling "path()"

 

(string_o) CAST-CONVERSION
SIGNATURE: operator string_o () const
SYNOPSIS: retuns the path+file, as a string. this is a simple wrapper function, equivalent to doing the "get()" member function.
 

file_name()
SIGNATURE: string_o name (int *pev = NULL) const
SYNOPSIS: returns the file name part of the file address, as a string.
PARAMETERS

pev - pointer to error var (must be provided). always set to 0

TRAITS:
'name()' member function [deprecated] apparently did the same thing as this function, it was confusing and is being phased out.
 

extension()
SIGNATURE: const string_o &extension (int *pev = NULL) const
SYNOPSIS:
returns the file extension (if any). examples:
if the file name is "address.cpp", this returns "cpp"
if the file name is "Makefile", this returns "" (empty string)
 

path()
SIGNATURE: int path (string_o &rs, int *pi = NULL) const
SYNOPSIS: gets the directory path part of the file address and puts it into output parameter 'rs'.
 

full_path()
SIGNATURE: int full_path (string_o *str, int *pi = NULL) const
SYNOPSIS:
this member function is similar to "path()", but the directory is from the root location. This subroutine converts the path specified by this object into a real path on the current file system.
PARAMETERS

str - contains the directory path, as a character string

 

directory()
SIGNATURE: const directory_address_o &directory () const
SYNOPSIS: returns the directory address component of the file address (as a reference to a directory_address object).
 

operator <<()
SIGNATURE: std::ostream &operator << (std::ostream &oso, const file_address_o &)
SYNOPSIS:
"prints" the file_address object to the given ostream ("oso"). a string representation of the file address is used, suitable for ostream printing
 

set_filename()
SIGNATURE: int set_filename (const string_o &s, int *pi = NULL)
SYNOPSIS:
assign a new file name to the current file address object. If 's' appears to have a directory path, the string will be broken up into components, and both the directory path and file name will be set. If the string 's' appears to be a file name only, any directory part of the current object will remain unaffected.
 

set_directory()
SIGNATURE: int set_directory (const string_o &s_dir)
SYNOPSIS:
Assigns a new directory path [only] to the current file address object. Any file name component of the current object is unaffected. This member function is The converse of "set_filename()".
 

set_directory()
SIGNATURE: int set_directory (const directory_address_o &d)
SYNOPSIS:
equivalent to "set_directory (const string_o &d)", but input parameter is of type directory_address_o. This simply copies the entire directory address object provided to its object (maintained internally; a "has-a" relationship). Thus, the directory part of the current file address is set to that of input variable 'd'.
 

bad_reference()
SIGNATURE: static const file_address_o &bad_reference ()
SYNOPSIS:
returns a handle to global "bad reference" instance. used for identifying failures in operations that return a reference to a file address object. This function is required if the object is to be inside a Z Directory container.
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the current object to default-construction state. The object will have no name or path.
 

clone()
SIGNATURE: file_address_o *clone () const
SYNOPSIS: allocate, assign and return a handle to a new file address instance. The new object will be a clone of the current object.
 

note.
Whether a 'file [or "directory"] address object' belongs to files or belongs to addresses can be debated and contested. Vettrasoft has decided that it is best categorized as an address that applies to files. This may be inconvenient for some, perhaps seeking documentation about these objects in the file zone. Most of the functionality provided by these two classes will probably be regarded my many as the domain of file systems.

bugs.
currently, each directory_address object lugs around a copy of the 'directory separator'. This is no doubt pointless and in the future this item will be made into a singleton global object. Nonetheless, the code works correctly.

history.

??? 11/21/1995: "pathexp.c" migrated & merged to file address src
Thu 07/11/1996: created file_address_o::operator string_o()
??? 07/11/1996: get() bug fix: check for empty string after dir. made
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Wed 08/27/2003: reworking "file/dir._address_o::name()/extension()"
Wed 02/09/2011: adding device (eg drive letter) to in/out strings
Mon 02/14/2011: de-inlined operator string_o(); strange errors
Tue 02/15/2011: added add_subdir() & delete_leafdir()
Mon 10/31/2011: added final, global function z_DIRSEP() {--GeG}
Sat 04/28/2012: moved z_DIRSEP() -> layer 01
Fri 06/15/2012: name cleanup: internal vars now "my_[xxx]"