Bank & Structure¶

hipo::structure¶

Base class for binary data structures with an 8-byte header. Users rarely interact with it directly.

Binary Layout¶

---
title: "hipo::structure — 8-byte header (64 bits)"
---
packet-beta
0-15: "group (uint16)"
16-23: "item (u8)"
24-31: "type (u8)"
32-55: "totalSize (24 bits)"
56-63: "headerLength (8 bits)"

Byte	Size	Field	Type	Description
0	2	`group`	`uint16`	Bank group ID
2	1	`item`	`uint8`	Bank item ID
3	1	`type`	`uint8`	Data type code
4	4	`sizeWord`	`uint32`	bits `[0:23]` = `totalSize`, bits `[24:31]` = `headerLength`
8	N	`data`	bytes	Variable-length payload, column-major (Structure-of-Arrays)

The 8-byte header is followed immediately by the data payload — there is no padding.
All get*At() / put*At() accessors take an offset into the data payload, i.e. relative to byte 8 of the structure.

Key Methods¶

int getSize();        // total size (lower 24 bits of sizeWord)
int getType();        // data type
int getGroup();       // bank group ID
int getItem();        // bank item ID

// Raw typed access at byte offset within data region
int      getIntAt(int index);
float    getFloatAt(int index);
int16_t  getShortAt(int index);
double   getDoubleAt(int index);
int64_t  getLongAt(int index);
int8_t   getByteAt(int index);

void putIntAt(int index, int value);
void putFloatAt(int index, float value);
// ... etc

hipo::bank¶

Schema-based tabular data container -- the primary user-facing class for accessing physics data.

Construction¶

bank();
bank(const schema& s);            // empty bank (rows set on read)
bank(const schema& s, int rows);  // bank with pre-allocated rows

Metadata¶

schema& getSchema();
int     getRows();
void    setRows(int rows);
void    reset();

Typed Getters (by column name)¶

int    getInt(const char *name, int row);
int    getShort(const char *name, int row);
int    getByte(const char *name, int row);
float  getFloat(const char *name, int row);
double getDouble(const char *name, int row);
long   getLong(const char *name, int row);

Typed Getters (by column index)¶

int    getInt(int item, int row);
int    getShort(int item, int row);
int    getByte(int item, int row);
float  getFloat(int item, int row);
double getDouble(int item, int row);
long   getLong(int item, int row);

Performance

Column access by index is faster than by name (avoids map lookup). Cache the column index for hot loops:

int pidCol = schema.getEntryOrder("pid");
for (int row = 0; row < bank.getRows(); row++) {
    int pid = bank.getInt(pidCol, row);
}

Column Vector Extraction¶

Get all values for a column as a vector:

std::vector<int>    getInt(int item);
std::vector<int>    getInt(const char *name);
std::vector<float>  getFloat(int item);
std::vector<float>  getFloat(const char *name);
std::vector<double> getDouble(int item);
std::vector<double> getDouble(const char *name);

Generic Template Access¶

template<typename T> T get(int item, int row);
template<typename T> T get(const char *name, int row);

Typed Setters¶

// By name
void putInt(const char *name, int row, int32_t value);
void putShort(const char *name, int row, int16_t value);
void putByte(const char *name, int row, int8_t value);
void putFloat(const char *name, int row, float value);
void putDouble(const char *name, int row, double value);
void putLong(const char *name, int row, int64_t value);

// By index
void putInt(int item, int row, int32_t value);
void putShort(int item, int row, int16_t value);
// ... etc

Generic Template Setter¶

template<typename T> void put(const char *name, int row, T value);
template<typename T> void put(int item, int row, T value);

Row List Operations¶

rowlist::list_t const& getRowList();           // current (possibly filtered) rows
rowlist::list_t const  getFullRowList();        // always all rows
rowlist&               getMutableRowList();     // for filtering
rowlist::list_t const  getRowListLinked(int row, int column);

Display¶

void show();
void show(bool showAllRows);

Important Behaviors¶

getInt() auto-promotes: if the column is kByte or kShort, it still returns int
getDouble() auto-promotes from kFloat
Banks are reused across events -- event.read(bank) overwrites data in-place

`hipo::bank::rowlist`¶

Enables row filtering and iteration on a bank.

void reset(int numRows = -1);           // reset to full row list
rowlist::list_t const& getList();       // get current list
void setList(list_t const& list);       // manually set row indices

// Filter by lambda
void filter(std::function<bool(bank&, int)> func);

// Filter by expression string
void filter(char const* expression);

// Filter with pre-constructed Parser (avoids re-parsing)
void filter(Parser& parser);

// Create a list [0, 1, 2, ..., num-1]
static list_t createFullList(int num);

Example¶

// Lambda filter
auto& rl = bank.getMutableRowList();
rl.filter([](hipo::bank& b, int row) {
    return b.getInt("charge", row) != 0;
});

// Expression filter
rl.filter("charge!=0");

// Iterate filtered rows
for (auto row : bank.getRowList()) {
    int pid = bank.getInt("pid", row);
}

hipo::composite¶

Unformatted composite bank (type=10) for ad-hoc structured data without a dictionary schema.

composite();
composite(int group, int item, const char *format, int capacity);

void parse(std::string format);
int  getRows();
int  getEntries();

int     getInt(int element, int row);
int64_t getLong(int element, int row);
float   getFloat(int element, int row);

void putInt(int element, int row, int value);
void putLong(int element, int row, int64_t value);
void putFloat(int element, int row, float value);

void print();
void reset();

hipo::banklist¶

using banklist = std::vector<bank>;

// Get index of a named bank within a banklist
banklist::size_type getBanklistIndex(banklist& banks, std::string const& bankName);