Tabular-C++ Guide - Interacting with Tables

Introduction Getting Started More About Table Construction Interacting With Tables Inline Tables

Tabular-C++: Overview and Guide

Matthew Smith

Interacting with Tables

Once our table has been constructed, we would very much like to do stuff with it. The basic operations that can be performed on a table are:

Adding and removing rows
Reading and updating table elements
Looking up key values for a given field value

All of these operations are of course supported by Tabular-C++, as well as some other useful operations.

Adding and Removing Rows

Adding a row is done by a table's member method,

table.add(elements)

This function will return the key value associated with the row, which should remain constant throughout the row's life. For this reason, the user is recommended to not update the field nominated as a manual key.

Removing a row requires knowledge of its associated key, or label (see below). The syntax is,

table.remove(keyval)

table.removeByLabel(label)

To remove all rows,

table.clear()

Reading and Updating Elements

Reading an element by key value is done via a field's get method,

table.field.get(keyval)

If a table row has been labeled (see below), then we may also use,

table.field.get(label)

Setting the element is done with,

table.field.set(keyval, fieldval)

If you need to read or write by row index (the vertical position of a row), you can simply manipulate the object table.field[index], since table fields extend std::vector.

Labelling Rows

Sometimes it is convenient to give a label to a row, to help facilitate access in different locations in code. To associate a label with a key value,

table.makeLabel(keyval, label)

Labels are implemented as a std::map named table.labels, from std::string to the key datatype.

Getting Relevant Key Values

One thing we might want to do, is get the key value for which a field takes on a particular value. To find the first such key,

table.field.findFirst(fieldval)

To get a vector of all such keys,

table.field.findAll(fieldval)

To get a std::map taking field values onto some subset (std::vector) of key values,

table.field.createKeyMap(keyrange)

Storing Arbitary Values at Runtime

Sometimes, for the sake of convenience or performance, it is useful to store complex data related to a table at runtime. For this purpose, each table can hold arbitary data via use of void*. This is made easy for the user by a set of functions,

table.createVal<valtype>(name, val)
table.setVal<valtype>(name, val)
table.getVal<valtype>(name)
table.destroyVal(name)