---
name: "sc_KeyVal"
section: "3"
platform: "linux"
package: "libsc-doc"
version: "2.3.1-22"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/sc_KeyVal"
---

# sc\_KeyVal(3)

The KeyVal class is designed to simplify the process of allowing a user to specify keyword/value associations to a C++ program.

## NAME

sc::KeyVal - The **KeyVal** class is designed to simplify the process of allowing a user to specify keyword/value associations to a C++ program.

## SYNOPSIS

`#include <keyval.h>`

Inherits **sc::RefCount**.

Inherited by **sc::AggregateKeyVal**, **sc::AssignedKeyVal**, **sc::PrefixKeyVal**, and **sc::StringKeyVal**.

### 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.  int **count** (const char \*=0)\
 If the value of a keyword is an array, then return its length.  **Ref**\< **KeyValValue** \> **value** (const char \*=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.  size\_t **sizevalue** (const char \*key=0, const **KeyValValue** &def=**KeyValValuesize**())\
 Returns the size\_t value of key.  char \* **pcharvalue** (const char \*key=0, const **KeyValValue** &def=**KeyValValuepchar**())\
 Returns a copy of the string representation of the key's value.  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**.

**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**())\
 size\_t **sizevalue** (const char \*key, int i, const **KeyValValue** &def=**KeyValValuesize**())\
 char \* **pcharvalue** (const char \*key, int i, const **KeyValValue** &def=**KeyValValuepchar**())\
 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**())\
 size\_t **sizevalue** (int i, const **KeyValValue** &def=**KeyValValuesize**())\
 char \* **pcharvalue** (int i, const **KeyValValue** &def=**KeyValValuepchar**())\
 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**())\
 size\_t **sizevalue** (const char \*key, int, int, const **KeyValValue** &def=**KeyValValuesize**())\
 char \* **pcharvalue** (const char \*key, int, int, const **KeyValValue** &def=**KeyValValuepchar**())\
 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**())\
 size\_t **sizevalue** (int i, int j, const **KeyValValue** &def=**KeyValValuesize**())\
 char \* **pcharvalue** (int i, int j, const **KeyValValue** &def=**KeyValValuepchar**())\
 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,...)\
 size\_t **Va\_sizevalue** (const char \*key, int nindex,...)\
 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.

### 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 size\_t **key\_sizevalue** (const char \*key, const **KeyValValue** &def)\
 Ultimately called by sizevalue.  virtual 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 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

### 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.

### virtual void sc::KeyVal::dump (std::ostream & fp = ExEnv::err0`()`)` [virtual]`

Write a message to fp describing the error.

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

### virtual void sc::KeyVal::errortrace (std::ostream & fp = ExEnv::err0`()`)` [virtual]`

Write a message to fp describing the error.

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

### 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.

### virtual int sc::KeyVal::have\_unseen ()` [virtual]`

Return 1 if there were unseen keywords, 0 if there are none, or -1 this keyval doesn't keep track of unseen keywords.

Reimplemented in **sc::ParsedKeyVal**.

### virtual int sc::KeyVal::key\_exists (const char \*)` [protected]`, ` [pure virtual]`

Ultimately called by exists.

Implemented in **sc::AssignedKeyVal**, **sc::StringKeyVal**, and **sc::AggregateKeyVal**.

### virtual Ref\< KeyValValue \> sc::KeyVal::key\_value (const char \*, const KeyValValue & def)` [protected]`, ` [pure virtual]`

Ultimately called by value.

Implemented in **sc::AssignedKeyVal**, **sc::StringKeyVal**, and **sc::AggregateKeyVal**.

### char \* sc::KeyVal::pcharvalue (const char \* key = `0`, const KeyValValue & def = KeyValValuepchar`()`)

Returns a copy of the string representation of the key's value. Storage for the copy is obtained with new.

### virtual void sc::KeyVal::print\_unseen (std::ostream & fp = ExEnv::out0`()`)` [virtual]`

Print keywords that were never looked at, if possible.

Reimplemented in **sc::ParsedKeyVal**.

## Author

Generated automatically by Doxygen for MPQC from the source code.