3rd-party/libfort
1
0
Fork 0
Code Releases Activity

[A] Added tutorial from github wiki to repository

Browse Source
This commit is contained in:
seleznevae 2020-01-30 19:11:36 +03:00
parent 77ad49daeb
commit 0430da4163
12 changed files with 1246 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog.md
View File

@ -12,6 +12,10 @@
- Refactoring of code that uses vectors.
### Docs
- Add tutorial from github wiki to repository.
## v0.3.2
### Bug fixes

2
README.md
View File

@ -40,7 +40,7 @@ For C++ projects that use compiler with C++11 support (and later) there are also
```
## Documentation
See guide on [wiki](https://github.com/seleznevae/libfort/wiki) of the project and doxygen [API documentation](http://seleznevae.github.io/libfort).
See guide in [tutorial](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/Tutorial.md) of the library and doxygen [API documentation](http://seleznevae.github.io/libfort).
## Getting Started

257
docs/tutorial/CPP_API/Border-styles.md Normal file
View File

@ -0,0 +1,257 @@
**libfort** has a number of builtin border styles.
To change border style of **libfort** tables one can use `set_default_border_style`, `set_border_style` functions:
```C++
/* Change border style of all libfort tables that will be created */
bool set_default_border_style(struct ft_border_style *style);
/* Change border style of the current table */
bool set_border_style(struct ft_border_style *style);
```
Here is a simple example of creating table and setting border style:
```C++
fort::char_table table;
/* Set table border style */
table.set_border_style(FT_BASIC_STYLE);
// Fill table with data
table << fort::header
<< "Rank" << "Title" << "Year" << "Rating" << fort::endr
<< "1" << "The Shawshank Redemption" << "1994" << "9.5" << fort::endr
<< "2" << "12 Angry Men" << "1957" << "8.8" << fort::endr
<< "3" << "It's a Wonderful Life" << "1946" << "8.6" << fort::endr
<< fort::separator
<< "4" << "2001: A Space Odyssey" << "1968" << "8.5" << fort::endr
<< "5" << "Blade Runner" << "1982" << "8.1" << fort::endr
<< fort::endr;
table.column(0).set_cell_text_align(fort::text_align::center);
table.column(1).set_cell_text_align(fort::text_align::left);
std::cout << table.to_string() << std::endl;
```
Output:
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_BASIC_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_BASIC2_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
+------+--------------------------+------+--------+
| 2 | 12 Angry Men | 1957 | 8.8 |
+------+--------------------------+------+--------+
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
+------+--------------------------+------+--------+
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_SIMPLE_STYLE
```text
Rank Title Year Rating
------ -------------------------- ------ --------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
------ -------------------------- ------ --------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_PLAIN_STYLE
```text
-------------------------------------------------
Rank Title Year Rating
-------------------------------------------------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
-------------------------------------------------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_DOT_STYLE
```text
...................................................
: Rank : Title : Year : Rating :
:......:..........................:......:........:
: 1 : The Shawshank Redemption : 1994 : 9.5 :
: 2 : 12 Angry Men : 1957 : 8.8 :
: 3 : It's a Wonderful Life : 1946 : 8.6 :
:......:..........................:......:........:
: 4 : 2001: A Space Odyssey : 1968 : 8.5 :
: 5 : Blade Runner : 1982 : 8.1 :
:......:..........................:......:........:
```
## FT_EMPTY_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_EMPTY2_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_SOLID_STYLE
```text
┌──────┬──────────────────────────┬──────┬────────┐
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
└──────┴──────────────────────────┴──────┴────────╯
```
## FT_SOLID_ROUND_STYLE
```text
╭──────┬──────────────────────────┬──────┬────────╮
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
╰──────┴──────────────────────────┴──────┴────────╯
```
## FT_DOUBLE_STYLE
```text
╔══════╦══════════════════════════╦══════╦════════╗
║ Rank ║ Title ║ Year ║ Rating ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
╚══════╩══════════════════════════╩══════╩════════╝
```
## FT_DOUBLE2_STYLE
```text
╔══════╤══════════════════════════╤══════╤════════╗
║ Rank │ Title │ Year │ Rating ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 2 │ 12 Angry Men │ 1957 │ 8.8 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 5 │ Blade Runner │ 1982 │ 8.1 ║
╚══════╧══════════════════════════╧══════╧════════╝
```
## FT_BOLD_STYLE
```text
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Rank ┃ Title ┃ Year ┃ Rating ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ┃
┃ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ┃
┃ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ┃
┃ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ┃
┗━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━┛
```
## FT_BOLD2_STYLE
```text
┏━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┓
┃ Rank │ Title │ Year │ Rating ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 2 │ 12 Angry Men │ 1957 │ 8.8 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 5 │ Blade Runner │ 1982 │ 8.1 ┃
┗━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┛
```
## FT_FRAME_STYLE
```text
▛▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▜
▌ Rank ┃ Title ┃ Year ┃ Rating ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ▐
▌ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ▐
▌ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ▐
▌ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ▐
▙▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▟
```

68
docs/tutorial/CPP_API/Cell-and-table-properties.md Normal file
View File

@ -0,0 +1,68 @@
## Cell properties
By default all cells created in **libfort** tables will have the same properties.
To change cell properties one should use functions `set_cell_{property_name}`:
```C++
bool set_cell_min_width(unsigned value);
bool set_cell_text_align(enum fort::text_align value);
bool set_cell_top_padding(unsigned value);
bool set_cell_bottom_padding(unsigned value);
bool set_cell_left_padding(unsigned value);
bool set_cell_right_padding(unsigned value);
bool set_cell_empty_str_height(unsigned value);
bool set_cell_row_type(enum fort::row_type value);
bool set_cell_content_fg_color(enum fort::color value);
bool set_cell_bg_color(enum fort::color value);
bool set_cell_content_bg_color(enum fort::color value);
bool set_cell_text_style(enum fort::text_style value);
bool set_cell_content_text_style(enum fort::text_style value);
```
Properties can be set as default (for all cells in tables that will be created in the future),
for all cells of the specified table, for cells in the particular row of the specified table, for cells in the particular column of the specified table and for the particular cell of the specified table.
These examples illustrate it:
```C++
// Set top padding = 2 for all cells in all tables that will be later created
fort::table::default_props().set_cell_top_padding(2);
// Set row type for all cells in row 2
table.row(2).set_cell_row_type(fort::row_type::header);
// Set text alignment for all cells in column 1
table.column(1).set_cell_text_align(fort::text_align::center);
// Set min width of the cell(0,0)
table[0][0].set_cell_min_width(20);
```
Here is a simple complete example:
```C++
fort::char_table table;
// Fill table with data
table << fort::header
<< "Rank" << "Title" << "Year" << "Rating" << fort::endr
<< "1" << "The Shawshank Redemption" << "1994" << "9.5" << fort::endr
<< "2" << "12 Angry Men" << "1957" << "8.8" << fort::endr
<< "3" << "It's a Wonderful Life" << "1946" << "8.6" << fort::endr
<< fort::endr;
table[0][0].set_cell_min_width(20);
table.column(1).set_cell_text_align(fort::text_align::center);
table[3][3].set_cell_left_padding(15);
std::cout << table.to_string() << std::endl;
```
Output:
```
+--------------------+--------------------------+------+-------------------+
| Rank | Title | Year | Rating |
+--------------------+--------------------------+------+-------------------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+--------------------+--------------------------+------+-------------------+
```

117
docs/tutorial/CPP_API/Filling-tables-with-data.md Normal file
View File

@ -0,0 +1,117 @@
At each moment of time a **libfort** table has a current cell - cell to which data will be written in the next write operation.
Functions `set_cur_cell` and `operator<<(fort::endr)` can be used to change current cell:
```CPP
/* Set current cell to the cell with coordinates (row, col) */
void set_cur_cell(size_t row, size_t col)
/* Set current cell to the first cell of the next row(line) */
table << fort::endr;
```
There are a lot of functions that can be used to fill tables with data.
All write functions are grouped in pairs (**_function_**, **_function_ln_**), where **function** writes data to a group of consecutive cells, **function_ln** does the same and moves _current-cell_ pointer to the first cell of the next row(line).
### operator <<
This operator (`<<`) applied to a **libfort** table is known as insertion operator. It inserts string to the table cell. Internally **libfort** converts argument to a string using `std::stringstream`. If you want to insert argument of some custom type in a table you should overload `std::stringstream::operator<<`.
```CPP
fort::char_table table;
table << fort::header
<< "N" << "Driver" << "Time" << "Avg Speed" << fort::endr
<< "1" << "Ricciardo" << "1:25.945" << "47.362" << fort::endr
<< "2" << "Hamilton" << "1:26.373" << "35.02" << fort::endr
<< "3" << "Verstappen" << "1:26.469" << "29.78" << fort::endr;
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### operator[]
This operator (`[]`) provides an ability to directly change content of a particular cell.
```CPP
fort::char_table table;
table << fort::header;
table[0][0] = "N"; table[0][1] = "Driver"; table[0][2] = "Time"; table[0][3] = "Avg Speed";
table[1][0] = "1"; table[1][1] = "Ricciardo"; table[1][2] = "1:25.945"; table[1][3] = "47.362";
table[2][0] = "2"; table[2][1] = "Hamilton"; table[2][2] = "1:26.373"; table[2][3] = "35.02";
table[3][0] = "3"; table[3][1] = "Verstappen"; table[3][2] = "1:26.469"; table[3][3] = "29.78";
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### write, write_ln
`write`, `write_ln` write an arbitrary number of string arguments to the table cells.
```CPP
fort::char_table table;
table << fort::header;
table.write_ln("N", "Driver", "Time", "Avg Speed");
table.write_ln("1", "Ricciardo", "1:25.945", "47.362");
table.write_ln("2", "Hamilton", "1:26.373", "35.02");
table.write_ln("3", "Verstappen", "1:26.469", "29.78");
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### range_write, range_write_ln
`range_write`, `range_write_ln` write data from a container determined by a pair of iterators.
```C++
template <typename InputIt>
bool range_write(InputIt first, InputIt last);
template <typename InputIt>
bool range_write_ln(InputIt first, InputIt last);
```
```C++
fort::char_table table;
table << fort::header;
std::vector<std::string> header = {"N", "Driver", "Time", "Avg Speed"};
std::list<std::string> line_1 = {"1", "Ricciardo", "1:25.945", "47.362"};
std::initializer_list<std::string> line_2 = {"2", "Hamilton", "1:26.373", "35.02"};
std::deque<std::string> line_3 = {"3", "Verstappen", "1:26.469", "29.78"};
table.range_write_ln(header.begin(), header.end());
table.range_write_ln(line_1.begin(), line_1.end());
table.range_write_ln(line_2.begin(), line_2.end());
table.range_write_ln(line_3.begin(), line_3.end());
std::cout << table.to_string() << std::endl;
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```

30
docs/tutorial/CPP_API/Table-life-cycle.md Normal file
View File

@ -0,0 +1,30 @@
The common **libfort table** life cycle:
- create a table (with default constructor, copy constructor or move constructor);
- fill it with data (`operator <<`, `operator[]`, `write_ln` ...);
- modify basic table appearance;
- convert table to string representation (`to_string`) and print it.
All resources allocated during table lifetime will be automatically freed in destructor.
Example:
```CPP
fort::char_table table;
table << fort::header
<< "N" << "Driver" << "Time" << "Avg Speed" << fort::endr
<< "1" << "Ricciardo" << "1:25.945" << "47.362" << fort::endr
<< "2" << "Hamilton" << "1:26.373" << "35.02" << fort::endr
<< "3" << "Verstappen" << "1:26.469" << "29.78" << fort::endr;
std::cout << table.to_string() << std::endl;
```
Output:
```
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 47.362 |
| 2 | Hamilton | 1:26.373 | 35.02 |
| 3 | Verstappen | 1:26.469 | 29.78 |
+---+------------+----------+-----------+
```

345
docs/tutorial/C_API/Border-styles.md Normal file
View File

@ -0,0 +1,345 @@
- [Change border style](#change-border-style)
- [Custom border styles](#custom-border-styles)
- [Built-in border styles](#built-in-border-styles)
## Change border style
**libfort** has a number of built-in border styles.
To change border style of **libfort** tables one can use `ft_set_default_border_style`, `ft_set_border_style` functions:
```C
/* Change border style of all libfort tables that will be created */
int ft_set_default_border_style(const struct ft_border_style *style);
/* Change border style of a particular table */
int ft_set_border_style(ft_table_t *table, const struct ft_border_style *style);
/**
* Structure describing border appearance.
*/
struct ft_border_chars {
const char *top_border_ch;
const char *separator_ch;
const char *bottom_border_ch;
const char *side_border_ch;
const char *out_intersect_ch;
const char *in_intersect_ch;
};
/**
* Structure describing border style.
*/
struct ft_border_style {
struct ft_border_chars border_chs;
struct ft_border_chars header_border_chs;
const char *hor_separator_char;
};
```
Here is a simple example of creating table and setting built-in border style:
```C
ft_table_t *table = ft_create_table();
/* Set border style */
ft_set_border_style(table, FT_BASIC_STYLE);
ft_set_cell_prop(table, FT_ANY_ROW, 0, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_CENTER);
ft_set_cell_prop(table, FT_ANY_ROW, 1, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_LEFT);
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "Rank", "Title", "Year", "Rating");
ft_write_ln(table, "1", "The Shawshank Redemption", "1994", "9.5");
ft_write_ln(table, "2", "12 Angry Men", "1957", "8.8");
ft_write_ln(table, "3", "It's a Wonderful Life", "1946", "8.6");
ft_add_separator(table);
ft_write_ln(table, "4", "2001: A Space Odyssey", "1968", "8.5");
ft_write_ln(table, "5", "Blade Runner", "1982", "8.1");
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## Custom border styles
`ft_set_default_border_style`, `ft_set_border_style` can be used to set custom border styles:
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
ft_add_separator(table);
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
/* Set custom border style */
struct ft_border_chars border;
border.top_border_ch = "^";
border.separator_ch = "=";
border.bottom_border_ch = "v";
border.side_border_ch = "|";
border.out_intersect_ch = "x";
border.in_intersect_ch = "x";
struct ft_border_style border_style;
memcpy(&border_style.border_chs, &border, sizeof(struct ft_border_chars));
memcpy(&border_style.header_border_chs, &border, sizeof(struct ft_border_chars));
border_style.hor_separator_char = "~";
ft_set_border_style(table, &border_style);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```
x^^^x^^^^^^^^^^^^x^^^^^^^^^^x^^^^^^^^^^^x
| N | Driver | Time | Avg Speed |
x===x============x==========x===========x
| 1 | Ricciardo | 1:25.945 | 222.128 |
x===x============x==========x===========x
| 2 | Hamilton | 1:26.373 | 221.027 |
x~~~x~~~~~~~~~~~~x~~~~~~~~~~x~~~~~~~~~~~x
| 3 | Verstappen | 1:26.469 | 220.782 |
xvvvxvvvvvvvvvvvvxvvvvvvvvvvxvvvvvvvvvvvx
```
## Built-in border styles
## FT_BASIC_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
| 2 | 12 Angry Men | 1957 | 8.8 |
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_BASIC2_STYLE
```text
+------+--------------------------+------+--------+
| Rank | Title | Year | Rating |
+------+--------------------------+------+--------+
| 1 | The Shawshank Redemption | 1994 | 9.5 |
+------+--------------------------+------+--------+
| 2 | 12 Angry Men | 1957 | 8.8 |
+------+--------------------------+------+--------+
| 3 | It's a Wonderful Life | 1946 | 8.6 |
+------+--------------------------+------+--------+
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
+------+--------------------------+------+--------+
| 5 | Blade Runner | 1982 | 8.1 |
+------+--------------------------+------+--------+
```
## FT_SIMPLE_STYLE
```text
Rank Title Year Rating
------ -------------------------- ------ --------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
------ -------------------------- ------ --------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_PLAIN_STYLE
```text
-------------------------------------------------
Rank Title Year Rating
-------------------------------------------------
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
-------------------------------------------------
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_DOT_STYLE
```text
...................................................
: Rank : Title : Year : Rating :
:......:..........................:......:........:
: 1 : The Shawshank Redemption : 1994 : 9.5 :
: 2 : 12 Angry Men : 1957 : 8.8 :
: 3 : It's a Wonderful Life : 1946 : 8.6 :
:......:..........................:......:........:
: 4 : 2001: A Space Odyssey : 1968 : 8.5 :
: 5 : Blade Runner : 1982 : 8.1 :
:......:..........................:......:........:
```
## FT_EMPTY_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_EMPTY2_STYLE
```text
Rank Title Year Rating
1 The Shawshank Redemption 1994 9.5
2 12 Angry Men 1957 8.8
3 It's a Wonderful Life 1946 8.6
4 2001: A Space Odyssey 1968 8.5
5 Blade Runner 1982 8.1
```
## FT_SOLID_STYLE
```text
┌──────┬──────────────────────────┬──────┬────────┐
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
└──────┴──────────────────────────┴──────┴────────╯
```
## FT_SOLID_ROUND_STYLE
```text
╭──────┬──────────────────────────┬──────┬────────╮
│ Rank │ Title │ Year │ Rating │
├──────┼──────────────────────────┼──────┼────────┤
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
├──────┼──────────────────────────┼──────┼────────┤
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
│ 5 │ Blade Runner │ 1982 │ 8.1 │
╰──────┴──────────────────────────┴──────┴────────╯
```
## FT_NICE_STYLE
```text
╔══════╦══════════════════════════╦══════╦════════╗
║ Rank ║ Title ║ Year ║ Rating ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
╟──────╫──────────────────────────╫──────╫────────╢
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
╚══════╩══════════════════════════╩══════╩════════╝
```
## FT_DOUBLE_STYLE
```text
╔══════╦══════════════════════════╦══════╦════════╗
║ Rank ║ Title ║ Year ║ Rating ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
╠══════╬══════════════════════════╬══════╬════════╣
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
╚══════╩══════════════════════════╩══════╩════════╝
```
## FT_DOUBLE2_STYLE
```text
╔══════╤══════════════════════════╤══════╤════════╗
║ Rank │ Title │ Year │ Rating ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 2 │ 12 Angry Men │ 1957 │ 8.8 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ║
╠══════╪══════════════════════════╪══════╪════════╣
║ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ║
╟──────┼──────────────────────────┼──────┼────────╢
║ 5 │ Blade Runner │ 1982 │ 8.1 ║
╚══════╧══════════════════════════╧══════╧════════╝
```
## FT_BOLD_STYLE
```text
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Rank ┃ Title ┃ Year ┃ Rating ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ┃
┃ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ┃
┃ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ┃
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
┃ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ┃
┃ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ┃
┗━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━┛
```
## FT_BOLD2_STYLE
```text
┏━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┓
┃ Rank │ Title │ Year │ Rating ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 2 │ 12 Angry Men │ 1957 │ 8.8 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ┃
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
┃ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ┃
┠──────┼──────────────────────────┼──────┼────────┨
┃ 5 │ Blade Runner │ 1982 │ 8.1 ┃
┗━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┛
```
## FT_FRAME_STYLE
```text
▛▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▜
▌ Rank ┃ Title ┃ Year ┃ Rating ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ▐
▌ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ▐
▌ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ▐
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
▌ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ▐
▌ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ▐
▙▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▟
```

146
docs/tutorial/C_API/Cell-and-table-properties.md Normal file
View File

@ -0,0 +1,146 @@
- [Cell properties](#cell-properties)
- [Table properties](#table-properties)
## Cell properties
By default all cells created in **libfort** tables will have the same properties. So for example if you want your first row to be a header for your table you should explicitly specify corresponding options.
To change cell properties one should use functions `ft_set_cell_prop` and `ft_set_default_cell_prop`:
```C
/* Change cell properties for all new tables */
int ft_set_default_cell_prop(uint32_t property, int value);
/* Change cell properties for the particular table */
int ft_set_cell_prop(ft_table_t *table, size_t row, size_t col, uint32_t property, int value);
```
To change cell properties for all cells in the row, in the column or for the entire table use macros `FT_ANY_COLUMN` and `FT_ANY_ROW`:
| Example | Use case |
| --------------------------------------------------------------------- |:-----------------------------------------|
| `ft_set_cell_prop(table, row, FT_ANY_COLUMN, property, value)` | Set property for all cells in the row |
| `ft_set_cell_prop(table, FT_ANY_ROW, col, property, value)` | Set property for all cells in the column |
| `ft_set_cell_prop(table, FT_ANY_ROW, FT_ANY_COLUMN, property, value)` | Set property for all cells in the table |
Here is a simple example:
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
/* Set right text alignment for cell(0, 1) */
ft_set_cell_prop(table, 0, 1, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_RIGHT);
/* Set minimum cell width to 30 for cell(0, 1) */
ft_set_cell_prop(table, 0, 1, FT_CPROP_MIN_WIDTH, 30);
/* Set left padding = 3 for all cells in the 3rd column */
ft_set_cell_prop(table, FT_ANY_ROW, 3, FT_CPROP_LEFT_PADDING, 3);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
```
+---+------------------------------+----------+-------------+
| N | Driver | Time | Avg Speed |
+---+------------------------------+----------+-------------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------------------------+----------+-------------+
```
List of all possible cell properties:
| Property | Description | Possible values |
| ------------------------- |--------------------------------| ------------------------|
| FT_CPROP_MIN_WIDTH | Minimum width | Non negative int |
| FT_CPROP_TEXT_ALIGN | Text alignment | `enum ft_text_alignment`|
| FT_CPROP_TOP_PADDING | Top padding for cell content | Non negative int |
| FT_CPROP_BOTTOM_PADDING | Bottom padding for cell content| Non negative int |
| FT_CPROP_LEFT_PADDING | Left padding for cell content | Non negative int |
| FT_CPROP_EMPTY_STR_HEIGHT | Right padding for cell content | Non negative int |
| FT_CPROP_ROW_TYPE | Row type | `enum ft_row_type` |
| FT_CPROP_CONT_FG_COLOR | Content foreground color | `enum ft_color` |
| FT_CPROP_CELL_BG_COLOR | Cell background color | `enum ft_color` |
| FT_CPROP_CONT_BG_COLOR | Content background color | `enum ft_color` |
| FT_CPROP_CELL_TEXT_STYLE | Cell text style | `enum ft_text_style` |
| FT_CPROP_CONT_TEXT_STYLE | Content text style | `enum ft_text_style` |
where
```C
enum ft_text_alignment {
FT_ALIGNED_LEFT = 0, /**< Align left */
FT_ALIGNED_CENTER, /**< Align center */
FT_ALIGNED_RIGHT /**< Align right */
};
enum ft_row_type {
FT_ROW_COMMON = 0, /**< Common row */
FT_ROW_HEADER /**< Header row */
};
enum ft_color {
FT_COLOR_DEFAULT = 0,
FT_COLOR_BLACK = 1,
FT_COLOR_RED = 2,
FT_COLOR_GREEN = 3,
FT_COLOR_YELLOW = 4,
FT_COLOR_BLUE = 5,
FT_COLOR_MAGENTA = 6,
FT_COLOR_CYAN = 7,
FT_COLOR_LIGHT_GRAY = 8,
FT_COLOR_DARK_GRAY = 9,
FT_COLOR_LIGHT_RED = 10,
FT_COLOR_LIGHT_GREEN = 11,
FT_COLOR_LIGHT_YELLOW = 12,
FT_COLOR_LIGHT_BLUE = 13,
FT_COLOR_LIGHT_MAGENTA = 15,
FT_COLOR_LIGHT_CYAN = 16,
FT_COLOR_LIGHT_WHYTE = 17
};
enum ft_text_style {
FT_TSTYLE_DEFAULT = (1U << 0),
FT_TSTYLE_BOLD = (1U << 1),
FT_TSTYLE_DIM = (1U << 2),
FT_TSTYLE_ITALIC = (1U << 3),
FT_TSTYLE_UNDERLINED = (1U << 4),
FT_TSTYLE_BLINK = (1U << 5),
FT_TSTYLE_INVERTED = (1U << 6),
FT_TSTYLE_HIDDEN = (1U << 7)
};
```
## Table properties
To change table properties use functions `ft_set_tbl_prop` and `ft_set_default_tbl_prop`:
```C
/* Change table properties for all new tables */
int ft_set_default_tbl_prop(uint32_t property, int value);
/* Change table properties for the particular table */
int ft_set_tbl_prop(ft_table_t *table, uint32_t property, int value);
```
List of all possible table properties:
| Property | Description | Possible values |
| ------------------------- |---------------| ------------------|
| FT_TPROP_LEFT_MARGIN | Left margin | Non negative int |
| FT_TPROP_TOP_MARGIN | Top margin | Non negative int |
| FT_TPROP_RIGHT_MARGIN | Right margin | Non negative int |
| FT_TPROP_BOTTOM_MARGIN | Bottom margin | Non negative int |
Table margins are used during conversion to string representation:
```
M ^ M
L a | Top margin R a
e r v i r
f g ╔═══════╤════════╗ g g
t i ║ Cell │ Cell ║ h i
n ╠═══════╪════════╣ t n
<----->║ Cell │ Cell ║<------------>
╚═══════╧════════╝
^
| Bottom margin
v
```

135
docs/tutorial/C_API/Filling-tables-with-data.md Normal file
View File

@ -0,0 +1,135 @@
At each moment of time a **libfort** table has a current cell - cell to which data will be written in the next write operation.
Functions `ft_set_cur_cell` and `ft_ln` can be used to change current cell:
```C
/* Set current cell to the cell with coordinates (row, col) */
void ft_set_cur_cell(ft_table_t *table, size_t row, size_t col);
/* Set current cell to the first cell of the next row(line) */
void ft_ln(ft_table_t *table);
```
There are a lot of functions that can be used to fill tables with data.
All write functions are grouped in pairs (**_function_**, **_function_ln_**), where **function** writes data to a group of consecutive cells, **function_ln** does the same and moves _current-cell_ pointer to the first cell of the next row(line).
### ft_write, ft_write_ln
`ft_write`, `ft_write_ln` macros can be used to write an arbitrary number of strings to the table cells.
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 47.362 |
| 2 | Hamilton | 1:26.373 | 35.02 |
| 3 | Verstappen | 1:26.469 | 29.78 |
+---+------------+----------+-----------+
```
### ft_printf, ft_printf_ln
`ft_printf`, `ft_printf_ln` functions provide habitual **printf**-like interface.
```C
int ft_printf(ft_table_t *table, const char *fmt, ...);
int ft_printf_ln(ft_table_t *table, const char *fmt, ...);
```
By default vertical line character '|' in the format string is treated as a cell separator.
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
ft_printf_ln(table, "%d|%s|%s|%7.3f", 1, "Ricciardo", "1:25.945", 222.128);
ft_printf_ln(table, "%d|%s|%s|%d.%d", 2, "Hamilton", "1:26.373", 221, 027);
ft_printf_ln(table, "%d|%s|%s|%s.%d", 3, "Verstappen", "1:26.469", "220", 782);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### ft_row_write, ft_row_write_ln
`ft_row_write`, `ft_row_write_ln` functions provide means to copy string data from the string arrays to the table.
```C
int ft_row_write(ft_table_t *table, size_t cols, const char *row_cells[]);
int ft_row_write_ln(ft_table_t *table, size_t cols, const char *row_cells[]);
```
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
const char *header[] = {"N", "Driver", "Time", "Avg Speed"};
const char *line_1[] = {"1", "Ricciardo", "1:25.945", "222.128"};
const char *line_2[] = {"2", "Hamilton", "1:26.373", "221.027"};
const char *line_3[] = {"3", "Verstappen", "1:26.469", "220.782"};
ft_row_write_ln(table, 4, header);
ft_row_write_ln(table, 4, line_1);
ft_row_write_ln(table, 4, line_2);
ft_row_write_ln(table, 4, line_3);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```
### ft_table_write, ft_table_write_ln
`ft_table_write`, `ft_table_write_ln` functions provide means to copy string data from the 2D array to the table.
```C
int ft_table_write(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
int ft_table_write_ln(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
```
```C
ft_table_t *table = ft_create_table();
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
const char *data[4][4] = {
{"N", "Driver", "Time", "Avg Speed"},
{"1", "Ricciardo", "1:25.945", "222.128"},
{"2", "Hamilton", "1:26.373", "221.027"},
{"3", "Verstappen", "1:26.469", "220.782"}};
ft_table_write_ln(table, 4, 4, (const char **)data);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+-----------+
```

77
docs/tutorial/C_API/Misc.md Normal file
View File

@ -0,0 +1,77 @@
- [Row separators](#row-separators)
- [Cell span](#cell-span)
- [Custom memory allocators](#custom-memory-allocators)
## Row separators
Explicit row separators are useful in styles without horizontal borders between rows to emphasize content. To add row separator use function `ft_add_separator`:
```C
int ft_add_separator(ft_table_t *table);
```
Example:
```C
ft_table_t *table = ft_create_table();
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
ft_add_separator(table);
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```
+---+------------+----------+---------+
| 1 | Ricciardo | 1:25.945 | 222.128 |
| 2 | Hamilton | 1:26.373 | 221.027 |
+---+------------+----------+---------+
| 3 | Verstappen | 1:26.469 | 220.782 |
+---+------------+----------+---------+
```
## Cell span
Cells can span two or more columns. To specify cell span use `ft_set_cell_span`:
```C
/* Set horizontal span for cell (row, col) */
int ft_set_cell_span(ft_table_t *table, size_t row, size_t col, size_t hor_span);
```
Example:
```C
ft_table_t *table = ft_create_table();
/* Change border style */
ft_set_border_style(table, FT_DOUBLE2_STYLE);
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "Sed", "Aenean", "Text");
ft_write_ln(table, "Duis", "Aliquam", "Lorem ipsum dolor");
ft_write_ln(table, "Mauris", "Curabitur", "Proin condimentum");
ft_write_ln(table, "Summary", "", "Sed tempor est eget odio varius dignissim.");
/* Set cell span */
ft_set_cell_span(table, 3, 0, 2);
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
```
Output:
```
╔════════╤═══════════╤════════════════════════════════════════════╗
║ Sed │ Aenean │ Text ║
╠════════╪═══════════╪════════════════════════════════════════════╣
║ Duis │ Aliquam │ Lorem ipsum dolor ║
╟────────┼───────────┼────────────────────────────────────────────╢
║ Mauris │ Curabitur │ Proin condimentum ║
╟────────┴───────────┼────────────────────────────────────────────╢
║ Summary │ Sed tempor est eget odio varius dignissim. ║
╚════════════════════╧════════════════════════════════════════════╝
```
## Custom memory allocators
**libfort** actively uses memory allocation functions (by default standard `malloc`, `free` ...). If your application uses custom memory allocators you can provide appropriate functions to **libfort**:
```C
void ft_set_memory_funcs(void *(*f_malloc)(size_t size), void (*f_free)(void *ptr));
```

44
docs/tutorial/C_API/Table-life-cycle.md Normal file
View File

@ -0,0 +1,44 @@
The common **libfort table** life cycle:
- create a table (`ft_create_table`);
- fill it with data (`ft_write_ln, fr_ptrintf_ln, ft_row_write, ...`);
- modify basic table appearance (`ft_set_cell_prop, ft_set_border_style ...`)
- convert table to string representation (`ft_to_string`) and print it;
- destroy the table (`ft_destroy_table`).
Here is a simple example:
```C
/* C API */
#include <stdio.h>
#include "fort.h"
int main(void)
{
ft_table_t *table = ft_create_table();
/* Set "header" type for the first row */
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
printf("%s\n", ft_to_string(table));
ft_destroy_table(table);
}
```
Output:
```text
+---+------------+----------+-----------+
| N | Driver | Time | Avg Speed |
+---+------------+----------+-----------+
| 1 | Ricciardo | 1:25.945 | 47.362 |
| 2 | Hamilton | 1:26.373 | 35.02 |
| 3 | Verstappen | 1:26.469 | 29.78 |
+---+------------+----------+-----------+
```
To copy table and all its internal data use `ft_copy_table`:
```C
ft_table_t *ft_copy_table(ft_table_t *table);
```

22
docs/tutorial/Tutorial.md Normal file
View File

@ -0,0 +1,22 @@
**libfort** is a simple crossplatform library to create formatted text tables.
**libfort** is written in C and to use it you should include [fort.h](https://github.com/seleznevae/libfort/blob/develop/lib/fort.h) in your source files and compile with [`fort.c`](https://github.com/seleznevae/libfort/blob/develop/lib/fort.c) file.
The functions generally follow standard C conventions. They tend to return 0 or a pointer when acting properly, and negative integer numbers or NULL when something went wrong.
For C++ projects that use compiler with C++11 support (and later) there are also availabe convenient C++ wrappers around C functions (see [`fort.hpp`](https://github.com/seleznevae/libfort/blob/develop/lib/fort.hpp) in **lib** direrctory). In that case instead of `fort.h` you will need to include `fort.hpp` in your source files and use C++ **libfort** API.
**libfort** doesn't use any threading itself. Therefore you shouldn't specify default table properties or work with the same table from different threads without external synchronization. However, it should be safe to create different tables from different threads and work with them in each thread separately.
# Tutorial content
- [C API](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Table-life-cycle.md)
- [Table life cycle](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Table-life-cycle.md)
- [Filling tables with data](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Filling-tables-with-data.md)
- [Cell and table properties](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Cell-and-table-properties.md)
- [Border styles](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Border-styles.md)
- [Misc](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/C_API/Misc.md)
- [C++ API](https://github.com/seleznevae/libfort/wiki/Table-life-cycle-(CPP-API))
- [Table life cycle](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/CPP_API/Table-life-cycle.md)
- [Filling tables with data](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/CPP_API/Filling-tables-with-data.md)
- [Cell and table properties](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/CPP_API/Cell-and-table-properties.md)
- [Border styles](https://github.com/seleznevae/libfort/blob/develop/docs/tutorial/CPP_API/Border-styles.md)