synopsis.
the namevalue_set_o class is a very simple way of maintaining a set of name-value pairs. A name-value pair can be store in a namevalue_pair_o object. The namevalue_set_o class maintains a collection of these objects.

description.
This object is a simple combination of an ordered set object () with the namevalue_pair_o object. It can be used in a wide variety of applications, wherever you want to keep variables that can be represented in string format. For example:

• A web server gets a list of parameters from a client web browser, such as HOSTNAME, REMOTE_ADDR, REMOTE_USER, HTTP_REFERER, and HTTP_USER_AGENT. Since the names are unique, and the data is of a simple name-value pair, a namevalue_set_o instance can hold the set of variables for each connection.
• A medical procedure approval system recieves a request to check if a procedure is covered by an insurance policy. The data in the request is of the simple name-value format:
  

  NAME="Jonathan Seagull"
  SSNO="758-71-7881"
  SEX=M
  POLICYNO=1760589201
  PROBLEM="Acute Halitosis"
  

  
  These datums can be put into a string and fed to the namevalue_pair_o object:
  

      string_o s ("NAME=\"Jonathan Seagull\"; SSNO=\"758-71-7881\";");
      s += "SEX=M; POLICYNO=1760589201;PROBLEM=\"Acute Halitosis\"";
      namevalue_set_o nvp_set;
      int ie = nvp_set.load_from_string (s);
  

member functions (primary)

namevalue_set_o()
SIGNATURE: namevalue_set_o ()
SYNOPSIS: creates a a new namevalue_set object. There are no elements in the object at creation time.
 

namevalue_set_o(<args>)
SIGNATURE: namevalue_set_o (const string_o &s, char ch = ';')
SYNOPSIS:
creates a a new namevalue_set object. The objects in string 's' are loaded into it, as name-value pair objects. The character 'ch' is used to separate name-value pairs in string 's'. A semi-colon (';') is the default item separator.
 

namevalue_set_o(namevalue_set_o)
SIGNATURE: namevalue_set_o (const namevalue_set_o &rhs)
SYNOPSIS:
creates a a new namevalue_set object, based on the object represented by 'rhs'. The contents of 'rhs' is copied to the current object. Thus, the current object is a clone of 'rhs'.
TRAITS: this function is inlined
 

operator = (namevalue_set_o)
SIGNATURE: const namevalue_set_o &operator = (const namevalue_set_o &rhs)
SYNOPSIS: the current object's contents is replaced with that of 'rhs'.
 

destructor
SIGNATURE: ~namevalue_set_o ()
SYNOPSIS:
virtual destructor: this destroys the class object instance. all namevalue_pair_o elements contained inside are removed and destroyed.
 

size()
SIGNATURE: int size ()
SYNOPSIS: returns the number of namevalue pair objects contained inside.
 

separator()
SIGNATURE: string_o separator ()
SYNOPSIS: returns the number of namevalue pair objects contained inside.
TRAITS:
this is a static function. Its usage would be like so:

string_o s = namevalue_set_o::separator();

 

set_separator()
SIGNATURE: int set_separator (const string_o = ";")
SYNOPSIS:
This allows the user-application to override the default separator character(s). This string is used during printing [function print()] to separate name-value pairs.
TRAITS: this is a static function
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the object to empty. All namevalue pair objects contained inside are removed.
 

load()
SIGNATURE: int load (const string_o &s, char ch = ';', boolean addto = TRUE, int *pi = NULL)
SYNOPSIS: adds name-value pairs in 's' to the object. If 'addto' is FALSE, the object is emptied before the load operation begins.
DESCRIPTION:
This function uses a protocol that a single character separates name-value pairs. The character defaults to a semi-colon, but is configurable. Name-value pair string representations must be of the syntax NAME=VALUE. the NAME must be a 'word' type text (eg containing alphabetic or numbers, and '_'). VALUE can be any text up to the terminating character. If it contains white-space, it must be quoted (either single- or double-quotes). This function processes the entire string.
 

operator =+()
SIGNATURE: namevalue_set_o &operator += (const namevalue_set_o &that)
SYNOPSIS:
concatenats another set to this set. The new number of elements is the sum of the old number and the number found in 'that'.
RETURNS: reference to the current object.
 

print()
SIGNATURE: string_o print() const
SYNOPSIS: prints all the name-value pairs as one solid block of text.
DESCRIPTION:
the name-value pairs contained in the object are printed, one after another, Pairs are separated from each other by the separator string (by default, a semi-colon [';']).
 

get()
SIGNATURE: const namevalue_pair_o &get (const namevalue_pair_o &x, count_t *idx, int *pie)
SYNOPSIS:
searches for a name-value pair object whose name matches that of 'x'. if found, 'pi' is set to 0 and 'idx' is set to the element number (first element in the set has index value 0).
RETURNS: reference to the object found. if object is not found, the returned reference points to the 'bad-value' object.
 

get()
SIGNATURE: const namevalue_pair_o &get (const namevalue_pair_o &x, int *pi = NULL) const
SYNOPSIS:
searches for a name-value pair object whose name matches that of 'x'. if found, 'pi' is set to 0. This is a short-hand version of the version of get() with 3 parameters.
RETURNS: reference to the object found. if object is not found, the returned reference points to the 'bad-value' object, and 'pi' is set to non-zero.
 

get()
SIGNATURE: const namevalue_pair_o &get (count_t n, int *pi) const
SYNOPSIS:
retrievs the "nth" name-value pair object. This version of get() is useful (needed!) when the object in question is unknown, and the application wants to process each item in the set sequentially.
RETURNS: reference to the object found. if object is not found, the returned reference points to the 'bad-value' object, and 'pi' is set to non-zero.
 

add()
SIGNATURE: const namevalue_pair_o &add (const namevalue_pair_o &x, int *pi)
SYNOPSIS:
adds name-value pair object 'x' to the set. the name of 'x' must not be in the set prior to this call. If found, the operation will ot be performed and 'pi' will be set to a non-zero value.
RETURNS: reference to the object added. if an error occurs, the returned reference points to the 'bad-value' object.
 

update()
SIGNATURE: const namevalue_pair_o &update (const namevalue_pair_o &x, int *pi = NULL);
SYNOPSIS:
updates the name-value pair object contained in the current object, if found. Returns a handle to the actual object in the internal container [if found].
RETURNS: reference to the object updated. if an error occurs, or if the object is not found, the returned reference points to the 'bad-value' object.
 

put()
SIGNATURE: const namevalue_pair_o &put (const namevalue_pair_o &x, int *pi = NULL)
SYNOPSIS:
adds or updates the name-value pair object. Which action (add or update) depends if the key-value pair searched for is contained in the current object. Returns a handle to the actual object (maybe fresh) in the internal container.
DESCRIPTION:
this is a shorthand convenience function that obviates having to do this kind of coding:

int ie;
namevalue_set_o nvp_set;
y.set_name  ("my_item");
y.set_value ("my_value");
nvp_set.update(y, &ie);
if (ie)
    nvp_set.add(y, &ie);

RETURNS: reference to the object updated. if an error occurs, the returned reference points to the 'bad-value' object.
 

remove()
SIGNATURE: int remove (const namevalue_pair_o &x, int *pi)
SYNOPSIS: removes (deletes) 'x' from the set (if found).
 

usage.
Here is a quick example:

    int main ()
    {
        int ie;
        count_t idx;
        string_o s = "COMMAND=77;TIME=\"Dec 21, 2012 21:15:59\";\
HOSTNAME=burgundy;IP=127.0.0.1;OSTYPE=\"Windows Vista\"";

        namevalue_pair_o x;
        namevalue_set_o nvp;
        int ie = nvp.load_from_string(s);
        if (ie) return -1;
        x.set_name("COMMAND");

        const namevalue_pair_o &act_what = nvp.get(x, &idx, &ie);
        if (ie2)
            std::cout << "FAILED TO FIND 'COMMAND' keyword\n";

        x.set_name ("Chuck Norris");
        x.set_value ("2-bit actor");
        const namevalue_pair_o &newguy = nvp.add(x, &ie);
        if (ie) std::cout << "FAILED TO ADD Chuck Norris\n";
        if (newguy != x)
            std::cout << "oddness: Norris morphed into: " << newguy.name();

        // --loop thru each element of the name-value container--
        for (idx = 0; idx < nvp.size(); idx++)
        {
            const namevalue_pair_o &found = nvp.get(idx, &ie);
            if (!ie)
                std::cout << idx << ": " << found.name() << std::endl;
        }

        // --print all elements on 1 line--
        std::cout << "CONTENTS: " << nvp.print() << std::endl;

        return 0;
    }