MCPcopy Create free account
hub / github.com/p-ranav/tabulate

github.com/p-ranav/tabulate

Chat with this repo
repository ↗ · DeepWiki ↗ · release v2.1 ↗ · + Follow · compare 3 versions
956 symbols 1,698 edges 76 files 89 documented · 9% ● updated 18mo agov1.5 · 2023-02-20★ 2,17837 open issues

Browse by type

⨍ Functions 593◇ Types & classes 363
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

ci status standard license version

Source for the above image can be found here

Table of Contents

Quick Start

tabulate is a header-only library. Just add include/ to your include_directories and you should be good to go. A single header file version is also available in single_include/.

NOTE Tabulate supports >=C++11. The rest of this README, however, assumes C++17 support.

Create a Table object and call Table.add_rows to add rows to your table.

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {

  Table universal_constants;

  universal_constants.add_row({"Quantity", "Value"});
  universal_constants.add_row({"Characteristic impedance of vacuum", "376.730 313 461... Ω"});
  universal_constants.add_row({"Electric constant (permittivity of free space)", "8.854 187 817... × 10⁻¹²F·m⁻¹"});
  universal_constants.add_row({"Magnetic constant (permeability of free space)", "4π × 10⁻⁷ N·A⁻² = 1.2566 370 614... × 10⁻⁶ N·A⁻²"});
  universal_constants.add_row({"Gravitational constant (Newtonian constant of gravitation)", "6.6742(10) × 10⁻¹¹m³·kg⁻¹·s⁻²"});
  universal_constants.add_row({"Planck's constant", "6.626 0693(11) × 10⁻³⁴ J·s"});
  universal_constants.add_row({"Dirac's constant", "1.054 571 68(18) × 10⁻³⁴ J·s"});
  universal_constants.add_row({"Speed of light in vacuum", "299 792 458 m·s⁻¹"});

Use RowStream to format table data with stream insertion.

  employees.add_row({"Emp. ID", "First Name", "Last Name", "Department / Business Unit", "Pay Rate"});
  employees.add_row(RowStream{} << 101 << "Donald" << "Patrick" << "Finance" << 59.6154);
  employees.add_row(RowStream{} << 102 << "Rachel" << "Williams" << "Marketing and Operational\nLogistics Planning" << 34.9707);
  employees.add_row(RowStream{} << 103 << "Ian" << "Jacob" << department << 57.0048);

You can format this table using Table.format() which returns a Format object. Using a fluent interface, format properties of the table, e.g., borders, font styles, colors etc.

  universal_constants.format()
    .font_style({FontStyle::bold})
    .border_top(" ")
    .border_bottom(" ")
    .border_left(" ")
    .border_right(" ")
    .corner(" ");

You can access rows in the table using Table[row_index]. This will return a Row object on which you can similarly call Row.format() to format properties of all the cells in that row.

Now, let's format the header of the table. The following code changes the font background of the header row to red, aligns the cell contents to center and applies a padding to the top and bottom of the row.

  universal_constants[0].format()
    .padding_top(1)
    .padding_bottom(1)
    .font_align(FontAlign::center)
    .font_style({FontStyle::underline})
    .font_background_color(Color::red);

Calling Table.column(index) will return a Column object. Similar to rows, you can use Column.format() to format all the cells in that column.

Now, let's change the font color of the second column to yellow:

  universal_constants.column(1).format()
    .font_color(Color::yellow);

You can access cells by indexing twice from a table: From a row using Table[row_index][col_index] or from a column using Table.column(col_index)[cell_index]. Just like rows, columns, and tables, you can use Cell.format() to format individual cells

  universal_constants[0][1].format()
    .font_background_color(Color::blue)
    .font_color(Color::white);
}

Print the table using the stream operator<< like so:

  std::cout << universal_constants << std::endl;

You could also use Table.print(stream) to print the table, e.g., universal_constants.print(std::cout).

Table Size and Shape

Table.size() returns the number of rows, and Table.dimensions() returns {rows, columns} actually added to the table:

Table table;
table.add_row({"cell"});
auto [rows, cols] = table.dimensions(); // {1, 1}

NOTE: Table.shape() is a different, unrelated measurement: it renders the table and returns {character width, line count} of that rendered text, not row/column counts. It exists for callers who need to know how much terminal space a printed table will occupy (e.g. for a single-cell table, shape() returns the width/height of its printed box, not {1, 1}).

Formatting Options

Style Inheritance Model

Formatting in tabulate follows a simple style-inheritance model. When rendering each cell: 1. Apply cell formatting if specified 2. If no cell formatting is specified, apply its parent row formatting 3. If no row formatting is specified, apply its parent table formatting 4. If no table formatting is specified, apply the default table formatting

This enables overriding the formatting for a particular cell even though row or table formatting is specified, e.g., when an entire row is colored yellow but you want a specific cell to be colored red.

Word Wrapping

tabulate supports automatic word-wrapping when printing cells.

Although word-wrapping is automatic, there is a simple override. Automatic word-wrapping is used only if the cell contents do not have any embedded newline \n characters. So, you can embed newline characters in the cell contents and enforce the word-wrapping manually.

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {
  Table table;

  table.add_row({"This paragraph contains a veryveryveryveryveryverylong word. The long word will "
                 "break and word wrap to the next line.",
                 "This paragraph \nhas embedded '\\n' \ncharacters and\n will break\n exactly "
                 "where\n you want it\n to\n break."});

  table[0][0].format().width(20);
  table[0][1].format().width(50);

  std::cout << table << std::endl;
}
  • The above table has 1 row and 2 columns.
  • The first cell has automatic word-wrapping.
  • The second cell uses the embedded newline characters in the cell contents - even though the second column has plenty of space (50 characters width), it uses user-provided newline characters to break into new lines and enforce the cell style.
  • NOTE: Whether word-wrapping is automatic or not, tabulate performs a trim operation on each line of each cell to remove whitespace characters from either side of line.

NOTE: Both columns in the above table are left-aligned by default. This, however, can be easily changed.

Font Alignment

tabulate supports three font alignment settings: left, center, and right. By default, all table content is left-aligned. To align cells, use .format().font_align(alignment).

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {
  Table movies;
  movies.add_row({"S/N", "Movie Name", "Director", "Estimated Budget", "Release Date"});
  movies.add_row({"tt1979376", "Toy Story 4", "Josh Cooley", "$200,000,000", "21 June 2019"});
  movies.add_row({"tt3263904", "Sully", "Clint Eastwood", "$60,000,000", "9 September 2016"});
  movies.add_row({"tt1535109", "Captain Phillips", "Paul Greengrass", "$55,000,000", " 11 October 2013"});

  // center align 'Director' column
  movies.column(2).format()
    .font_align(FontAlign::center);

  // right align 'Estimated Budget' column
  movies.column(3).format()
    .font_align(FontAlign::right);

  // right align 'Release Date' column
  movies.column(4).format()
    .font_align(FontAlign::right);

  // center-align and color header cells
  for (size_t i = 0; i < 5; ++i) {
    movies[0][i].format()
      .font_color(Color::yellow)
      .font_align(FontAlign::center)
      .font_style({FontStyle::bold});
  }

  std::cout << movies << std::endl;
}

Font Styles

tabulate supports 8 font styles: bold, dark, italic, underline, blink, reverse, concealed, crossed. Depending on the terminal (or terminal settings), some of these might not work.

To apply a font style, simply call .format().font_style({...}). The font_style method takes a vector of font styles. This allows to apply multiple font styles to a cell, e.g., bold and italic.

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {
  Table styled_table;
  styled_table.add_row({"Bold", "Italic", "Bold & Italic", "Blinking"});
  styled_table.add_row({"Underline", "Crossed", "Dark", "Bold, Italic & Underlined"});

  styled_table[0][0].format()
    .font_style({FontStyle::bold});

  styled_table[0][1].format()
    .font_style({FontStyle::italic});

  styled_table[0][2].format()
    .font_style({FontStyle::bold, FontStyle::italic});

  styled_table[0][3].format()
    .font_style({FontStyle::blink});

  styled_table[1][0].format()
    .font_style({FontStyle::underline});

  styled_table[1][1].format()
    .font_style({FontStyle::crossed});

  styled_table[1][2].format()
    .font_style({FontStyle::dark});


  styled_table[1][3].format()
    .font_style({FontStyle::bold, FontStyle::italic, FontStyle::underline});

  std::cout << styled_table << std::endl;

}

NOTE: Font styles are applied to the entire cell. Unlike HTML, you cannot currently apply styles to specific words in a cell.

Cell Colors

There are a number of methods in the Format object to color cells - foreground and background - for font, borders, corners, and column separators. Thanks to termcolor, tabulate supports 8 colors: grey, red, green, yellow, blue, magenta, cyan, and white. The look of these colors vary depending on your terminal.

For font, border, and corners, you can call .format().<element>_color(value) to set the foreground color and .format().<element>_background_color(value) to set the background color. Here's an example:

#include <tabulate/table.hpp>
using namespace tabulate;

int main() {
  Table colors;

  colors.add_row({"Font Color is Red", "Font Color is Blue", "Font Color is Green"});
  colors.add_row({"Everything is Red", "Everything is Blue", "Everything is Green"});
  colors.add_row({"Font Background is Red", "Font Background is Blue", "Font Background is Green"});

  colors[0][0].format()
    .font_color(Color::red)
    .font_style({FontStyle::bold});
  colors[0][1].format()
    .font_color(Color::blue)
    .font_style({FontStyle::bold});
  colors[0][2].format()
    .font_color(Color::green)
    .font_style({FontStyle::bold});

  colors[1][0].format()
    .border_left_color(Color::red)
    .border_left_background_color(Color::red)
    .font_background_color(Color::red)
    .font_color(Color::red);

  colors[1][1].format()
    .border_left_color(Color::blue)
    .border_left_background_color(Color::blue)
    .font_background_color(Color::blue)
    .font_color(Color::blue);

  colors[1][2].format()
    .border_left_color(Color::green)
    .border_left_background_color(Color::green)
    .font_background_color(Color::green)
    .font_color(Color::green)
    .border_right_color(Color::green)
    .border_right_background_color(Color::green);

  colors[2][0].format()
    .font_background_color(Color::red)
    .font_style({FontStyle::bold});
  colors[2][1].format()
    .font_background_color(Color::blue)
    .font_style({FontStyle::bold});
  colors[2][2].format()
    .font_background_color(Color::green)
    .font_style({FontStyle::bold});

  std::cout << colors << std::endl;
}

Borders and Corners

tabulate allows for fine control over borders and corners. For each border and corner, you can set the text, color, and background color.

NOTE: You can use .corner(..), .corner_color(..), and .corner_background_color(..) to set a common style for all corners. Similarly, you can use .border(..), .border_color(..) and .border_background_color(..) to set a common style for all borders.

NOTE: Note the use of `.format().multi_byte_

Core symbols most depended-on inside this repo

browse all functions →

Shape

Method 414
Class 287
Function 179
Enum 76

Languages

C++99%
Python1%

Modules by API surface

single_include/tabulate/tabulate.hpp421 symbols
include/tabulate/variant_lite.hpp195 symbols
include/tabulate/optional_lite.hpp56 symbols
include/tabulate/string_view_lite.hpp51 symbols
include/tabulate/table.hpp31 symbols
include/tabulate/table_internal.hpp19 symbols
include/tabulate/row.hpp16 symbols
include/tabulate/column.hpp16 symbols
utils/amalgamate/amalgamate.py14 symbols
include/tabulate/format.hpp14 symbols
samples/benchmark.cpp12 symbols
include/tabulate/printer.hpp9 symbols

For agents

$ claude mcp add tabulate \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page