category-group: files
layer: 10
header file(s): z_txtfilesubs.h
libraries: libz10.lib

synopsis.
In this compartment (layer 10 - files), we have 2 functions to yield the contents of a text file:

  • z_getnext_inputline() - returns a single line
  • z_nextdbag_fromfile() - returns single recursive databag.
And 5 files related to image files:
  • z_imagefile_fix_badextension() - corrects an image file to its actual type (if it's wrong)
  • z_imagefile_type() - returns a code (see 'z_file.h') indicating what type of image file it is (if it is one)
  • z_imagetype_magicheader() returns the image file type based on a block of bytes (this is more of an internal function)
  • z_lookslike_imagefile() - determines whether it's an image file based on file extension
  • z_imagefile_code_to_extension() - code to string mapping utility function
z_nextdbag_fromfile() implements a specific [quick & dirty?] protocol, of wrapping the databag with the lines "# :start-databag:" and "# :end-databag:".
For example:
# :start-databag: target ( slogan ( name "Keep the Faith" ) name (first Lamine last Zhivago) arpa "dre@ditto.harvard.edu" sex M ); # :end-databag:

# :start-databag: target ( slogan ( name "Peanut Butter Fans" ) name (first Srinivas last Kolliflower) arpa "s_kolliflower@yahoo.com" sex M ); # :end-databag:

The first time z_nextdbag_fromfile() is called, it returns a databag for Lamine Zhivago; the second time, that for Srinivas Kolliflower; a third call will fail, returning an error condition and an empty databag.

For images files, a list of image codes exists to represent the major image types:

Z Directory image codes
macro name value description
zt_Image_JPG 1
zt_Image_PNG 2 portable network graphics
zt_Image_GIF 3 graphics interchange format
zt_Image_TIFF 4 tagged image file format
zt_Image_BMP 5 Microsoft bitmap format
zt_Image_ICO 6 Microsoft icon format
zt_Image_WEBP 7 Google WebP format (a type of .riff)
zt_Invalid_Image -1 not an image

[C] functions (aka subroutines):

z_getnext_inputline()
SIGNATURE: int z_getnext_inputline (file_o &f, string_o &s, const boolean use_file, int *pexi)
SYNOPSIS:
gets a line of input. z_file_exists() for a discussion on the formatting of the path parameter.
PARAMETERS
  • pie - error indicator output variable. values:
    0: ok; directory is bona-fide;
    1: does not exist;
    2: entry exists, but it is not a directory
  • path - the directory, as a string. This value should be either the fully-qualified path (including the directory itself), or a valid path relative to the current program.
RETURNS:
TRUE: directory exists
FALSE: no such directory (or error)
 

z_nextdbag_fromfile()
SIGNATURE: int z_nextdbag_fromfile (file_o &f, rec_dbag_o &dbag, const string_o &pre_sep = "# :start-databag:", const string_o &post_sep = "# :end-databag:", const string_o &sep = "", int *pi = NULL)
SYNOPSIS:
gets a the next recursive databag from a file referenced by 'f'. The file must have been opened prior to calling this function.
See the main description on this page for an example of this function's usage.
PARAMETERS

  • f: file object referencing a previously opened file
  • dbag: output variable, holds the contents of the databag retrieved from the file. Any previous contents is wiped out.
  • pre_sep: [input] pre-bag indicator. Must be on its own line anything following this line is part of thet next databag to be processed.
  • post_sep: [input] post-bag indicator. Must be on its own line used in conjunction with 'pre_sep'.
  • sep: if you want to have a single line of text separating databags, set this to non-empty. Doing so will negate the usage of the 'pre_sep' and 'post_sep' parameters
  • pi: error indicator output variable. values:
    0: databag retrieved succesfully
    1: end of file
    2: file has not been opened
    -1: error occurred
RETURNS:
0: databag retrieved succesfully
-1: otherwise (see value of 'pi' for more detail)
 

z_imagefile_fix_badextension()
SIGNATURE: int z_imagefile_fix_badextension (file_o &f, int *pi = NULL)
SYNOPSIS:
this routine checks the file extension and compares it to 'x'. if it's different, the file is renamed so that the extension matches. The address of the file (name and path) must be set, in 'f'. The file can have an extension indicating an image file (eg ".gif", ".jpeg", .ico", etc), a different extension not related to images (eg ".txt"), or even no extension at all. The file will be given the correct extension if it is detected to be an image file.
This subroutine uses z_imagetype_magicheader() to look at the file's header in determining the file format.
PARAMETERS

  • f: [input] - a file object representing the file.
  • pi [output] - error indicator output variable. values:
    0: success
    zErr_Item_NotFound: file does not exist
    zErr_Read_Failed: could not open or read the file
RETURNS:
0: success
1: file extension matches internal file magic (no change)
-1: error (see 'pi')
 

z_imagefile_type()
SIGNATURE: int z_imagefile_type (const file_o &f, boolean strict = FALSE, int *pi = NULL)
SYNOPSIS: returns an integer code indicating the type of image file the file contains.
PARAMETERS

  • f: the file object
  • strict: if TRUE, does a more strict check to confirm the type of image file (if possible). This in reality is useful only for JPEG files.
  • pi [output] - error indicator output variable. values:
    0: success
    zErr_Item_NotFound: file does not exist
    zErr_Read_Failed: could not open or read the file
RETURNS:
0: success
-1: error ocurred (see 'pi')
 

z_imagetype_magicheader()
SIGNATURE: int z_imagetype_magicheader (const byte_t *data, size_t nb, boolean strict = FALSE)
SYNOPSIS:
this determines the image type based on the contents of the block of bytes in 'data'. This function is analogous to z_imagefile_type(), but operates on a byte array instead of a file.
PARAMETERS

  • data: a binary character array pointing to the
  • nb: the length of 'data'. Must be at least 16 bytes
  • strict: use "strict mode" (see z_imagefile_type())
RETURNS: [code x]: integer code indicating the image type (see chart above).
 

z_lookslike_imagefile()
SIGNATURE: boolean z_lookslike_imagefile (const file_o &f)
SYNOPSIS:
this examines the file extension of the file represented by file object 'f' to determine if the file is [probably] an image file. no internal contents is inspected.
PARAMETERS

  • f [input] the file object
    • RETURNS:
    TRUE: the file's extension is that of an image file (.bmp, .ico, .jpg, ..)
    FALSE: otherwise.
     

    z_imagefile_code_to_extension()
    SIGNATURE: string_o z_imagefile_code_to_extension (const int x, int *pi = NULL)
    SYNOPSIS:
    this is a mapping (ie like a hash function) of Z Directory code to image file extension (see main discussion above for a list of values). the extensions are lower case. For JPEG files, the extension is "jpg" (not "jpeg").
    PARAMETERS

  • pi - error indicator output variable. values:
    0: successful lookup
    zErr_Param_BadVal: not a valid image code
    • RETURNS: [(string_o) s] string object containing the text equivalent of the image code