Z Directory reference manual ("man" pages)

class ref name: file
category-group: files
layer: 9
header file: z_file.h

synopsis.
The file object (file_o) represents a single file found on a computer's file system for a storage device (eg a disk drive). Most of the member functions of this class have counterparts in layer 0 functions . This class is closely related to the directory class. These two classes are functionally brothers, although the file class is not derived from the file address class they way directory is a child of the directory class.

description.
The file object contains a file address (file_address_o) object inside. This differs from the directory object, which subclasses from its address class parent. The file object has a large, rich set of member functions. One can get (or write) successive lines of text to/from a file, or read / write a string object in one operation [via load() and store() functions].

Full file system support is provided via these member functions:

create() - create a new file
remove() - delete an existing file
rename() - rename a file
relocate() - move a file
copy_contents() - copy one file into another

Note that these functions have global (subroutine) function counterparts in layer 0.

file_address_o and directory_address_o classes are associated with the file_o and directory_o classes, respectively. It is easy to confuse these pairs of classes. The "address" classe is the base class for the class it is affiliated with, and handles matters related only to addressing, that is, where the file or directory is located. The subclass (ie, file_o) manages operations on the actual item, such as creation, reading from, writing to, or destroying it. Note that if copying files with the file object, one needs to invoke one of the 'deep copy' member functions: copy_contents() , copy_from() , or copy_to() . Doing a simple assignment may, depending on the right-hand-side variable, do one of these:

(a) write the contents of a string out to a [text] file;
(b) set the name of a file;
(c) [re]set the name of a file_o instance to that of another file object:

void some_function()
{
    file_o fx ("jake.txt"), fy ("yerba.txt");
    file_o fz (fy);     // sets fz's name to "yerba.txt"
    file_address_o fa ("C:\\temp\\xyz.txt");
    string_o s = "I do not like eggs in the file. I do not like them in any style.";
    fz = fy;            // sets fz's name to "yerba.txt"
    fz = s;             // sets contents of "yerba.txt" to poetry
    fz = fa;            // sets fz's file name to "xyz.txt" (and path)
    fz.copy_contents(fy);   // copy contents of "xyz.txt" to "yerba.txt"
}

Copying a file object instance to another file object copies everything, including the name - so the original file object's name (if any) is over-written. This is akin to reference counting - the two objects "point" to the same actual file. Thus, doing "fz = fy;" [in the example above] simply makes 'fz' point to whatever 'fy' points to - and thus, there is no need for an actual copy operation.

member functions (primary)

file_o()
SIGNATURE: file_o ()
SYNOPSIS: creates a a new file object, completely devoid of name, path or contents.

file_o(file_o)
SIGNATURE: file_o (const file_o &rhs)
SYNOPSIS: creates a a new file object, based on the file represented by file object 'rhs'. The file's address will be copied.

operator = (file_o)
SIGNATURE: const file_o &operator = (const file_o &rhs)
SYNOPSIS:
The current file object is set to that of 'rhs'. This is not a "deep copy" operation, as the file object is made to simply point to whatever 'rhs' is pointing to (if anything). The resuls is that the current file object will have a file address that is equal to that of 'rhs' (they will point to the same file).
To copy the file who's file name is provided by the variable 'rhs', use one of the "deep copy" functions, such as copy_contents() , copy_from() , or copy_to() .

destructor
SIGNATURE: ~file_o ()
SYNOPSIS:
destroys the class object instance. If the instance has flags z_Remove_On_Exit and z_Bound_To_File both set, the file will be deleted when the instance goes out of scope (eg when the destructor is invoked). any open file handle in this object to the file will be closed.

file_o(<args>)
SIGNATURE: file_o (const string_o &s)
SYNOPSIS:
equivalent to "file_o (const file_address_o &s)". constructor, creates a new file object and sets the address to that specified in 's' (which should be a path to a file, either fully qualified or just the file's name).

file_o(<args>)
SIGNATURE: file_o (const file_address_o &fa)
SYNOPSIS:
creates a file object with the address specified by 'fa'. this constructor should be given a name that contains the concatenation of path and file (eg the last directory separator divides the directory from the file name).

file_o(<args>)
SIGNATURE: file_o (const directory_address_o &da)
SYNOPSIS:
this constructor creates a file object. It sets the directory address of the file [only]. The file object's address is incomplete, because the file name is not specified via this constructor.

operator = (file_o)
SIGNATURE: const file_o &operator = (const file_address_o &rhs)
SYNOPSIS:
sets the address of a file (path + name) to that given in 'rhs'. If the new address is blank, the address is unset. overwrites any existing address.

operator == (file_o)
SIGNATURE: int operator == (const file_o &rhs) const
SYNOPSIS:
compares 2 file objects for equality. Equal file objects are defined as objects that point to the same file, eg have the same directory path and file name.
RETURNS:
1: the files have the same address (name and path)
0: the files are different (location-wise)

operator != (file_o)
SIGNATURE: int operator != (const file_o &rhs) const
SYNOPSIS:
the inverse of "==" operator. returns 1 if the files do not have the same directory location, or if the file names are different; returns 0 otherwise.
RETURNS:
1: the files are different
0: the files are the same

name()
SIGNATURE: string_o name (int *pie, boolean WithPath = FALSE, boolean TruePath = FALSE) const
SYNOPSIS:
retrieves the file name, and (depending on parameters used) the path. An "informational" member function. By default, only the file name is returned.
PARAMETERS

pie: an error indicator [output] variable. values:
0: success
zErr_Fetch_Failed: error occured in processing (this error occurs only when the true path is desired)

WithPath: if TRUE, the path is included in the string output

TruePath: if TRUE, the path is expanded to the full, true path. applicable only if 'WithPath' is TRUE. The "true" path is not always the same as the "regular" path. This is most common when a relative path (such as "../../somewhere/far") was supplied as the file address's path.

RETURNS: a string object containing the file name

full_name()
SIGNATURE: string_o full_name (int *pie = NULL, boolean TruePath = FALSE) const
SYNOPSIS: an "informational" member function. returns the path with file name concatenated.
RETURNS: a string object containing the full path.

base_name()
SIGNATURE: string_o base_name (int *pi = NULL) const
SYNOPSIS:
an "informational" member function. returns the file's "base" name - that is, the part of the file without the extension (or '.' dot separator).
PARAMETERS
pi: optional error code indicator variable. possible values:
0: successfully found, extracted, and returned the base name;
zErr_NotConfigured: no basename (file name not set?);
zErr_DirtyData: [informational] no dot ('.') separator in the file name
RETURNS: a string containing the base name component of the file name

extension()
SIGNATURE: string_o extension (int *pi = NULL) const
SYNOPSIS:
returns the file's extension (eg, its "type"). This may be an empty string in the case of a file without any extension. Given foo.bar, the return value of this function will be 'bar'.
unix case: if the file is a "dot file", that is, the name begins with a dot ('.'), the extension is considered to be any alphanumeric text after the last dot, if there is at least 1 dot after the initial dot. For example, given ".exinit.rc" or ".myhidden.file.txt.rc", the value returned will be (in both cases) 'rc'. If there is no
PARAMETERS
pi: [optional error code indicator variable. its values:
0: successfully found, extracted, and returned the extension;
zErr_NotConfigured: file has no name (possibly has not been set)
zErr_NoMatch: no extension found

address_isset()
SIGNATURE: boolean address_isset (int *pi = NULL) const
SYNOPSIS:
informational. tells if the file "address" (where it is, eg, path and/or file name). The output variable 'pi' (which is usually relegated to just reporting errors) in this case tells what part (if any) of the file address is set. If the file name is set, this function returns TRUE. The directory path need not be set, as the convention is that if a file's address contains only the file name, the file is regarded as being in the program's current directory. Whether or not the directory path is set can be ascertained from the value of the output parameter 'pi'.
Note that it does not tell if the file exists! Or if the directory path is real (exists) or not - for that, use the member function "exists()".
PARAMETERS
pi: optional error and status code indicator variable. values:
0: file name and directory path was set
zErr_Data_Incomplete: file name is set; directory path is not set
zErr_NotConfigured: neither path nor file name is set (the object is uninitialized)
zErr_Object_Corrupted: internal error (panic)
RETURNS:
TRUE: file name is set
FALSE: file name is not set

exists()
SIGNATURE: boolean exists (int *pe = NULL) const
SYNOPSIS: tells if a file specified by the address found in this object is on the current file system.
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: no error, file exists;
zErr_NotConfigured: file name not set;
zErr_Object_Corrupted: could not access file or its location (error reading path);
RETURNS:
TRUE: the file is there;
FALSE: the file does not exist (or error)

size()
SIGNATURE: size_t size (int *pie = NULL) const
SYNOPSIS:
returns size of the file (in bytes). if the file does not exist or cannot be accessed, 0 will be returned and 'pie' set to a non-zero value. See [L0] z_filesize() for the list of values of 'pie'.

time_created()
SIGNATURE: const time_o &time_created (int *pi = NULL)
SYNOPSIS: gets the time when the file was created
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: creation time successfully obtained
zErr_NotConfigured: file object's properties not set
DESCRIPTION:
this routine uses fetch_properties() if it was not called earlier. the 3 functions time_created(), time_lastused(), and time_lastwrite() are all identical in structure. Since they require an earlier call to fetch_properties(), if one was not done, the ywill automatically do it. then these routines simply return a reference to the appropriate variable.

time_lastused()
SIGNATURE: const time_o &time_lastused (int *pi = NULL)
SYNOPSIS: gets the time when the file was last accessed
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: creation time successfully obtained
zErr_NotConfigured: file object's properties not set
DESCRIPTION: see time_created() for more information.

time_lastwrite()
SIGNATURE: const time_o &time_lastwrite (int *pi = NULL)
SYNOPSIS: gets the time when the file was last written to.
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: creation time successfully obtained
zErr_NotConfigured: file object's properties not set
DESCRIPTION: see time_created() for more information.

is_same()
SIGNATURE: boolean is_same (const file_o &rhs, int *pi = NULL, boolean deep = FALSE)
SYNOPSIS: compares file contents for equality
PARAMETERS

rhs: [input] the file to compare to. it must exist.

deep: [input] if TRUE, a byte-by-byte comparison will be performed. If FALSE, such a comparison will be skipped.

pi: [output] an error indicator [output] variable. values:
0: successful comparison
zErr_Unfinished: 'deep' parameter set to TRUE (the programming is incomplete here)

DESCRIPTION:
if the contents of the current file is exactly the same as that of 'rhs', TRUE is returned. If not, FALSE is returned. This function comes in 2 flavors: quick (deep = FALSE), and long (deep = TRUE). In "quick mode", the file sizes and MD-5 hash values will be compared. In "long mode", these two properties will be used, and in the case of a match, a byte-by-byte comparison will be done.
Although the 2nd parameter ('pi') is optional, omitting it or ignoring it is highly discouraged. If either of the two files do not exist or
RETURNS:
TRUE: the files are equivalent (same contents)
FALSE: files are different, or an error occured
TRAITS: this should not be used on very large (1GB+) files.

is_open()
SIGNATURE: boolean is_open () const
SYNOPSIS: an "informational" member function. tells if the file has been opened [via open() call].
TRAITS: this is an inlined function.

is_textmode()
SIGNATURE: boolean is_textmode() const
SYNOPSIS:
tells if the "mode" of the file object is text or binary. The file object maintains this state information in the internal boolean flag variable 'm_textmode'. This variable can be set or unset via calls to the member functions setmode_text() and setmode_binary(). The default (at construction) state is text mode. The mode affects how a file is opened, file copy operations, and how a string object is loaded from a text file (Z Directory strings can run in "binary mode", thus acting as buffers for binary data, such as DLLs, object modules, or even executable file images).

directory()
SIGNATURE: const directory_address_o &directory () const
SYNOPSIS: returns the directory address object, contained in the current object instance.

address()
SIGNATURE: const file_address_o &address () const
SYNOPSIS: returns the file address object, contained in the current object instance.

set_name()
SIGNATURE: int set_name (const string_o &s, int *pie = NULL)
SYNOPSIS: a "configuration" member function. sets the file name. equivalent to "file_o::operator = ((file_address_o) s)"
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: name successfully set
zErr_Param_NotSet: 's' is an empty string

set_extension()
SIGNATURE: int set_extension (const string_o &s, int *pi = NULL)
SYNOPSIS:
this sets the file's extension. If the file name has been set earlier, the extension will be changed to that given in 's'. Any string is allowed here. Example:
file_o f;
f.set_name ("myfile.txt");      // myfile.txt
f.set_extension ("php");        // myfile.php
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: extension successfully set
zErr_Param_NotSet: 's' is an empty string
TRAITS: a "configuration" member function

set_address()
SIGNATURE: int set_address (const string_o &s, int *pi = NULL)
SYNOPSIS: this call sets the address to that of 's' (path and file name, or just file name)
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: address successfully set
zErr_Param_NotSet: 's' is an empty string
RETURNS: 0

set_address()
SIGNATURE: int set_address (const file_address_o &new_addr, int *pi = NULL)
SYNOPSIS: a "configuration" member function. sets the address to that of 'new_addr' (path and file name).
PARAMETERS
pie: an [optional] error indicator [output] variable. values:
0: address successfully set
zErr_SameData: the new address (in 'new_addr') is the same as the existing/prior address
RETURNS: 0

set_flag()
SIGNATURE: int set_flag (enum File_Flag x, boolean is_on = TRUE)
SYNOPSIS:
a "configuration" member function. sets a flag (property value) for the file object. Only user-configurable flags may be set. Flags that are not for the user to configure are internal state flags. If the user tries to set such a flag, this function will return the error value of -1.
PARAMETERS

x: can be z_Remove_On_Exit or z_Overwrite_On_Create. The other flags (z_Address_Is_Set, z_Bound_To_File, z_Is_Open) are not set by the user.

is_on: if TRUE, the flag is set; if FALSE, the flag is unset (cleared).

set_textmode()
SIGNATURE: int set_textmode (boolean is_on = TRUE)
SYNOPSIS:
a "configuration" member function. use this prior to calling member function open(). Tells the object what type of file it is (text or binary).
PARAMETERS
is_on: if TRUE, the object is set to "text mode"; if FALSE, the object is set to "binary mode".

setmode_binary()
SIGNATURE: int setmode_binary (boolean is_on = TRUE)
SYNOPSIS:
a "configuration" member function. use this prior to calling member function open(). Tells the object what type of file it is to open (text or binary). This function is the exact inverse of "set_textmode()".
PARAMETERS
is_on: if TRUE, the object is set to "binary mode"; if FALSE, the object is set to "text mode".

set_directory()
SIGNATURE: int set_directory (const string_o &s, int *pie = NULL)
SYNOPSIS:
a "configuration" member function. set the directory part of the file's address. the string "s" must be a valid path in order for this function to succeed.

operator =()
SIGNATURE: const file_o &operator = (const string_o &s)
SYNOPSIS: open the file, copy the contents of "s" to the file, then close the file. does a complete write operation.
DESCRIPTION:
similar to store(), but automatically opens and closes the file. This function is being debated because it may appear to be setting the file name (use set_name() for setting the file name).
WARNING!: this does *not* set the file name!
TRAITS: the user may assume a different meaning to this operation

operator +=()
SIGNATURE: const file_o &operator += (const string_o &s)
SYNOPSIS: this concatenates the contents of string 's' to the file. The file must exist in order for this operation to succeed.
DESCRIPTION:
this operator is closely related and coupled to the assignment operator:
  string_o s1 = "A thousand leagues;\n";
  string_o s2 = "a thousand leagues.\n";
  file_o f("myfile.txt");
  f = s1;
  f += s2;
reset()
SIGNATURE: int reset (int *pi = NULL)
SYNOPSIS:
returns the file object to its at-construction state. closes any associcated file, if open, and wipes out the address (file name and path).
PARAMETERS
pi: [output] error indicator variable. values:
0: successfully reset
zErr_Item_CantClose: could not do a file system close

create()
SIGNATURE: int create ()
SYNOPSIS:
creates a new file. The file's address must be set. If there is a file by the same name in the same location when this function is invoked, if the flag z_Overwrite_On_Create is set, the file will be over-written and its existing contents lost. If such a file exists and z_Overwrite_On_Create is not set, this function will return -1.

rename()
SIGNATURE: int rename (const string_o &new_name)
SYNOPSIS:
renames the file. the new name must be "simple" - it cannot have a directory-separator symbol imbedded in it. The current file object must have the name and path set, and be a valid file in the current file system.

relocate()
SIGNATURE: int relocate (const directory_address_o &new_home)
SYNOPSIS: moves a file from its current location to the new address specified by "new_home"
RETURNS:
0: successful relocation (or target address is same as current address)
-1: error (possibley invalid address)

remove()
SIGNATURE: int remove ()
SYNOPSIS:
deletes the file from the file system. The current file object must have the name and path set, and must represent a valid file in the current file system.

kill()
SIGNATURE: int kill (boolean all_links = TRUE)
SYNOPSIS:
deletes a file. If the given file is (one or more) symbolic link, this will follow the links to the final destination and terminate the final file - if there is one.

deep_copy()
SIGNATURE: int deep_copy (const directory_address_o &dir, int direc = 0, boolean stomp = FALSE)
SYNOPSIS:
This function copies to/from another file. This function is exactly analogous to the other signitures of "deep_copy()" (which see), except that the first parameter type is directory_address_o. Basically this function is equivalent to "deep_copy(const file_o &that ..)", where the file name of "that" is the same as this (the current object), and the directory path of "that" is whatever is specified in "dir". Please see this other "deep_copy()" signiture variant for behaviours of this function.
PARAMETERS

dir: the source or destination file. If direc is 0, "dir" is the source location, and the file given by the current object will be copied from "dir".

direc: a flag; tells this function whether to copy from or to the other file.

stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted.

deep_copy()
SIGNATURE: int deep_copy (const file_address_o &new_addr, int direc = 0, boolean stomp = FALSE)
SYNOPSIS:
This function copies to/from another file. This function is exactly analogous to "deep_copy(file_o, int, boolean)" (which see), except that the first parameter type is file_address_o instead of file_o.
This function is explicitly provided since there is no automatic conversion from file_address_o to file_o.
PARAMETERS

that: the source or destination file. If direc is 0, "that" is the source file, and the file given by this object will be copied from "that".

direc: a flag; tells this function whether to copy from or to the other file ("that").

stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted.

deep_copy()
SIGNATURE: int deep_copy (const file_o &that, int direc = 0, boolean stomp = FALSE)
SYNOPSIS:
This function copies to/from another file. If the second parameter ("direc") is 1, it copies the file given by the current object to a new (or possibly existing) file. If "direc" is 0, it does the converse: this function then copies the other file ("that") to the file given by the current object. The current file object must have the name and path set. The directory location must be valid in order for this operation to succeed. Whether the file exists or not depends on the parameters to this function call. If writing to another file (direct == 1), and there is a file in the same target name and path as "that", it will be over-written only if "stomp" is TRUE. If the target file is the same as the current file object, nothing is done and 0 is returned.
PARAMETERS

that: the source or destination file. If direc is 0, "that" is the source file, and the file given by this object will be copied from "that".

direc: a flag; tells this function whether to copy from or to the other file ("that").

stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted.

true_path()
SIGNATURE: int true_path (string_o *s_relpath) const
SYNOPSIS: expands the path given by "s_relpath" to the absolute, full fixed path.
TRAITS: why is this function not static? needs investigation

open()
SIGNATURE: int open (enum File_Open mode = zFile_Read)
SYNOPSIS:
opens a file for [subsequent] reading. The methodology corresponds to that used by fopen(). set_textmode() should be called prior if the file is a text file, and setmode_binary() in the case the file contains binary data.
PARAMETERS
mode: how to open the file. valid values are:
zFile_Read: open the file for reading.
zFile_Write: open the file for writing. this will overwrite any existing contents
zFile_Create: create a new, empty (0-length) file.
zFile_Append: open the file for appending data to it. any previously existing contents will be preserved; new data will go after it.

close()
SIGNATURE: int close ()
SYNOPSIS: "close" an open file. if the file has not been opened, this routine does nothing and returns 0.

flush()
SIGNATURE: int flush ()
SYNOPSIS:
flush all changes done on the file to the disk. That is, if the OS has buffered any data, calling this function will cause the OS to sync the data, should the OS have buffered any (basically this maps onto a fflush() system call).

get_line()
SIGNATURE: int get_line (string_o &s, int flags = 0) const
SYNOPSIS: gets the next line of text from the file. The file must have been opened [via open() call] prior.
PARAMETERS

s: string object that recieves the next line from the file

flags: bitmap of flags controlling usage of trailing space.
bit 0: add a newline ('\n') [value: 1]
bit 1: trim trailing space, including newlines [value: 2]
eg, a value of 1 appends a newline, and a value of 2 trims the line. note that a value of 3 gets you a trimmed line with '\n' at the end (if that makes any sense).

RETURNS:
0: new line successfully read in
1: EOF
-1: error occured.
TRAITS:
non-standardized parameter list. "flags" should be flag object, not int. This function will probably recieve an additional parameter at the end - an [output] error indicator variable.

put_line()
SIGNATURE: int put_line (const string_o &s)
SYNOPSIS:
writes the text in "s" out to the file. the file should be opened previously and in "text mode". Note that 's' can have multiple lines (multi-line text is typically stored in a derived class textstring_o). Everything in 's' is written, up to (but not including) the terminating '\0'.
TRAITS: the name put_line() is somewhat misleading as it implies that only a single line of text is written out.

get_bytes()
SIGNATURE: int get_bytes (string_o &s_b, size_t *n, int *pie) const
SYNOPSIS:
read a byte stream in from a file. Since the string object can be put into binary mode and then can hold binary bytes, this member function uses "s_b" to hold the block of data. The file must have been opened prior to calling this function. Make sure that if the file contains [non-text] binary data, that the file object was set to the correct mode prior to opening it. Also, the string needs to have its internal buffer allocated so that it can accomodate "n" bytes. This should be done like so:
  int ierr, rv;
  file_o f;                     // configure the file object..
  size_t numbytes = 512;
  string_o s;
  s.force_size(800);            // VITAL
  f.setmode_binary();           // if binary (eg "pic.jpg")
  f.open();
  rv = f.get_bytes(s, &numbytes, &ierr);
PARAMETERS

s_b: a string object that will recieve the data. if the size of the string is less than "n", it will be resized inside this function.

n: the [maximum] number of bytes to read. this value must be known in advance. also, this number will be set to the number of bytes actually read (which can be less than what it was set to, if there are not enough bytes to fill the original buffer size).

RETURNS:
0: successful byte read
1: successful read, but less than the alloted capacity
-1: error

put_bytes()
SIGNATURE: int put_bytes (const string_o &s_b, size_t *p_n, int *pie)
SYNOPSIS:
write a byte stream out to a file. the string object containing the bytes must be in binary mode. If the file has not been opened for writing prior, this routine will open the file with mode zFile_Write.
PARAMETERS

s_b: string containing the byte block to be written.

p_n: number of bytes to write. if the size of "s_b" is less than this number, the lesser size will be used. this is also an output variable - the actual number of bytes written will be put in this parameter.

pie: an error indicator [output] variable.

load()
SIGNATURE: int load (string_o &s, int *pie = NULL)
SYNOPSIS:
loads the contents of a file into a string object. the mode (text or binary) is dependent on the file and / or string object: if either is in binary mode, the load-mode is set to binary; else, the load is done in text mode.

load()
SIGNATURE: int load (string_o &s, int flags = 0, int *pie = NULL)
SYNOPSIS:
loads the contents of a file into a string object. the file can be text or binary. you specify which in the "flags" [2nd] parameter. Data will be loaded into "s" either a line at a time (text mode), or in 4K chunks (4,096 bytes), if in binary mode.
PARAMETERS

s: the string object to recieve the contents of the file

flags: additional control, for text mode. a bit-map. values:
1: add '\n' to each line
2: use line at a time loading, for text

store()
SIGNATURE: int store (const string_o &s, int *pie = NULL)
SYNOPSIS: write out a string to a file. this is basically a convenience function. It is the converse of load().

fetch_properties()
SIGNATURE: int fetch_properties (int *pi = NULL)
SYNOPSIS:
gets the properties (characteristics) of an existing file. the properties are stored in internal variables. These variables can get out of sync with the reality of the file, so the properties should be retrieved immediately after calling this function. if the file does not exist, this return will error out.
PARAMETERS
pi: an error indicator [output] variable. values:
0: successful fetch
zErr_Resource_Missing: no such file
zErr_Fetch_Failed: could not read contents of file
zErr_Resource_Corrupted: failure trying to calculate MD-5 hash value
zErr_NotSupported: this function not implemented on current OS
RETURNS:
0: file properties fetched and set
-1: error occured (have you set the file name?)

string_o()
SIGNATURE: operator string_o () const
SYNOPSIS:
Read a file's contents to a string. usage:
file_o f;
string_o s = f;
This subroutine automatically opens and closes the file. Set the mode to either text or binary, as appropriate, via set_textmode().

clone()
SIGNATURE: file_o *clone () const
SYNOPSIS: does a new and duplicates the file object in the new object instance. For symbolic canonical format usage.

<<()
SIGNATURE: friend std::ostream &operator << (std::ostream &, const file_o &)
SYNOPSIS: prints the file's address to stdout.

copy_to()
SIGNATURE: int copy_to (const file_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)".

copy_to()
SIGNATURE: int copy_to (const file_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)".

copy_to()
SIGNATURE: int copy_to (const directory_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)".

copy_from()
SIGNATURE: int copy_from (const file_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)".

copy_from()
SIGNATURE: int copy_from (const file_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)".

copy_from()
SIGNATURE: int copy_from (const directory_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)".

copy_contents()
SIGNATURE: int copy_contents (const file_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)".

copy_contents()
SIGNATURE: int copy_contents (const file_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)".

copy_contents()
SIGNATURE: int copy_contents (const directory_address_o &rhs, boolean stomp = FALSE)
SYNOPSIS:
this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)".

note.
This class, like the directory_o class, uses the concept of a virtual "directory separator", which is "/" in unix environments and "\" in Microsoft environments.

The file_o class is not subclassed from the file_address_o class. However, file objects contain an instance of the file address class. This implementation took the viewpoint that the address of a file is a [very important] property of a file, but that a file is a file, not an address. Hence the relationship is "uses-a", not "is-a".

The nomenclature for file-copy operations went thru a little evolution. Originally, it was a simple "copy()", but this member function is usually private in most other Z Directory objects. Also, just 'copy' lacks semantics about what is being copied and where. "copy_contents()" was the next choice, but given this:

    file_o fa, fb;
    fa.copy_contents(fb);

It is not entire clear whether fa is being copied to fb or if fb is copied to fa. clone() was considered, but this is appropriate when creating a new file only. fa.clone(fb); just doesn't look right. We finally decided on providing several naming choices:

copy_contents() - copies from the right-hand-side (RHS) object
copy_from() - same as copy_contents() .
copy_to() copy contents of current object to RHS target.
deep_copy(x, i) copy contents from or to RHS object, depending on value of [integer] variable 'i': 0 - copy from RHS; 1 - copy to RHS.

The object type of the parameter to each of these member functions can be a file_o, file_address_o. In the "copy-to" cases, it can also be a directory_o class instance.

history.

Fri 11/24/1995: merged old Z Directory file "killfile.c"
??? 12/20/1996: new & improved: added the "trim line" feature
??? 12/03/1997: bug fix in "file_o::file_o (string_o &)"
Fri 05/01/1998: changed "get/put_bytes()", auto-open for read/write
Sun 10/18/1998: changed "(file_o) = (string_o)" semantics
??? 10/26/1998: added "feof()" check {maybe solaris-specific?}
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Sun 09/07/2003: changed internal data member names
Sat 09/06/2003: changed 2nd param, "boolean do_trim" to int
Tue 02/15/2011: various bug fixes, eg, in "file_o::load()"
Tue 06/12/2012: added function names: copy_contents(), copy_from/to()
Fri 11/27/2015: error output code values cleaned up for many functions
Fri 04/15/2016: added-created function: operator += (const string_o &)

Vettrasoft Z Directory > tech support > reference > file (files group)
ref home support home samples contact
	class ref name: file category-group: files layer: 9 header file: z_file.h synopsis. The file object (file_o) represents a single file found on a computer's file system for a storage device (eg a disk drive). Most of the member functions of this class have counterparts in layer 0 functions . This class is closely related to the directory class. These two classes are functionally brothers, although the file class is not derived from the file address class they way directory is a child of the directory class. description. The file object contains a file address (file_address_o) object inside. This differs from the directory object, which subclasses from its address class parent. The file object has a large, rich set of member functions. One can get (or write) successive lines of text to/from a file, or read / write a string object in one operation [via load() and store() functions]. Full file system support is provided via these member functions: create() - create a new file remove() - delete an existing file rename() - rename a file relocate() - move a file copy_contents() - copy one file into another Note that these functions have global (subroutine) function counterparts in layer 0. file_address_o and directory_address_o classes are associated with the file_o and directory_o classes, respectively. It is easy to confuse these pairs of classes. The "address" classe is the base class for the class it is affiliated with, and handles matters related only to addressing, that is, where the file or directory is located. The subclass (ie, file_o) manages operations on the actual item, such as creation, reading from, writing to, or destroying it. Note that if copying files with the file object, one needs to invoke one of the 'deep copy' member functions: copy_contents() , copy_from() , or copy_to() . Doing a simple assignment may, depending on the right-hand-side variable, do one of these: (a) write the contents of a string out to a [text] file; (b) set the name of a file; (c) [re]set the name of a file_o instance to that of another file object: void some_function() { file_o fx ("jake.txt"), fy ("yerba.txt"); file_o fz (fy); // sets fz's name to "yerba.txt" file_address_o fa ("C:\\temp\\xyz.txt"); string_o s = "I do not like eggs in the file. I do not like them in any style."; fz = fy; // sets fz's name to "yerba.txt" fz = s; // sets contents of "yerba.txt" to poetry fz = fa; // sets fz's file name to "xyz.txt" (and path) fz.copy_contents(fy); // copy contents of "xyz.txt" to "yerba.txt" } Copying a file object instance to another file object copies everything, including the name - so the original file object's name (if any) is over-written. This is akin to reference counting - the two objects "point" to the same actual file. Thus, doing "fz = fy;" [in the example above] simply makes 'fz' point to whatever 'fy' points to - and thus, there is no need for an actual copy operation. member functions (primary) file_o() SIGNATURE: file_o () SYNOPSIS: creates a a new file object, completely devoid of name, path or contents. file_o(file_o) SIGNATURE: file_o (const file_o &rhs) SYNOPSIS: creates a a new file object, based on the file represented by file object 'rhs'. The file's address will be copied. operator = (file_o) SIGNATURE: const file_o &operator = (const file_o &rhs) SYNOPSIS: The current file object is set to that of 'rhs'. This is not a "deep copy" operation, as the file object is made to simply point to whatever 'rhs' is pointing to (if anything). The resuls is that the current file object will have a file address that is equal to that of 'rhs' (they will point to the same file). To copy the file who's file name is provided by the variable 'rhs', use one of the "deep copy" functions, such as copy_contents() , copy_from() , or copy_to() . destructor SIGNATURE: ~file_o () SYNOPSIS: destroys the class object instance. If the instance has flags z_Remove_On_Exit and z_Bound_To_File both set, the file will be deleted when the instance goes out of scope (eg when the destructor is invoked). any open file handle in this object to the file will be closed. file_o(<args>) SIGNATURE: file_o (const string_o &s) SYNOPSIS: equivalent to "file_o (const file_address_o &s)". constructor, creates a new file object and sets the address to that specified in 's' (which should be a path to a file, either fully qualified or just the file's name). file_o(<args>) SIGNATURE: file_o (const file_address_o &fa) SYNOPSIS: creates a file object with the address specified by 'fa'. this constructor should be given a name that contains the concatenation of path and file (eg the last directory separator divides the directory from the file name). file_o(<args>) SIGNATURE: file_o (const directory_address_o &da) SYNOPSIS: this constructor creates a file object. It sets the directory address of the file [only]. The file object's address is incomplete, because the file name is not specified via this constructor. operator = (file_o) SIGNATURE: const file_o &operator = (const file_address_o &rhs) SYNOPSIS: sets the address of a file (path + name) to that given in 'rhs'. If the new address is blank, the address is unset. overwrites any existing address. operator == (file_o) SIGNATURE: int operator == (const file_o &rhs) const SYNOPSIS: compares 2 file objects for equality. Equal file objects are defined as objects that point to the same file, eg have the same directory path and file name. RETURNS: 1: the files have the same address (name and path) 0: the files are different (location-wise) operator != (file_o) SIGNATURE: int operator != (const file_o &rhs) const SYNOPSIS: the inverse of "==" operator. returns 1 if the files do not have the same directory location, or if the file names are different; returns 0 otherwise. RETURNS: 1: the files are different 0: the files are the same name() SIGNATURE: string_o name (int pie, boolean WithPath = FALSE, boolean TruePath = FALSE) const SYNOPSIS: retrieves the file name, and (depending on parameters used) the path. An "informational" member function. By default, only the file name is returned. PARAMETERS pie: an error indicator [output] variable. values: 0: success zErr_Fetch_Failed: error occured in processing (this error occurs only when the true path is desired) WithPath: if TRUE, the path is included in the string output TruePath: if TRUE, the path is expanded to the full, true path. applicable only if 'WithPath' is TRUE. The "true" path is not always the same as the "regular" path. This is most common when a relative path (such as "../../somewhere/far") was supplied as the file address's path. RETURNS: a string object containing the file name full_name()* SIGNATURE: string_o full_name (int pie = NULL, boolean TruePath = FALSE) const SYNOPSIS: an "informational" member function. returns the path with file name concatenated. RETURNS: a string object containing the full path. base_name()* SIGNATURE: string_o base_name (int pi = NULL) const SYNOPSIS: an "informational" member function. returns the file's "base" name - that is, the part of the file without the extension (or '.' dot separator). PARAMETERS pi: optional error code indicator variable. possible values: 0: successfully found, extracted, and returned the base name; zErr_NotConfigured: no basename (file name not set?); zErr_DirtyData: [informational] no dot ('.') separator in the file name RETURNS: a string containing the base name component of the file name extension()* SIGNATURE: string_o extension (int pi = NULL) const SYNOPSIS: returns the file's extension (eg, its "type"). This may be an empty string in the case of a file without any extension. Given foo.bar, the return value of this function will be 'bar'. unix case: if the file is a "dot file", that is, the name begins with a dot ('.'), the extension is considered to be any alphanumeric text after the last dot, if there is at least 1 dot after the initial dot. For example, given ".exinit.rc" or ".myhidden.file.txt.rc", the value returned will be (in both cases) 'rc'. If there is no PARAMETERS pi: [optional error code indicator variable. its values: 0: successfully found, extracted, and returned the extension; zErr_NotConfigured: file has no name (possibly has not been set) zErr_NoMatch: no extension found address_isset()* SIGNATURE: boolean address_isset (int pi = NULL) const SYNOPSIS: informational. tells if the file "address" (where it is, eg, path and/or file name). The output variable 'pi' (which is usually relegated to just reporting errors) in this case tells what part (if any) of the file address is set. If the file name is set, this function returns TRUE. The directory path need not be set, as the convention is that if a file's address contains only the file name, the file is regarded as being in the program's current directory. Whether or not the directory path is set can be ascertained from the value of the output parameter 'pi'. Note that it does not tell if the file exists! Or if the directory path is real (exists) or not - for that, use the member function "exists()". PARAMETERS pi: optional error and status code indicator variable. values: 0: file name and directory path was set zErr_Data_Incomplete: file name is set; directory path is not set zErr_NotConfigured: neither path nor file name is set (the object is uninitialized) zErr_Object_Corrupted: internal error (panic) RETURNS: TRUE: file name is set FALSE: file name is not set exists()* SIGNATURE: boolean exists (int pe = NULL) const SYNOPSIS: tells if a file specified by the address found in this object is on the current file system. PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: no error, file exists; zErr_NotConfigured: file name not set; zErr_Object_Corrupted: could not access file or its location (error reading path); RETURNS: TRUE: the file is there; FALSE: the file does not exist (or error) size()* SIGNATURE: size_t size (int pie = NULL) const SYNOPSIS: returns size of the file (in bytes). if the file does not exist or cannot be accessed, 0 will be returned and 'pie' set to a non-zero value. See [L0] z_filesize()* for the list of values of 'pie'. time_created() SIGNATURE: const time_o &time_created (int pi = NULL) SYNOPSIS: gets the time when the file was created PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: creation time successfully obtained zErr_NotConfigured: file object's properties not set DESCRIPTION: this routine uses fetch_properties()* if it was not called earlier. the 3 functions time_created(), time_lastused(), and time_lastwrite() are all identical in structure. Since they require an earlier call to fetch_properties(), if one was not done, the ywill automatically do it. then these routines simply return a reference to the appropriate variable. time_lastused() SIGNATURE: const time_o &time_lastused (int pi = NULL) SYNOPSIS: gets the time when the file was last accessed PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: creation time successfully obtained zErr_NotConfigured: file object's properties not set DESCRIPTION: see time_created()* for more information. time_lastwrite() SIGNATURE: const time_o &time_lastwrite (int pi = NULL) SYNOPSIS: gets the time when the file was last written to. PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: creation time successfully obtained zErr_NotConfigured: file object's properties not set DESCRIPTION: see time_created()* for more information. is_same() SIGNATURE: boolean is_same (const file_o &rhs, int pi = NULL, boolean deep = FALSE) SYNOPSIS: compares file contents for equality PARAMETERS rhs: [input] the file to compare to. it must exist. deep: [input] if TRUE, a byte-by-byte comparison will be performed. If FALSE, such a comparison will be skipped. pi: [output] an error indicator [output] variable. values: 0: successful comparison zErr_Unfinished: 'deep' parameter set to TRUE (the programming is incomplete here) DESCRIPTION: if the contents of the current file is exactly the same as that of 'rhs', TRUE is returned. If not, FALSE is returned. This function comes in 2 flavors: quick (deep = FALSE), and long (deep = TRUE). In "quick mode", the file sizes and MD-5 hash values will be compared. In "long mode", these two properties will be used, and in the case of a match, a byte-by-byte comparison will be done. Although the 2nd parameter ('pi') is optional, omitting it or ignoring it is highly discouraged. If either of the two files do not exist or RETURNS: TRUE: the files are equivalent (same contents) FALSE: files are different, or an error occured TRAITS: this should not be used on very large (1GB+) files. is_open()* SIGNATURE: boolean is_open () const SYNOPSIS: an "informational" member function. tells if the file has been opened [via open() call]. TRAITS: this is an inlined function. is_textmode() SIGNATURE: boolean is_textmode() const SYNOPSIS: tells if the "mode" of the file object is text or binary. The file object maintains this state information in the internal boolean flag variable 'm_textmode'. This variable can be set or unset via calls to the member functions setmode_text() and setmode_binary(). The default (at construction) state is text mode. The mode affects how a file is opened, file copy operations, and how a string object is loaded from a text file (Z Directory strings can run in "binary mode", thus acting as buffers for binary data, such as DLLs, object modules, or even executable file images). directory() SIGNATURE: const directory_address_o &directory () const SYNOPSIS: returns the directory address object, contained in the current object instance. address() SIGNATURE: const file_address_o &address () const SYNOPSIS: returns the file address object, contained in the current object instance. set_name() SIGNATURE: int set_name (const string_o &s, int pie = NULL) SYNOPSIS: a "configuration" member function. sets the file name. equivalent to "file_o::operator = ((file_address_o) s)" PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: name successfully set zErr_Param_NotSet: 's' is an empty string set_extension()* SIGNATURE: int set_extension (const string_o &s, int pi = NULL) SYNOPSIS: this sets the file's extension. If the file name has been set earlier, the extension will be changed to that given in 's'. Any string is allowed here. Example: file_o f; f.set_name ("myfile.txt"); // myfile.txt f.set_extension ("php"); // myfile.php PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: extension successfully set zErr_Param_NotSet: 's' is an empty string TRAITS: a "configuration" member function set_address()* SIGNATURE: int set_address (const string_o &s, int pi = NULL) SYNOPSIS: this call sets the address to that of 's' (path and file name, or just file name) PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: address successfully set zErr_Param_NotSet: 's' is an empty string RETURNS: 0 set_address()* SIGNATURE: int set_address (const file_address_o &new_addr, int pi = NULL) SYNOPSIS: a "configuration" member function. sets the address to that of 'new_addr' (path and file name). PARAMETERS pie: an [optional] error indicator [output] variable. values: 0: address successfully set zErr_SameData: the new address (in 'new_addr') is the same as the existing/prior address RETURNS: 0 set_flag()* SIGNATURE: int set_flag (enum File_Flag x, boolean is_on = TRUE) SYNOPSIS: a "configuration" member function. sets a flag (property value) for the file object. Only user-configurable flags may be set. Flags that are not for the user to configure are internal state flags. If the user tries to set such a flag, this function will return the error value of -1. PARAMETERS x: can be z_Remove_On_Exit or z_Overwrite_On_Create. The other flags (z_Address_Is_Set, z_Bound_To_File, z_Is_Open) are not set by the user. is_on: if TRUE, the flag is set; if FALSE, the flag is unset (cleared). set_textmode() SIGNATURE: int set_textmode (boolean is_on = TRUE) SYNOPSIS: a "configuration" member function. use this prior to calling member function open(). Tells the object what type of file it is (text or binary). PARAMETERS is_on: if TRUE, the object is set to "text mode"; if FALSE, the object is set to "binary mode". setmode_binary() SIGNATURE: int setmode_binary (boolean is_on = TRUE) SYNOPSIS: a "configuration" member function. use this prior to calling member function open(). Tells the object what type of file it is to open (text or binary). This function is the exact inverse of "set_textmode()". PARAMETERS is_on: if TRUE, the object is set to "binary mode"; if FALSE, the object is set to "text mode". set_directory() SIGNATURE: int set_directory (const string_o &s, int pie = NULL) SYNOPSIS: a "configuration" member function. set the directory part of the file's address. the string "s" must be a valid path in order for this function to succeed. operator =()* SIGNATURE: const file_o &operator = (const string_o &s) SYNOPSIS: open the file, copy the contents of "s" to the file, then close the file. does a complete write operation. DESCRIPTION: similar to store(), but automatically opens and closes the file. This function is being debated because it may appear to be setting the file name (use set_name() for setting the file name). WARNING!: this does not* set the file name!* TRAITS: the user may assume a different meaning to this operation operator +=() SIGNATURE: const file_o &operator += (const string_o &s) SYNOPSIS: this concatenates the contents of string 's' to the file. The file must exist in order for this operation to succeed. DESCRIPTION: this operator is closely related and coupled to the assignment operator: string_o s1 = "A thousand leagues;\n"; string_o s2 = "a thousand leagues.\n"; file_o f("myfile.txt"); f = s1; f += s2; reset() SIGNATURE: int reset (int pi = NULL) SYNOPSIS: returns the file object to its at-construction state. closes any associcated file, if open, and wipes out the address (file name and path). PARAMETERS pi: [output] error indicator variable. values: 0: successfully reset zErr_Item_CantClose: could not do a file system close create()* SIGNATURE: int create () SYNOPSIS: creates a new file. The file's address must be set. If there is a file by the same name in the same location when this function is invoked, if the flag z_Overwrite_On_Create is set, the file will be over-written and its existing contents lost. If such a file exists and z_Overwrite_On_Create is not set, this function will return -1. rename() SIGNATURE: int rename (const string_o &new_name) SYNOPSIS: renames the file. the new name must be "simple" - it cannot have a directory-separator symbol imbedded in it. The current file object must have the name and path set, and be a valid file in the current file system. relocate() SIGNATURE: int relocate (const directory_address_o &new_home) SYNOPSIS: moves a file from its current location to the new address specified by "new_home" RETURNS: 0: successful relocation (or target address is same as current address) -1: error (possibley invalid address) remove() SIGNATURE: int remove () SYNOPSIS: deletes the file from the file system. The current file object must have the name and path set, and must represent a valid file in the current file system. kill() SIGNATURE: int kill (boolean all_links = TRUE) SYNOPSIS: deletes a file. If the given file is (one or more) symbolic link, this will follow the links to the final destination and terminate the final file - if there is one. deep_copy() SIGNATURE: int deep_copy (const directory_address_o &dir, int direc = 0, boolean stomp = FALSE) SYNOPSIS: This function copies to/from another file. This function is exactly analogous to the other signitures of "deep_copy()" (which see), except that the first parameter type is directory_address_o. Basically this function is equivalent to "deep_copy(const file_o &that ..)", where the file name of "that" is the same as this (the current object), and the directory path of "that" is whatever is specified in "dir". Please see this other "deep_copy()" signiture variant for behaviours of this function. PARAMETERS dir: the source or destination file. If direc is 0, "dir" is the source location, and the file given by the current object will be copied from "dir". direc: a flag; tells this function whether to copy from or to the other file. stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted. deep_copy() SIGNATURE: int deep_copy (const file_address_o &new_addr, int direc = 0, boolean stomp = FALSE) SYNOPSIS: This function copies to/from another file. This function is exactly analogous to "deep_copy(file_o, int, boolean)" (which see), except that the first parameter type is file_address_o instead of file_o. This function is explicitly provided since there is no automatic conversion from file_address_o to file_o. PARAMETERS that: the source or destination file. If direc is 0, "that" is the source file, and the file given by this object will be copied from "that". direc: a flag; tells this function whether to copy from or to the other file ("that"). stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted. deep_copy() SIGNATURE: int deep_copy (const file_o &that, int direc = 0, boolean stomp = FALSE) SYNOPSIS: This function copies to/from another file. If the second parameter ("direc") is 1, it copies the file given by the current object to a new (or possibly existing) file. If "direc" is 0, it does the converse: this function then copies the other file ("that") to the file given by the current object. The current file object must have the name and path set. The directory location must be valid in order for this operation to succeed. Whether the file exists or not depends on the parameters to this function call. If writing to another file (direct == 1), and there is a file in the same target name and path as "that", it will be over-written only if "stomp" is TRUE. If the target file is the same as the current file object, nothing is done and 0 is returned. PARAMETERS that: the source or destination file. If direc is 0, "that" is the source file, and the file given by this object will be copied from "that". direc: a flag; tells this function whether to copy from or to the other file ("that"). stomp: a flag; tells if the operation is permitted or not if the target file exists prior to this function call. If stomp is TRUE, the copy operation will always be attempted. If FALSE, and if the target file does not exist, the copy will be attempted; else, if the target file exists the operation will be aborted. true_path() SIGNATURE: int true_path (string_o s_relpath) const SYNOPSIS: expands the path given by "s_relpath" to the absolute, full fixed path. TRAITS: why is this function not static? needs investigation open()* SIGNATURE: int open (enum File_Open mode = zFile_Read) SYNOPSIS: opens a file for [subsequent] reading. The methodology corresponds to that used by fopen(). set_textmode() should be called prior if the file is a text file, and setmode_binary() in the case the file contains binary data. PARAMETERS mode: how to open the file. valid values are: zFile_Read: open the file for reading. zFile_Write: open the file for writing. this will overwrite any existing contents zFile_Create: create a new, empty (0-length) file. zFile_Append: open the file for appending data to it. any previously existing contents will be preserved; new data will go after it. close() SIGNATURE: int close () SYNOPSIS: "close" an open file. if the file has not been opened, this routine does nothing and returns 0. flush() SIGNATURE: int flush () SYNOPSIS: flush all changes done on the file to the disk. That is, if the OS has buffered any data, calling this function will cause the OS to sync the data, should the OS have buffered any (basically this maps onto a fflush() system call). get_line() SIGNATURE: int get_line (string_o &s, int flags = 0) const SYNOPSIS: gets the next line of text from the file. The file must have been opened [via open() call] prior. PARAMETERS s: string object that recieves the next line from the file flags: bitmap of flags controlling usage of trailing space. bit 0: add a newline ('\n') [value: 1] bit 1: trim trailing space, including newlines [value: 2] eg, a value of 1 appends a newline, and a value of 2 trims the line. note that a value of 3 gets you a trimmed line with '\n' at the end (if that makes any sense). RETURNS: 0: new line successfully read in 1: EOF -1: error occured. TRAITS: non-standardized parameter list. "flags" should be flag object, not int. This function will probably recieve an additional parameter at the end - an [output] error indicator variable. put_line() SIGNATURE: int put_line (const string_o &s) SYNOPSIS: writes the text in "s" out to the file. the file should be opened previously and in "text mode". Note that 's' can have multiple lines (multi-line text is typically stored in a derived class textstring_o). Everything in 's' is written, up to (but not including) the terminating '\0'. TRAITS: the name put_line() is somewhat misleading as it implies that only a single line of text is written out. get_bytes() SIGNATURE: int get_bytes (string_o &s_b, size_t n, int pie) const SYNOPSIS: read a byte stream in from a file. Since the string object can be put into binary mode and then can hold binary bytes, this member function uses "s_b" to hold the block of data. The file must have been opened prior to calling this function. Make sure that if the file contains [non-text] binary data, that the file object was set to the correct mode prior to opening it. Also, the string needs to have its internal buffer allocated so that it can accomodate "n" bytes. This should be done like so: int ierr, rv; file_o f; // configure the file object.. size_t numbytes = 512; string_o s; s.force_size(800); // VITAL f.setmode_binary(); // if binary (eg "pic.jpg") f.open(); rv = f.get_bytes(s, &numbytes, &ierr); PARAMETERS s_b: a string object that will recieve the data. if the size of the string is less than "n", it will be resized inside this function. n: the [maximum] number of bytes to read. this value must be known in advance. also, this number will be set to the number of bytes actually read (which can be less than what it was set to, if there are not enough bytes to fill the original buffer size). RETURNS: 0: successful byte read 1: successful read, but less than the alloted capacity -1: error put_bytes() SIGNATURE: int put_bytes (const string_o &s_b, size_t p_n, int pie) SYNOPSIS: write a byte stream out to a file. the string object containing the bytes must be in binary mode. If the file has not been opened for writing prior, this routine will open the file with mode zFile_Write. PARAMETERS s_b: string containing the byte block to be written. p_n: number of bytes to write. if the size of "s_b" is less than this number, the lesser size will be used. this is also an output variable - the actual number of bytes written will be put in this parameter. pie: an error indicator [output] variable. load() SIGNATURE: int load (string_o &s, int pie = NULL) SYNOPSIS: loads the contents of a file into a string object. the mode (text or binary) is dependent on the file and / or string object: if either is in binary mode, the load-mode is set to binary; else, the load is done in text mode. load()* SIGNATURE: int load (string_o &s, int flags = 0, int pie = NULL) SYNOPSIS: loads the contents of a file into a string object. the file can be text or binary. you specify which in the "flags" [2nd] parameter. Data will be loaded into "s" either a line at a time (text mode), or in 4K chunks (4,096 bytes), if in binary mode. PARAMETERS s: the string object to recieve the contents of the file flags: additional control, for text mode. a bit-map. values: 1: add '\n' to each line 2: use line at a time loading, for text store()* SIGNATURE: int store (const string_o &s, int pie = NULL) SYNOPSIS: write out a string to a file. this is basically a convenience function. It is the converse of load(). fetch_properties()* SIGNATURE: int fetch_properties (int pi = NULL) SYNOPSIS: gets the properties (characteristics) of an existing file. the properties are stored in internal variables. These variables can get out of sync with the reality of the file, so the properties should be retrieved immediately after calling this function. if the file does not exist, this return will error out. PARAMETERS pi: an error indicator [output] variable. values: 0: successful fetch zErr_Resource_Missing: no such file zErr_Fetch_Failed: could not read contents of file zErr_Resource_Corrupted: failure trying to calculate MD-5 hash value zErr_NotSupported: this function not implemented on current OS RETURNS: 0: file properties fetched and set -1: error occured (have you set the file name?) string_o()* SIGNATURE: operator string_o () const SYNOPSIS: Read a file's contents to a string. usage: file_o f; string_o s = f; This subroutine automatically opens and closes the file. Set the mode to either text or binary, as appropriate, via set_textmode(). clone() SIGNATURE: file_o clone () const SYNOPSIS: does a new* and duplicates the file object in the new object instance. For symbolic canonical format usage. <<() SIGNATURE: friend std::ostream &operator << (std::ostream &, const file_o &) SYNOPSIS: prints the file's address to stdout. copy_to() SIGNATURE: int copy_to (const file_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)". copy_to() SIGNATURE: int copy_to (const file_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)". copy_to() SIGNATURE: int copy_to (const directory_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 1, stomp)". copy_from() SIGNATURE: int copy_from (const file_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)". copy_from() SIGNATURE: int copy_from (const file_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)". copy_from() SIGNATURE: int copy_from (const directory_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "copy_contents(rhs, stomp)" or "deep_copy(rhs, 0, stomp)". copy_contents() SIGNATURE: int copy_contents (const file_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)". copy_contents() SIGNATURE: int copy_contents (const file_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)". copy_contents() SIGNATURE: int copy_contents (const directory_address_o &rhs, boolean stomp = FALSE) SYNOPSIS: this member function is provided as a convenience. It is an alternate name - signature for the deep_copy() function. It is exactly the same as "deep_copy(rhs, 0, stomp)". note. This class, like the directory_o class, uses the concept of a virtual "directory separator", which is "/" in unix environments and "\" in Microsoft environments. The file_o class is not subclassed from the file_address_o class. However, file objects contain an instance of the file address class. This implementation took the viewpoint that the address of a file is a [very important] property of a file, but that a file is a file, not an address. Hence the relationship is "uses-a", not "is-a". The nomenclature for file-copy operations went thru a little evolution. Originally, it was a simple "copy()", but this member function is usually private in most other Z Directory objects. Also, just 'copy' lacks semantics about what is being copied and where. "copy_contents()" was the next choice, but given this: file_o fa, fb; fa.copy_contents(fb); It is not entire clear whether fa is being copied to fb or if fb is copied to fa. clone() was considered, but this is appropriate when creating a new file only. fa.clone(fb); just doesn't look right. We finally decided on providing several naming choices: copy_contents() - copies from the right-hand-side (RHS) object copy_from() - same as copy_contents() . copy_to() copy contents of current object to RHS target. deep_copy(x, i) copy contents from or to RHS object, depending on value of [integer] variable 'i': 0 - copy from RHS; 1 - copy to RHS. The object type of the parameter to each of these member functions can be a file_o, file_address_o. In the "copy-to" cases, it can also be a directory_o class instance. history. Fri 11/24/1995: merged old Z Directory file "killfile.c" ??? 12/20/1996: new & improved: added the "trim line" feature ??? 12/03/1997: bug fix in "file_o::file_o (string_o &)" Fri 05/01/1998: changed "get/put_bytes()", auto-open for read/write Sun 10/18/1998: changed "(file_o) = (string_o)" semantics ??? 10/26/1998: added "feof()" check {maybe solaris-specific?} Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_") Sun 09/07/2003: changed internal data member names Sat 09/06/2003: changed 2nd param, "boolean do_trim" to int Tue 02/15/2011: various bug fixes, eg, in "file_o::load()" Tue 06/12/2012: added function names: copy_contents(), copy_from/to() Fri 11/27/2015: error output code values cleaned up for many functions Fri 04/15/2016: added-created function: operator += (const string_o &)
home \|\| support \|\| FAQ \|\| get Z Dir \|\| contact us Copyright 2010 Vettrasoft Corporation - All Rights Reserved