CNVList

[Previous] [Main] [Next]

	The CNVList class is a general-purpose, standalone class that provides management, storage, retrieval, and enumeration of name/value string pairs. You can think of CNVList as a self-contained pool of strings that you can manipulate using simple strings as names. CNVList is used internally by html++, and several html++ user-level classes (such as htmlCgi) inherit from it.
	Name/value pairs are stored using the Value() method, which accepts an item name and it's associated value. The Value() method is overloaded to accept a String object or an integer as the value.

	CNVList   list ;
	//  Add two values to the list
	list.Value( "lname", "Smith" ) ;
	list.Value( "age", 36 ) ;

	You could also use the ( ) operator of CNVList to achieve the same result:

	CNVList   list ;
	//  Add two value to the list using the () operator
	list( "lname" ) = "Smith" ;
	list( "age" ) = 36 ;

	The ( ) operator of CNVList returns a reference to the actual string object for the value, which makes it convenient to create and assign new name/value pairs in a single statement.
	To remove a name/value pair from the list, assign it's value with an empty string, e.g.:

	//  Replace, then remove a value from the list
	list.Value( "lname", "Johnson" ) ;
	list.Value( "lname", "" ) ;

	NOTE: If you wish to store a name in the list without a value, use a dummy value of a space (" ") as a placeholder.
	The Value() method is overloaded as well to return the value for a specified name as a String. The ValueAsInt() method is provided to return the value as an integer, or you may use the String::AsInt() method directly on the returned String object.

	//  Retrieve a specific value from the list

	String last_name = list.Value( "lname" ) ;
	int    age = list.ValueAsInt( "age" ) ;
	As mentioned above, you could also use the ( ) operator of CNVList to achieve similar results:

	//  Retrieve a specific value from the list

	String last_name = list( "lname" ) ;
	int    age = list( "age" ) ;
	NOTE: It's important to note that the behavior of ( ) operator of CNVList differs slightly from what you might expect. If no name/value pair exists for the specified name, one will be automatically created with an empty value string. That is, if you use the () operator to see if a name/value pair exists and it doesn't, one will be created for you. This is because the () operator must return a reference to a String object.
	The Exists() method let's you test the entire list for existence of a specific name/value pair by name.

	//  Retrieve a value from the list

	if ( list.Exists( "lname" ) )
	{
	//  the value exists in the list
	}
	The Count() method returns the number of name/value pairs stored in the list as an integer, or zero if the list is empty.
	To delete the contents of a list, use the Reset() method.
	There are two techniques for traversing the contents of a list: enumeration and enumeration by name. The Enumerate() method consecutively traverses the list of name/value pairs, using references to the name and value strings as parameters along with an optional argument that specifies whether traversal should begin at the start of the list or resume from the result of the previous call. Enumerate() returns TRUE as long as there are name/value pairs remaining to enumerate.
	The EnumerateName() method differs somewhat from Enumerate(), but is useful in other situations. Instead of accepting references to name and value string objects and returning a boolean result code, EnumerateName() accepts a single argument, an item name, and returns it's value as a string object. To begin at the start of the list, simply pass an empty ("") string as the argument. EnumerateName() will return an empty string once traversal of the list is complete.

Example Use

	#include <stdio.h>
	#include <stdlib.h>
	#include <dcmicro/htmlpp/htmlpp.h>
	int main( void )
	{
	CNVList  list ;
	String   name ;
	String   value ;
	Boolean  good_data ;
	//  store a few pairs in the list
	list( "name1" ) = "value1" ;
	list( "name2" ) = 2 ;
	list( "lastname" ) = "Smith" ;
	list( "firstname" ) = "John" ;
	//  begin list traversal using Enumerate()
	good_data = list.Enumerate( name, value, TRUE ) ;
	while ( good_data )
	{
	cout << name << "  :  " << value << "\n" ;
	//  continue looping with next pair
	good_data = list.Enumerate( name, value ) ;
	}
	cout << "\n\n" ;
	//  Change John's first name to Alex to
	//  illustrate modifying an existing pair
	list( "firstname" ) =  "Alex" ;
	//  This time, use EnumerateName() to traverse list once
	//  again, stopping when an empty string ("") is returned.
	name = "" ;
	while ( (name = s.EnumerateName(name)) != "" )
	{
	//  Lookup the value using () operator
	cout << name << "  :  "
	<< list( name )
	<< "\n" ;
	}
	return 0 ;
	}

Program Output

	name1 : value1
	name2 : 2
	lastname : Smith
	firstname : John
	name1 : value1
	name2 : 2
	lastname : Smith
	firstname : Alex

©1998 DC Micro Development. All rights reserved.
No portion of this document may be c opied or reproduced without expressed written consent.
html++ is a trademark of DC Micro Development.