synopsis.
the tmpfile object (tmpfile_o) represents a single, "temporary" file. "Temporary files" (or, "tmp files") are files that, like the name implies, exist for a short bit of time, usually as a place to put output until a program is finished processing. Often a program that modifies a file needs a temporary place to store the modified file's contents while the file is being processed by the program. Afterwards, the file may be replaced by the modified output. In this case, the application may take on the bookkeeping of finding a name and location for the temp file. However, this processing is so common that this object has been provided to do this bookkeeping. The tmpfile object both provides a unique file name and location.

description.
The tmpfile_o class generates temporary file names. The temp file base name pattern defaults to "ZZXYZTMP000.tmp", and the temp directory defaults to whatever is the first temp directory found by the function "z_tempdir()". Temp file names are created by successive calls to the member function "new_name()". A unique name is generated by each call by updating the digits pattern in the base file name. That is, given a base name of "ZZXYZTMP000", file names of "ZZXYZTMP001.tmp", "ZZXYZTMP002.tmp", "ZZXYZTMP003.tmp", "ZZXYZTMP004.tmp", etc will be generated. Only the digits part of the file name will change.

Three parameters relating to temp file names can be set by the application: the base file name pattern (via 'set_basepattern()'); the file extension (via 'set_extension()'); and the temp directory (via 'set_tempdir()').

member functions (primary)

tmpfile_o()
SIGNATURE: tmpfile_o ()
SYNOPSIS:
creates a a new tmpfile object, completely devoid of name, path or contents. However, global names for the template file basename, file extension, and temp dir path are established.
 

tmpfile_o(tmpfile_o)
SIGNATURE: tmpfile_o (const tmpfile_o &rhs)
SYNOPSIS:
creates a a new tmp. file object, based on the [temporary] file represented by file object "rhs". The file's name and address will be copied (if set).
 

operator = (tmpfile_o)
SIGNATURE: const tmpfile_o &operator = (const tmpfile_o &rhs)
SYNOPSIS:
the temp file object's contents is replaced with that of "rhs". the object will have a new file address that is equal to that of "rhs".
 

destructor
SIGNATURE: ~tmpfile_o ()
SYNOPSIS: destroys the class object instance. Any contents, path, and name for the temp file are destroyed.
 

set_tempdir()
SIGNATURE: int set_tempdir (const directory_address_o &da, int *pi = NULL)
SYNOPSIS:
this is a "manual over-ride" for the location of the "temporary directory" (TEMP dir). On unix systems, the default path of this directory is "/tmp". On Microsoft systems, this location is often determined by an environment variable such as TEMP, TMP, or a directory called \TEMP or \TMP on a file system specified by an environment variable such as SystemDrive, SystemRoot, HomeDrive, HOME, or COMSPEC. If the application wishes to over-ride whatever the tmpfile_o class determines for this directory, it may supply the path to the directory to use in input parameter "da". This is a static function. It must be called without an object instance:

  directory_address_o da = "/tmp";
  tmpfile_o::set_tempdir (da);

PARAMETERS

• da: directory address object. set this object's path prior to calling this function. Note that the path "da" is set to need not exist. The global temp directory will be set to the value of "da", whether the value is valid or not. If not, the [optional] error indicator output parameter "pi" will be set to 1.
• pi: an error indicator [output] variable. values:
  0: global temp dir set, and temp dir is valid
  1: global temp dir set, but temp dir is not valid (does not exist).

 

set_basepattern()
SIGNATURE: int set_basepattern (const string_o &s, int *pi = NULL)
SYNOPSIS:
this static function allows client application control of the temp file base name, which acts as a template for all future temp file name generation. The contents of input parameter "s" should be the file base name only (eg, without path or file extension). It should have numbers in the name. If not, the next invocation of "new_name()" will fail to generate a name. For example:

  tmpfile_o tf;
  string_o s;
  flag_o f(8,0);
  tmpfile_o::set_basepattern ("A-ATLAS.000");
  tf.new_name (s, f);           // 1st invocation
  tf.new_name (s, f);           // 2nd invocation

In the example above, invocation [1] will set string object "s" to "A-ATLAS.001". invocation [1] will set it to "A-ATLAS.002". If set_basepattern was to be called with its parameter set to "A-ATLAS", each invocation of new_name() would return the same file name ("A-ATLAS"). This is undersirable, as a new temp file name should not be that of an existing file (there is no way to tell a 'real' file from that of a temp file). The more digits (preferably 0's), the better - that is, more temp file names can be generated. In this example, 1,000 temp file names are available with the base name pattern "A-ATLAS.000": ["A-ATLAS.000" .. "A-ATLAS.999"].
PARAMETERS

• s: string object holding the base file name pattern to use.
• pi: an error indicator [output] variable. values:
  0: base name pattern well-set;
  1: parameter "s" is an empty string (error condition);
  2: string contents of parameter "s" contains no digits (warning condition)

RETURNS:
0: global file basename pattern set.
-1: error; global file basename pattern not set.
 

set_extension()
SIGNATURE: int set_extension (const string_o &s, int *pi = NULL)
SYNOPSIS:
set the default temp file name extension to that of "s". this function is static - it cannot be called with an object instance:

  tmpfile_o tf;
  string_o s;
  tmpfile_o::set_extension ("cpp");
  tf.new_name(s, flag_o(4,0));          // s: "ZZXYZTMP001.cpp"

If this function is not invoked, the temp file extension will be ".tmp" (ie, "ZZXYZTMP001.tmp").
PARAMETERS

• s: string object holding the file name extension to use. the string should not have a leading dot ('.'; or whatever is used for basename - extension separation).
• pi: an error indicator [output] variable. values:
  0: base name pattern well-set
  1: parameter "s" is an empty string (error condition)

 

clear_destroy_onexit()
SIGNATURE: int clear_destroy_onexit ()
SYNOPSIS:
Normally (by default), any actual file corresponding to the temp file object instance is deleted (removed) from the file system by the object's destructor. If this static function is called, that behaviour will be prevented. Thus, it will be up to the application to do any cleanup by removing temp files. However, you must explicitly invoke this function.
Example:

void main()
{
    string_o sfil;
    somefunc(sfil);
    if (z_file_exists(sfil.data()))
         std::cout << "file " << sfil << ": exists!\n";
    else
         std::cout << "file " << sfil << ": deleted.\n";
}


int somefunc(string_o &snam)
{
    tmpfile_o tf;
    string_o s = "rats live on no evil star";
    tf.new_name (snam, flag_o(8, 1));
    tmpfile_o::clear_destroy_onexit();
    tf = s;             // create a file with a palindrome
}

In the example above, the message "file [name]: exists!" will appear, due to the call to 'clear_destroy_onexit()'. Without it, you would see "file [name]: deleted." (where [name] is whatever file name was assigned).
 

set_destroy_onexit()
SIGNATURE: int set_destroy_onexit (boolean doit = TRUE)
SYNOPSIS:
Normally (by default), any actual file corresponding to the temp file object instance is deleted (removed) from the file system by the object's destructor. If this static function is called (with no arguments, the default is TRUE) then temp files (the actual file, not the object in the program) will be deleted when its object goes out of scope.
 

new_name()
SIGNATURE: int new_name (string_o &s, flag_o &f, int *pi = NULL)
SYNOPSIS:
generates a new temp file name. The output parameter 's' is optional, as the object file name will also be set to the value put into 's' (use either). The second parameter, 'f', is used to determine whether the temp directory (that is, the full path) should be included in output parameter 's' or not. Only the first bit of this flag object is used: value of 0 for file-only, 1 for path + file name.
PARAMETERS

• s: string object holding the [path and] file name from the next temp file name.
• f: flag object, controls format of output stored in 's'. if this flag-bit is set (value = 1), include the path of the temp dir in 's'; if cleared (value = 0), only the temp file name is put into 's'.
  AS OF THIS WRITING [June 2012] the following is planned but not yet implemented: if the 2nd bit is set (bit 1, counting from 0), the directory for the temp file is the current directory, not the temp directory.
• pi: an error indicator [output] variable. values:
  0: temp file name successfully created
  1: error, max name limit hit (eg, "99999")
  2: error - no new name could be made. probably because the "basename template pattern" has no numbers in it
  3: error in getting the temp dir path

RETURNS:
0: new temp file name successfully generated
-1: error in creating temp file name (see value of 'pi' for the reason why).
 

z_tempdir()
SIGNATURE: int z_tempdir (directory_address_o &my_td, int which = 0, int *pi = NULL)
SYNOPSIS:
this is a global-level function (not a member of tmpfile_o). It is included with the tmpfile_o class because it is directly related to it. This function searches for the 'temp' directory. It assumes there are multiple qualified candidate directories, and you can specify which by the "which" input parameter. By default, "which" is 0, meaning get the first temp directory that is found (on unix systems, this is usually the only one, and it is always "/tmp"). This routine searches for 'tmp' directories in this order (for all OS's):

[1] pointed to be "TEMP" environment variable;
[2] pointed to be "TMP" environment variable;
[3] pointed to be "TMPDIR" environment variable;
[4] "/tmp", in the root file system;
[5] "/temp", in the root file system (Microsoft only)

In Microsoft enviroments, a "root file system" is found on a drive unit given by these candidate environment vars:

SYSTEMDRIVE
SYSTEMROOT
HOMEDRIVE
HOME
COMSPEC
WINDIR

A drive unit associated with any of these variables is a candidate for holding a tmp directory. For example, if "SystemRoot" is "C:\WINDOWS", the corresponding drive unit is "C:". If there is a /tmp or /temp directory on that drive ("C:\TEMP" or "C:\TMP"), it is considered to be a "temp" directory.
PARAMETERS

• my_td: directory_address_o object holding the path of the temp directory (if one is found).
• pi: error indicator variable. Values:
  0: found (success);
  1: no temp directory found;
  2: there exists at least 1 tmp directory, but # tmp dirs < 'which';
  3: error in getting full-actual path;
  4: unhandled case value (internal error)

RETURNS:
0: temp dir successfully found and set in "my_td"
-1: error occured (see value of 'pi' for the reason why)
 

examples.
Here is a quick example of how temp files can be used:

#include "stdafx.h"
#include "z_file.h"
#include "z_string.h"

#define MY_TEXT "a thousand leagues;\na thousand Arabian nights;\n"

//----------------------------------------------------------------------
int main (int argc, char *argv[])
{
    int ie;
    z_start();              // Z Directory global initialization

    string_o of;
    string_o s(MY_TEXT);    // text-contents of original file
    file_o f;               // set up a file object
    tmpfile_o tf;           // and set up a temp file object

    f.set_name ("abc.txt");
    f = s;                  // write contents of 's' to file "abc.txt"
    s.search_replace (";", "!", string_o::z_Find_All);
    ie = tf.new_name(of, flag_o(2,0));

    file_o &rf = tf;        // need cast to do "tf = s;"
    rf = s;                 // write new contents of 's' to temp file
    f.remove();             // remove original file "abc.txt"
    tf.rename("abc.txt");   // rename temp. file to "abc.txt"
    z_finish();             // clean up...
    return 0;               // & exit successfully
}