// join_tables — Pure multi-key hash join between two tables.
// Promoted from cpp/apps/primitives_gallery/playground/tables/ (issue 0081-E).
// No ImGui, no I/O. Depends only on data_table_types.h.
#pragma once

#include "core/data_table_types.h"
#include <string>
#include <vector>

namespace data_table {

// join_tables — Pure: applies one Join spec over a left table and a TableInput right.
//
// Strategy:
//   Inner — only rows with at least one matching key in both sides.
//   Left  — all left rows; unmatched left rows get empty right cells.
//   Right — all right rows; unmatched right rows get empty left cells.
//   Full  — union of left and right: unmatched rows from both sides included.
//
// Multi-key: jn.on is a list of {left_col, right_col} pairs; all pairs must
// match for a row to be considered a hit (AND semantics). Missing key columns
// (name not found in headers) produce an empty string for that key component.
//
// Key duplicates: produces Cartesian product for matching rows. Each (left_i,
// right_j) pair where both keys match becomes a separate output row.
//
// Output columns: all left columns, then the right columns listed in jn.fields
// (or all right columns if jn.fields is empty). Right column names are prefixed
// with "jn.alias." when jn.alias is non-empty.
//
// Returns a StageOutput owning its cell_backing and cells pointer list.
StageOutput join_tables(const char* const* left_cells, int left_rows, int left_cols,
                        const std::vector<std::string>& left_headers,
                        const std::vector<ColumnType>&  left_types,
                        const TableInput& right,
                        const Join& jn);

} // namespace data_table
