nvf_util - EPOCH Named Variable Set Files

The NVF_UTIL package provides a C language implementation of EPOCH's C++ nvarsetFile (named variable set file) class. A C++ nvarsetFile object is associated with a single disk file: when a named variable set is added to the file, the set is immediately written out to disk and, when a named variable set is retrieved from the file, the disk file is searched for the desired set.

An NVF NVarSetFile, in contrast, is a virtual "file", a memory-resident collection of named sets of named variables. Sets can be programmatically added to or deleted from the collection and the current contents of the collection can be saved to or loaded from an arbitrary disk file at any time.

An empty, memory-resident "file" of named variable sets is created as follows:

    #include  "nvf_util.h"			-- Named variable files.
    NVarFile  file ;
    ...
    nvfCreate (&file) ;

Named variable sets are added to the file using nvfAdd(). The following example creates a two-member set, "numbers", and adds it to the memory-resident file:

    nvsCreate ("numbers", &set) ;
    nvsAdd (set, nvrNew ("THIS", NvrFloating, 123.45)) ;
    nvsAdd (set, nvrNew ("THAT", NvrInteger, 6789)) ;
    nvfAdd (file, set) ;

The sets in a memory-resident file can be retrieved by index:

    #include  <stdio.h>				-- Standard I/O definitions.
    int  i ;
    NVarSet  set ;
    ...
    for (i = 0 ;  i < nvfCount (file) ;  i++) {
        set = nvfGet (file, i) ;
        printf ("%s (%d members)\n", nvsName (set), nvsCount (set)) ;
    }

or by name:

    set = nvfFind (file, "numbers") ;		-- Prints "numbers (2 members)".
    printf ("%s (%d members)\n", nvsName (set), nvsCount (set)) ;

Individual sets can be deleted from a memory-resident file:

    set = nvfDelete (file, "numbers") ;

Although the set is removed from the memory-resident file, the set itself is not destroyed. In contrast, deleting a memory-resident file:

    nvfDestroy (file) ;

automatically destroys the remaining sets via calls to nvsDestroy(). Note that destroying a memory-resident file does not affect the contents of any disk files to which the "file" was saved.

Named variable sets can be loaded from a disk file:

    nvfLoad (file, "pathname") ;

and the current contents of a memory-resident file can be saved to disk:

    nvfSave (file, "pathname") ;

The ASCII disk file is formatted as follows:

    # Comment

    [setName1]
    name1 = value1		# Comment
    ...
    nameN = valueN

    [setName2]
    name1 = value1
    ...
    nameN = valueN

    ...

See nvrDecode() for a more complete description of the name/value specification format. Comments are introduced by '#'; a '#' embedded in a value should be escaped with a '\'.

Public Procedures

nvfAdd() - adds a named variable set to a file.

nvfCount() - returns the number of named variable sets in a file.

nvfCreate() - creates an empty named variable file.

nvfDelete() - deletes a named variable set from a file.

nvfDestroy() - destroys a file.

nvfFind() - retrieves a set by name from a file.

nvfGet() - retrieves a set by index from a file.

nvfLoad() - loads a memory-resident file of sets from a disk file.

nvfSave() - saves a memory-resident file of sets to a disk file.

Source Files

nvf_util.c

nvf_util.h