sc::KeyVal Class Reference

#include <util/keyval/keyval.h>

Inheritance diagram for sc::KeyVal:

Public Types
enum	{ MaxKeywordLength = 256 }
enum	KeyValError {   OK, HasNoValue, WrongType, UnknownKeyword,   OperationFailed }

Public Member Functions
int	exists (const char *)
	This takes as its only argument a keyword. More...
int	count (const char *=0)
	If the value of a keyword is an array, then return its length. More...
Ref< KeyValValue >	value (const char *key=0, const KeyValValue &def=KeyValValue())
	Return the value associated with the keyword.
int	booleanvalue (const char *key=0, const KeyValValue &def=KeyValValueboolean())
	Returns the boolean value (0 = false, 1 = true) of key.
double	doublevalue (const char *key=0, const KeyValValue &def=KeyValValuedouble())
	Returns the double value of key.
float	floatvalue (const char *key=0, const KeyValValue &def=KeyValValuefloat())
	Returns the float value of key.
char	charvalue (const char *key=0, const KeyValValue &def=KeyValValuechar())
	Returns the char value of key.
int	intvalue (const char *key=0, const KeyValValue &def=KeyValValueint())
	Returns the int value of key.
long	longvalue (const char *key=0, const KeyValValue &def=KeyValValuelong())
	Returns the long value of key.
size_t	sizevalue (const char *key=0, const KeyValValue &def=KeyValValuesize())
	Returns the size_t value of key.
DEPRECATED char *	pcharvalue (const char *key=0, const KeyValValue &def=KeyValValuestring())
	Returns a copy of the string representation of the key's value. More...
std::string	stringvalue (const char *key=0, const KeyValValue &def=KeyValValuestring())
	Returns a string representation of the key's value.
Ref< DescribedClass >	describedclassvalue (const char *key=0, const KeyValValue &def=KeyValValueRefDescribedClass())
	Returns a reference to an object of type DescribedClass.
virtual const char *	classname (const char *)
	Returns the name of the exact class of the object at the keyword. More...
virtual Ref< DescribedClass >	describedclass (const char *classname)
	Returns a reference to an object of type DescribedClass using the top level keywords of this KeyVal. More...
Reading Vectors.
These members correspond to the above members, but take an additional integer argument, i, which is a vector index. This is equivalent to getting a value for a keyword named "<i>key</i>:<i>i</i>". The routines that do not take key arguments get the value for the keyword named "<i>i</i>".
int	exists (const char *key, int i)
int	count (const char *key, int i)
int	booleanvalue (const char *key, int i, const KeyValValue &def=KeyValValueboolean())
double	doublevalue (const char *key, int i, const KeyValValue &def=KeyValValuedouble())
float	floatvalue (const char *key, int i, const KeyValValue &def=KeyValValuefloat())
char	charvalue (const char *key, int i, const KeyValValue &def=KeyValValuechar())
int	intvalue (const char *key, int i, const KeyValValue &def=KeyValValueint())
long	longvalue (const char *key, int i, const KeyValValue &def=KeyValValuelong())
size_t	sizevalue (const char *key, int i, const KeyValValue &def=KeyValValuesize())
DEPRECATED char *	pcharvalue (const char *key, int i, const KeyValValue &def=KeyValValuestring())
std::string	stringvalue (const char *key, int i, const KeyValValue &def=KeyValValuestring())
Ref< DescribedClass >	describedclassvalue (const char *key, int, const KeyValValue &def=KeyValValueRefDescribedClass())
int	exists (int i)
int	count (int i)
int	booleanvalue (int i, const KeyValValue &def=KeyValValueboolean())
double	doublevalue (int i, const KeyValValue &def=KeyValValuedouble())
float	floatvalue (int i, const KeyValValue &def=KeyValValuefloat())
char	charvalue (int i, const KeyValValue &def=KeyValValuechar())
int	intvalue (int i, const KeyValValue &def=KeyValValueint())
long	longvalue (int i, const KeyValValue &def=KeyValValuelong())
size_t	sizevalue (int i, const KeyValValue &def=KeyValValuesize())
DEPRECATED char *	pcharvalue (int i, const KeyValValue &def=KeyValValuestring())
std::string	stringvalue (int i, const KeyValValue &def=KeyValValuestring())
Ref< DescribedClass >	describedclassvalue (int i, const KeyValValue &def=KeyValValueRefDescribedClass())
Reading 2D Arrays.
These members correspond to the above members, but take additional integer arguments, i and j, which is an array index. This is equivalent to getting a value for a keyword named "<i>key</i>:<i>i</i>:<i>j</i>". The routines that do not take key arguments get the value for the keyword named "<i>i</i>:<i>j</i>".
int	exists (const char *, int, int)
int	count (const char *, int, int)
int	booleanvalue (const char *, int, int, const KeyValValue &def=KeyValValueboolean())
double	doublevalue (const char *key, int, int, const KeyValValue &def=KeyValValuedouble())
float	floatvalue (const char *key, int, int, const KeyValValue &def=KeyValValuefloat())
char	charvalue (const char *key, int, int, const KeyValValue &def=KeyValValuechar())
int	intvalue (const char *key, int, int, const KeyValValue &def=KeyValValueint())
long	longvalue (const char *key, int, int, const KeyValValue &def=KeyValValuelong())
size_t	sizevalue (const char *key, int, int, const KeyValValue &def=KeyValValuesize())
DEPRECATED char *	pcharvalue (const char *key, int, int, const KeyValValue &def=KeyValValuestring())
std::string	stringvalue (const char *key, int, int, const KeyValValue &def=KeyValValuestring())
Ref< DescribedClass >	describedclassvalue (const char *key, int, int, const KeyValValue &def=KeyValValueRefDescribedClass())
int	exists (int i, int j)
int	count (int i, int j)
int	booleanvalue (int i, int j, const KeyValValue &def=KeyValValueboolean())
double	doublevalue (int i, int j, const KeyValValue &def=KeyValValuedouble())
float	floatvalue (int i, int j, const KeyValValue &def=KeyValValuefloat())
char	charvalue (int i, int j, const KeyValValue &def=KeyValValuechar())
int	intvalue (int i, int j, const KeyValValue &def=KeyValValueint())
long	longvalue (int i, int j, const KeyValValue &def=KeyValValuelong())
size_t	sizevalue (int i, int j, const KeyValValue &def=KeyValValuesize())
DEPRECATED char *	pcharvalue (int i, int j, const KeyValValue &def=KeyValValuestring())
std::string	stringvalue (int i, int j, const KeyValValue &def=KeyValValuestring())
Ref< DescribedClass >	describedclassvalue (int i, int j, const KeyValValue &def=KeyValValueRefDescribedClass())
Reading 3D Arrays.
These members correspond to the above members, but can be used to read in arrays with more than two dimensions. The nindex argument is the number of indices in the array. It is followed by an int giving the value of each index.
int	Va_exists (const char *key, int nindex,...)
int	Va_count (const char *key, int nindex,...)
int	Va_booleanvalue (const char *key, int nindex,...)
double	Va_doublevalue (const char *key, int nindex,...)
float	Va_floatvalue (const char *key, int nindex,...)
char	Va_charvalue (const char *key, int nindex,...)
int	Va_intvalue (const char *key, int nindex,...)
long	Va_longvalue (const char *key, int nindex,...)
size_t	Va_sizevalue (const char *key, int nindex,...)
DEPRECATED char *	Va_pcharvalue (const char *key, int nindex,...)
std::string	Va_stringvalue (const char *key, int nindex,...)
Ref< DescribedClass >	Va_describedclassvalue (const char *key, int nindex,...)
KeyValError	error ()
	Return the current error condition.
const char *	errormsg (KeyValError err)
	Return a textual representation of err.
const char *	errormsg ()
	Return a textual representation of the current error.
virtual void	errortrace (std::ostream &fp=ExEnv::err0())
	Write a message to fp describing the error.
virtual void	dump (std::ostream &fp=ExEnv::err0())
	Write a message to fp describing the error.
virtual void	print_unseen (std::ostream &fp=ExEnv::out0())
	Print keywords that were never looked at, if possible.
virtual int	have_unseen ()
	Return 1 if there were unseen keywords, 0 if there are none, or -1 this keyval doesn't keep track of unseen keywords.
void	verbose (int v)
	Control printing of assignments.
int	verbose () const
	Returns nonzero if assignments are printed.
Public Member Functions inherited from sc::RefCount
size_t	identifier () const
	Return the unique identifier for this object that can be compared for different objects of different types. More...
int	lock_ptr () const
	Lock this object.
int	unlock_ptr () const
	Unlock this object.
void	use_locks (bool inVal)
	start and stop using locks on this object
refcount_t	nreference () const
	Return the reference count.
refcount_t	reference ()
	Increment the reference count and return the new count.
refcount_t	dereference ()
	Decrement the reference count and return the new count.
int	managed () const
void	unmanage ()
	Turn off the reference counting mechanism for this object. More...

Protected Member Functions
void	seterror (KeyValError err)
	Set the current error condition.
void	seterror (KeyValValue::KeyValValueError err)
	Set the current error condition.
virtual int	key_exists (const char *)=0
	Ultimately called by exists.
virtual int	key_count (const char *=0)
	Ultimately called by count.
virtual Ref< KeyValValue >	key_value (const char *, const KeyValValue &def)=0
	Ultimately called by value.
virtual int	key_booleanvalue (const char *, const KeyValValue &def)
	Ultimately called by booleanvalue.
virtual double	key_doublevalue (const char *key, const KeyValValue &def)
	Ultimately called by doublevalue.
virtual float	key_floatvalue (const char *key, const KeyValValue &def)
	Ultimately called by floatvalue.
virtual char	key_charvalue (const char *key, const KeyValValue &def)
	Ultimately called by charvalue.
virtual int	key_intvalue (const char *key, const KeyValValue &def)
	Ultimately called by intvalue.
virtual long	key_longvalue (const char *key, const KeyValValue &def)
	Ultimately called by longvalue.
virtual size_t	key_sizevalue (const char *key, const KeyValValue &def)
	Ultimately called by sizevalue.
virtual DEPRECATED char *	key_pcharvalue (const char *key, const KeyValValue &def)
	Ultimately called by pcharvalue.
virtual std::string	key_stringvalue (const char *key, const KeyValValue &def)
	Ultimately called by stringvalue.
virtual Ref< DescribedClass >	key_describedclassvalue (const char *key, const KeyValValue &def)
	Ultimately called by describedclassvalue.
Protected Member Functions inherited from sc::RefCount
	RefCount (const RefCount &)
RefCount &	operator= (const RefCount &)

Protected Attributes
int	verbose_

Friends
class	AggregateKeyVal
class	PrefixKeyVal

Detailed Description

The KeyVal class is designed to simplify the process of allowing a user to specify keyword/value associations to a C++ program. A flexible input style and ease of use for the programmer is achieved with this method. Keywords are represented by null terminated character arrays. The keywords are organized hierarchially, in a manner similar to the way that many file systems are organized. One character is special, ":", which is used to separate the various hierarchial labels, which are referred to as "segments", in the keyword.

A convention for specifying arrays is provided by KeyVal. Each index of the array is given by appending a segment containing the character representation of the index. Thus, "array:3:4" would be a the keyword corresponding to fourth row and fifth column of "array", since indexing starts at zero.

To allow the KeyVal class to have associations that can represent data for classes, the keyword can be associated with a class as well as a value. This permits polymorphic data to be unambiguously represented by keyword/value associations. Most use of KeyVal need not be concerned with this.

Member Function Documentation

classname()

virtual const char* sc::KeyVal::classname ( const char *  )

virtual

Returns the name of the exact class of the object at the keyword.

If no classname is assigned, or this KeyVal does not support classes, then 0 is returned.

Reimplemented in sc::ParsedKeyVal, sc::PrefixKeyVal, sc::AggregateKeyVal, sc::StringKeyVal, and sc::AssignedKeyVal.

count()

int sc::KeyVal::count

(

const char *

= 0

)

If the value of a keyword is an array, then return its length.

If no arguments are given then the top level will be checked to see if it is an array and, if so, the number of elements will be counted.

describedclass()

virtual Ref<DescribedClass> sc::KeyVal::describedclass ( const char *  classname )

virtual

Returns a reference to an object of type DescribedClass using the top level keywords of this KeyVal.

Parameters

[in]

classname

specifies the class name, must be derived from DescribedClass

Returns

Ref<> to the object, null if constructor not successful

exists()

int sc::KeyVal::exists

(

const char *

)

This takes as its only argument a keyword.

Returns 1 if the keyword has a value and 0 otherwise.

pcharvalue()

DEPRECATED char* sc::KeyVal::pcharvalue	(	const char *	key = 0,
		const KeyValValue &	def = KeyValValuestring()
	)

Returns a copy of the string representation of the key's value.

Storage for the copy is obtained with new. This is deprecated–use stringvalue instead.

---

The documentation for this class was generated from the following file:

• src/lib/util/keyval/keyval.h