category-group: files
layer(s): 0, 2, 9, 10

header file(s): z_baredisk.h, z_filesubs.h, z_file.h, z_phpfile.h, z_imagefile.h, z_inifile.h,
                        z_txtfilesubs.h, z_directory.h

synopsis.
The "files" group refers to files and directories on a file system on a hard drive. Standard computer science terminology is invoked here - a "file" here is an agglomoration of bits, not something held by the FBI; a directory is synonymous with a Microsoft "folder"; a "hard drive" is an electronic device for holding these things, not a road trip around the Beltway or the Perimeter during rush hour.

There are 5 groupings in the file zone:

1. low-level functions (in layer 0);
2. low-level objects (in layer 2) for managing hard drives;
3. high-level class objects (file and directory),
4. objects directly relating to a file or directory as an address. Since they are technically classified as "address objects", they fall under the address domain.
5. more specialized objects, such as the PHP file processor object, the INI file object, or the image file object (see the respective links below).

[1] Many of the layer-0 functions manifest themselves in the higher level objects. So you have a choice whether to use the object to do the operation (create, delete, rename, etc) or the subroutine.

[2] with the class baredisk_o, you can get information about a specific disc drive attached to the computer, including [in Microsoft OS environments,] the VSN (volume Serial Number).

[3] 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" class 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 do a one of copy_contents() , copy_from() , or copy_to() - not a simple assignment. This is conceptually similar to the difference between deep copy and shallow copy. See the main discussion in the file object page for more information.

[5] A new and quite interesting component (added June 2012) related to files is the PHP file processing system. This is a methodology based on PHP CLI that allows you to generate files with embedded PHP script-code in it. This is done from a C++ program. All that is needed is for PHP (at least version 4.3.0) to be installed on the local computer where your program is run. For more details, see the PHP file object page.

Another very useful item is the inifile_o object, which processes .ini files. The INI file object is not restricted to Microsoft OSes only, and is a great way to set program parameters (the unix equivalent would be a .rc file).

Layer 10 has 2 [global-scope] functions, z_getnext_inputline() and z_getnext_databa(). These are functions that are intended to by be called within a loop. They get subsequent single lines or entire recursive databags (in one gulp), respectively.

classes in this group: baredisk_o, file_o, tmpfile_o, phpfile_o, phpfile_o, imagefile_o,
                                      directory_o

function groups: layer 00 functions group
                              layer 10 functions group

description.
There is more than one syntax for describing a path in a file system. Historically, 2 major syntaxes have evolved: "unix" and "Microsoft". The basic difference between them is that unix systems have traditionally used a forward-slash character ('/') to separate directory names in a path, whereas Microsoft has used a back-slash ('\'). We avoid delving into the reasons for this ridiculous point of contention - such is the state of the world. When using paths, one can write a string in the format used by the underlying OS. This can lead to unportable code. To mitigate this problem, Vettrasoft created and recommends using the function z_DIRSEP() (header file entry in 'z02_func.h'), which returns a string object containing the correct character:

  #include "z_file.h"
  void main()
  {
    string_o badpath = "c:\\Documents and Settings\\account\\TEMP";
    string_o gudpath = string_o("C:") + z_DIRSEP();
    gudpath += string_o("Documents and Settings") + z_DIRSEP();
    gudpath += string_o("account") + z_DIRSEP() + "TEMP";
    file_o f1(badpath), f2(gudpath);
  }

In this example, the paths for the file objects f1 and f2 will both be set if the program runs on a Microsoft box, but the path given by 'badpath' uses invalid syntax in unix environments.
There is a logical blurring of groups with the advent of the image file object ( imagefile_o ). Image processing belongs in its own category, to which image files (.jpeg, .gif, .bmp etc) probably belong to - but at least for now, this component is with the files group.