Table class for storing and manipulating tabular data. More...

#include <table.hpp>

Classes
struct	Value
	Type for table cell values. More...

Public Types
using	Row = std::unordered_map< std::string, Value >
	Type for a table row (mapping column name to value).

Public Member Functions
	Table ()=default
	Construct an empty table.

const std::vector< Row > &	rows () const
	Get all rows in the table.

const std::set< std::string > &	columns () const
	Get all column names in the table.

void	add_row (const Row &row_data)
	Add a row to the table. Adds "id" and "timestamp" columns automatically.

Table	select_columns (const std::vector< std::string > &selected_columns) const
	Select a subset of columns from the table.

Table	query_rows_not_none (const std::string &column) const
	Query rows where a column is not None.

Table	query_rows_equals (const std::string &column, const Value &value) const
	Query rows where a column equals a value.

Table	query_rows_where (const std::string &column, const std::function< bool(const Value &) > &predicate) const
	Query rows where a column satisfies a predicate.

template<typename RawType >
std::vector< RawType >	column_as_vector (const std::string &column) const
	Returns the values of a column in a vector.

const Table &	print_pretty (std::ostream &os=logroot) const
	Print the table in a pretty formatted style.

const Table &	print_jsonl (std::ostream &os=logroot) const
	Print the table as JSON lines. Each row is a JSON object, one per line.

const Table &	print_csv (std::ostream &os=logroot) const
	Print the table as CSV.

void	clear ()
	Clear all rows and columns from the table.

Static Public Member Functions
static std::string	value_to_string (const Value &v)
	Convert a Value to a string for printing.

static Value	get_value_from_row_or_none (const Row &row, const std::string &col)
	Get a value from a row or return None if missing.

Static Public Attributes
static constexpr int	MAX_STRING_LENGTH = 10000
	Max length of string values (required for safe reading of possibly non-null-terminated char arrays).

Detailed Description

Table class for storing and manipulating tabular data.

Rows are stored as maps from column names to values. Columns are dynamically added as needed. Think: each row is a dict-like type. Columns are essentially keys.

Note: Each row automatically gets an "id" and "timestamp" column.

Provides functionality to add rows, select columns, query data, and print in various formats (pretty, JSON lines, CSV).

Not optimized for performance but designed for ease of use and flexibility. If you need high performance, or millions of rows, consider using a database or specialized library. But still useful for small to medium datasets, logging, prototyping, and data analysis tasks.

Supports various value types, including strings, numbers, booleans, and None (null).

Note: For logging, the convention is that most functions use the key "tag" to add some keyword to the table. To later sort data, therefore add a "tag" to mark where the data comes from.

Example usage:

terra::util::Table table;
 
// Add rows with various data types.
table.add_row({{"name", "Charlie"}, {"age", 28}, {"active", true}});
table.add_row({{"name", "Alice"}, {"age", 30}, {"active", false}});
table.add_row({{"name", "Bob"}, {"age", 25}, {"active", true}});
 
// Add rows with different columns to the same table.
table.add_row({{"city", "Berlin"}, {"country", "Germany"}, {"population", 3769000}});
 
// Select specific columns
auto selected_table = table.select_columns({ "name", "age" });
 
// Query rows where age is greater than 26
auto queried_table = table.query_rows_where( "age", []( const auto& value ) {
    return std::holds_alternative<int>( value ) && std::get<int>( value ) > 26;
});
 
// Print the table in different formats
table.print_pretty();
selected_table.print_jsonl();
queried_table.print_csv();
 
// Print to file
 
// CSV
std::ofstream file("output.csv");
table.print_csv(file);
file.close();
 
// JSON lines
std::ofstream json_file("output.jsonl");
table.print_jsonl(json_file);
json_file.close();
 
// Clear the table
table.clear();

Member Typedef Documentation

◆ Row

using terra::util::Table::Row = std::unordered_map< std::string, Value >

Type for a table row (mapping column name to value).

Constructor & Destructor Documentation

◆ Table()

terra::util::Table::Table ( )

default

Construct an empty table.

Member Function Documentation

◆ add_row()

void terra::util::Table::add_row ( const Row & row_data )

inline

Add a row to the table. Adds "id" and "timestamp" columns automatically.

Parameters

row_data Row data as a map from column name to value.

◆ clear()

void terra::util::Table::clear ( )

inline

Clear all rows and columns from the table.

This resets the table to an empty state - but does not reset the running id counter.

◆ column_as_vector()

template<typename RawType >

std::vector< RawType > terra::util::Table::column_as_vector ( const std::string & column ) const

inline

Returns the values of a column in a vector.

Casts arithmetic values (std::is_arithmetic_v) if the output type is also arithmetic. Skips the row otherwise. Skips rows where there is no entry for that column.

Parameters

column Column name.

Returns: Vector filled with non-empty values of the column with the specified name.

◆ columns()

const std::set< std::string > & terra::util::Table::columns ( ) const

inline

Get all column names in the table.

Returns: Set of column names.

◆ get_value_from_row_or_none()

static Value terra::util::Table::get_value_from_row_or_none	(	const Row &	row,
		const std::string &	col
	)

inlinestatic

Get a value from a row or return None if missing.

Parameters

row	Row to search.
col	Column name.

Returns: Value or None.

◆ print_csv()

const Table & terra::util::Table::print_csv ( std::ostream & os = logroot ) const

inline

Print the table as CSV.

Parameters

os	Output stream (default util::logroot).

Returns: Reference to this table.

◆ print_jsonl()

const Table & terra::util::Table::print_jsonl ( std::ostream & os = logroot ) const

inline

Print the table as JSON lines. Each row is a JSON object, one per line.

Example output: {"id":1,"timestamp":"2024-06-10 12:34:56","name":"Alice","age":30} {"id":2,"timestamp":"2024-06-10 12:34:57","name":"Bob","age":25}

To parse with pandas: import pandas as pd df = pd.read_json("yourfile.jsonl", lines=True)

Parameters

os	Output stream (default util::logroot).

Returns: Reference to this table.

◆ print_pretty()

const Table & terra::util::Table::print_pretty ( std::ostream & os = logroot ) const

inline

Print the table in a pretty formatted style.

Parameters

os	Output stream (default util::logroot).

Returns: Reference to this table.

◆ query_rows_equals()

Table terra::util::Table::query_rows_equals	(	const std::string &	column,
		const Value &	value
	)		const

inline

Query rows where a column equals a value.

Parameters

column	Column name.
value	Value to compare.

Returns: New Table with matching rows.

◆ query_rows_not_none()

Table terra::util::Table::query_rows_not_none ( const std::string & column ) const

inline

Query rows where a column is not None.

Parameters

column Column name.

Returns: New Table with matching rows.

◆ query_rows_where()

Table terra::util::Table::query_rows_where	(	const std::string &	column,
		const std::function< bool(const Value &) > &	predicate
	)		const

inline

Query rows where a column satisfies a predicate.

Parameters

column	Column name.
predicate	Predicate function.

Returns: New Table with matching rows.

◆ rows()

const std::vector< Row > & terra::util::Table::rows ( ) const

inline

Get all rows in the table.

Returns: Vector of rows.

◆ select_columns()

Table terra::util::Table::select_columns ( const std::vector< std::string > & selected_columns ) const

inline

Select a subset of columns from the table.

Parameters

selected_columns Columns to select.

Returns: New Table with only selected columns.

◆ value_to_string()

static std::string terra::util::Table::value_to_string ( const Value & v )

inlinestatic

Convert a Value to a string for printing.

Parameters

v	Value to convert.

Returns: String representation.

Member Data Documentation

◆ MAX_STRING_LENGTH

constexpr int terra::util::Table::MAX_STRING_LENGTH = 10000

staticconstexpr

Max length of string values (required for safe reading of possibly non-null-terminated char arrays).

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

table.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ Row

Constructor & Destructor Documentation

◆ Table()

Member Function Documentation

◆ add_row()

◆ clear()

◆ column_as_vector()

◆ columns()

◆ get_value_from_row_or_none()

◆ print_csv()

◆ print_jsonl()

◆ print_pretty()

◆ query_rows_equals()

◆ query_rows_not_none()

◆ query_rows_where()

◆ rows()

◆ select_columns()

◆ value_to_string()

Member Data Documentation

◆ MAX_STRING_LENGTH