.TH "FBB::Table" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Table\-formatter"

.PP 
.SH "NAME"
FBB::Table \- Generates row\- or column\-wise filled tables
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/table>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fBFBB::Table\fP objects can be used to create tables\&. Tables are filled
either column\- or row\-wise\&. Many of the table\(cq\&s characteristics may be
fine\-tuned using a separate \fBFBB::TableSupport\fP object (cf\&.
\fBtablesupport\fP(3bobcat))\&. When no \fBFBB::TableSupport\fP object is used, a
plain table, filled row\-wise or column\-wise, is constructed which can be
inserted into a \fBstd::ostream\fP\&.
.PP 
Tables defined by \fITable\fP consist of rows and a fixed number of
columns\&. The number of columns is specified at construction time, the number
of rows also depends on the number of inserted elements\&. Columns and rows are
addressed using indices (starting at 0)\&. Before the leftmost column, between
the columns and beyond the last column \fIseparators\fP are defined\&. By default
these separators are empty, but each separator may be given a (fixed) width or
content\&. The separator before column \fIcol\fP is addressed as separator
\fIcol\fP, the rightmost separator is addressed as separator \fInColummns\fP\&.
.PP 
Rows can also be separated from each other using separators\&. These separating
rows are empty by default\&. The row\-separator before row \fIrow\fP is addressed
as row\-separator \fIrow\fP\&. The row\-separator following the final row is
addressed as row\-separator \fInRows\fP, where \fInRows\fP is the value returned by
the \fInRows\fP member function\&.
.PP 
Non\-default (i\&.e\&., non\-empty) separators are defined using
\fIFBB::TableSupport\fP objects (cf\&. \fBtablesupport\fP(3bobcat))\&.
.PP 
\fITable\fP objects look a lot like \fIostream\fP objects, using a simple way
to define new elements: each new insertion defines another table element, and
it is difficult to end a row before it has received its \fInColumn\fP number of
elements\&. \fITable\fP\(cq\&s sister\-class, \fITableBuf\fP, is a \fIstd::streambuf\fP type
of class, offering additional control through the use of a wrapping
\fIostream\fP class object\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"

.PP 
\fBstd::ostringstream\fP \- \fITable\fP inherits from \fBstd::ostringstream\fP,
allowing insertions into a \fBTable\fP object\&. Each separate insertion adds
another element to the \fBTable\fP object\&.
.PP 
\fBFBB::TableBase\fP \- This class implements common elements of the table
implementation\&. The \fITableBase\fP class is not intended to be used by itself,
and no separate man\-page is provided\&. Facilities provided by \fITable\fP
which were inherited from \fITableBase\fP are described in this man\-page\&.
.PP 
.SH "ENUMERATIONS"
The following enumerations are defined by the class \fBFBB::Table\fP:
\fBenum FillDirection\fP
.br 
This enumeration defines two values:
.IP o 
\fBROWWISE\fP:
.br 
When this value is specified at construction time, elements are added
row\-wise to the table\&. I\&.e\&., the second element inserted into the
\fITable\fP will be found in the second column of the first row;
.IP o 
\fBCOLUMNWISE\fP:
.br 
When this value is specified at construction time, elements are added
column\-wise to the table\&. I\&.e\&., the second element is found in
the second row of the first column\&.

.PP 
\fBenum WidthType\fP
.br 
This enumeration defines two values:
.IP o 
\fBCOLUMNWIDTH\fP:
.br 
Specify this value when the columns may have variable widths\&. In this
case each column will be as wide as its widest element\&. This is the
default \fIWidthType\fP used by \fITable\fP objects\&.
.IP o 
\fBEQUALWIDTH\fP:
.br 
Specify this value when all of the table\(cq\&s columns must have equal
widths (i\&.e\&., equal to the width of the widest table element),

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBTable(size_t nColumns, Table::FillDirection direction,
Table::WidthType widthType = Table::COLUMNWIDTH)\fP:
.br 
The table\(cq\&s number of columns, the fill directions and the column
width\-type must be provided\&.  The number of rows is implied by the
combination of this parameter and the number of elements that is
actually inserted into the \fITable\fP object\&.  The \fIdirection\fP
parameter specifies the way new elements are added to the \fITable\fP
object: row\-wise or column\-wise\&. Finally, the \fIwidthType\fP parameter
is used to specify the way the width of the table\(cq\&s columns is
determined\&. Each column either defines its own width or all columns
have equal widths\&.
.IP o 
\fBTable(TableSupport &tableSupport, size_t nColumns,
Table::FillDirection direction,
Table::WidthType widthType = Table::COLUMNWIDTH)\fP:
.br 
This constructor operates identically to the previous constructor, but
expects an additional reference to a \fITableSupport\fP object\&. A
\fITableSupport\fP object offers additional formatting features used by
the table defining elements like horizontal lines between rows,
additional separators, etc, etc\&. The \fITableSupport\fP object is passed
as a non\-const reference as the \fITable\fP object must be able to
manipulate its data\&. See \fBtablesuppport\fP(3bobcat) for more
information about \fITableSupport\fP\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "OVERLOADED OPERATORS"

.PP 
.IP o 
\fBstd::ostream &operator<<(std::ostream &str, Table &table)\fP:
.br 
This operator inserts a \fITable\fP into a \fIstd::ostream\fP object\&.  This
operator requires a non\-const table as it may have to complete the
table by adding empty elements (i\&.e\&., empty strings) to obtain a
completely filled rectangular table;
.IP o 
\fBTable &operator<<(Table &obj, Align const &align)\fP:
.br 
This operator changes the default alignment of either a column or an
element\&. It is a wrapper around the member \fIsetAlign\fP (see below
for its description)\&. By default, all elements are right\-aligned (see
also \fBalign\fP(3bobcat));
.IP o 
\fBTable &operator<<(Table &obj, Type const &item)\fP:
.br 
This operator is defined as a function template: \fIType\fP is a template
type parameter instantiated to a type for which \fIstd::ostringstream\fP
insertions are possible\&.  It inserts the value/object \fIitem\fP into
the \fITable\fP\(cq\&s \fIstd::ostringstream\fP base class object as the
table\(cq\&s next element\&.

.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBTable &append(std::string const &text
char const *sep = \(dq\& \et\(dq\&, bool addEmpty = false)\fP:
.br 
Fields in \fItext\fP separated by one of the characters in \fIsep\fP are
added as elements to the \fITable\fP object\&. Empty fields are ignored
unless the parameter \fIaddEmpty\fP is \fItrue\fP;
.IP o 
\fBvoid clear()\fP:
.br 
The content of the table is erased;
.IP o 
\fBvoid clearStr()\fP:
.br 
The content of its \fIstd::ostringstream\fP base class buffer is erased;
.IP o 
\fBTable &def()\fP:
.br 
After inserting elements into a \fITable\fP object its number of elements
may or may not be an integral multiple of the number of columns
specified at construction time\&. To `complete\(cq\& a \fITable\fP object to a
rectangular object, for which all column widths and alignments have
been determined \fIdef\fP can be called\&. It is automatically
called by \fIoperator<<(ostream, Table)\fP\&. In other situations it may
be called explicitly to force the insertion of another row in a table
using \fIROWWISE\fP insertions\&. With \fICOLUMNWISE\fP insertions its
working is complex, since new elements added to a \fICOLUMNWISE\fP
filled table will reshuffle its elements over the table\(cq\&s columns;
.IP o 
\fBvoid fill(InputIterator begin, InputIterator end)\fP:
.br 
This member is defined as a member template; \fIInputIterator\fP is a
template type parameter representing any input iterator\&. It can also
be, e\&.g\&., a pointer to an insertable type\&. The iterators must point to
data elements which can be inserted into an \fIstd::ostream\fP\&. The
range of values implied by the member\(cq\&s iterator pair are inserted
into the table as new elements;
.IP o 
\fBvoid push_back(std::string const &element)\fP:
.br 
New elements can be added to the table using \fIpush_back\fP\&. It could
e\&.g\&., be called from a \fIback_inserter\fP adaptor;
.IP o 
\fBsize_t nRows()\fP:
.br 
The table\(cq\&s current number of rows is returned\&. It is initialized to 0,
and after that updated when \fIdef\fP has been called;
.IP o 
\fBTable &setAlign(Align const &align)\fP:
.br 
The alignment type of either a column or an element of the \fITable\fP
object is defined using \fIsetAlign\fP\&. The standard alignments
\fIstd::left, std::right\fP and \fIstd::internal\fP may be specified, but
in addition the alignment \fIFBB::center\fP may be used if elements
should be centered into their column\&. A construction like 
.nf 
tab << Align(2, FBB::center)
.fi 
requests centering of all elements in the table\(cq\&s column having index
value 2 (i\&.e\&., the table\(cq\&s 3rd column), whereas a construction like
.nf 
tab << Align(2, 3, FBB::center)
.fi 
requests centering of element [2][3]\&. It is the responsibility of the
programmer to ensure that such elements exist\&. By default, all
elements are right\-aligned\&.
)
.PP 
.SH "MANPULATORS"
.IP o 
\fBTable &def(Table &table)\fP:
.br 
This manipulator can be inserted into a table to call the table\(cq\&s
\fIdef\fP member\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
#include <iostream>

#include <bobcat/table>
#include <bobcat/tablelines>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
{
    TableLines tablelines;
                                // width/separators of cols 0, 1 and 2
    tablelines << 0 << \(dq\& | \(dq\& << \(dq\& | \(dq\&;

                                // hline over cols 1 and 2 of row 1
    tablelines << TableLines::HLine(1, 1, 3);

    Table tab(tablelines, 3, Table::ROWWISE, Table::EQUALWIDTH);
    // or: Table tab(tablelines, 3, Table::ROWWISE);

    tab << Align(0, std::left);     // set column non\-default alignment
    tab\&.fill(argv + 1, argv + argc);// fill range of values

    cout << tab << \(cq\&\en\(cq\&;            // complete the table and insert

    tab << \(dq\&hello\(dq\& << \(dq\&\(dq\& << \(dq\&wo\(dq\&;   // add additional elements\&.
    if (tab\&.nRows() > 2)
        tab << Align(2, 2, center); // set the layout of a specific element

    cout << tab << \(cq\&\en\(cq\&;
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/table\fP \- defines the class interface;
.br 

.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBalign\fP(3bobcat), \fBcsvtable\fP(3bobcat),
\fBmanipulator\fP(3bobcat), \fBtablebuf\fP(3bobcat), \fBtablelines\fP(3bobcat),
\fBtablesupport\fP(3bobcat)
.PP 
.SH "BUGS"
Note that \fIdef()\fP will reshuffle elements over the table\(cq\&s
columns when new elements are added to the table subsequent to calling
\fIdef()\fP
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP