NVarFile - File of Named Variable Sets

The NVarFile class provides a different approach to collections of named variable sets than that the approach taken by EPOCH's nvarsetFile class. An EPOCH 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 NVarFile, 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  "NVarFile.h"			// Named variable files.
    ...
    NVarFile  file ;

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

    NVarSet  *set = new NVarSet ("numbers") ;
    set->Add (set, new NVar (123.45, "THIS")) ;
    set->Add (set, new NVar (6789, "THIS")) ;
    file.Add (set) ;

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

    #include  <cstdio>			// Standard I/O definitions.
    int  i ;
    NVarSet  set ;
    ...
    for (i = 0 ;  i < file.Count () ;  i++) {
        set = file.Get (i) ;
        printf ("%s (%d members)\n", set->Name (), set->Count ()) ;
    }

or by name:

    set = file.Find ("numbers") ;		// Prints "numbers (2 members)".
    printf ("%s (%d members)\n", set->Name (), set->Count ()) ;

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

    set = file.Delete ("numbers") ;

Although the set is removed from the memory-resident file, the set itself is not destroyed. In contrast, when a memory-resident file is destroyed (either explicitly or by going out of scope), the remaining sets are automatically destroyed. 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:

    file.Load ("pathname") ;

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

    file.Save ("pathname") ;

The ASCII disk file is formatted as follows:

    # Comment.

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

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

    ...

The decoding of the ASCII name/value specifications is done by NVar::Decode(); see NVars for a more complete description of the specification format. Comments are introduced by '#'; a '#' embedded in a value should be escaped with a '\'.

Public Methods

NVarFile() - creates an empty named variable file.

~NVarFile() - destroys a named variable file.

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

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

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

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

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

Load() - loads a named variable file from disk.

Save() - saves a named variable file to disk.

Source Files

NVarFile.cpp

NVarFile.h