.TH "FBB::Table" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Construct text tables"

.PP 
.SH "NAME"
FBB::Table \- Generates row\- or column\-wise filled tables from
information inserted into a std::ostream
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/tablebuf>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"

.PP 
\fBFBB::Tablebuf\fP objects are \fBstd::streambuf\fP objects that can be used
to create tables\&. The tables are filled either column\-wise or row\-wise\&. Many
of the table\(cq\&s characteristics may be fine\-tuned by a separate
\fBFBB::TableSupport\fP object, described in a separate man\-page
(\fBTableSupport\fP(3bobcat))\&. When no \fBFBB::TableSupport\fP object is used, a
plain row\-wise or column\-wise table is constructed which can be inserted into
a \fBstd::ostream\fP\&. Displaying a table (e\&.g\&., at the standard output stream)
involves the following steps:
.IP o 
Optionally, a  \fITableSupport\fP object is created;
.IP o 
A \fITablebuf\fP object is created (maybe passing it a \fITableSupport\fP
object); 
.IP o 
The \fITablebuf\fP object is used to initialize a \fIstd::ostream\fP
.IP o 
The elements of the table are filled by inserting information into
that \fIstd::ostream\fP
.IP o 
The \fITablebuf\fP itself contains the formatted table and may itself
be inserted into a \fIstd::ostream\fP like \fIstd::cout\fP\&.

.PP 
Tables defined by \fITableBuf\fP consist of a (number of element dependent)
number of rows and a fixed number of columns, the latter value is specified at
construction time\&. Columns and rows are normally addressed using index values
(starting at 0)\&. Before the leftmost column, between the columns and beyond
the last column \fIseparators\fP are defined\&. By default the 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 
Likewise, rows can be separated from each other using separators\&. These
separating rows are also 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 
\fITableBuf\fP\(cq\&s sister\-class \fITable\fP can be used to insert elements into a
table in a more direct way\&. With \fITableBuf\fP \fIfield separators\fP are used to
switch to the next table\-element, and (with row\-wise filled tables) a \fIrow
separator\fP can be used to switch to the next row when it\(cq\&s only partially
defined\&. Instead, with \fITable\fP objects each new insertion defines another
table element, and no wrapping \fIstd::ostream\fP object is required\&.
.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::streambuf\fP \- allowing \fITableBuf\fP objects to be wrapped in
\fIstd::ostream\fP objects\&.
.PP 
\fBFBB::TableBase\fP \- This class implements common elements of the
table implementation (the \fIFBB::TableBuf\fP class is also derived from
\fITableBase\fP)\&. The \fITableBase\fP class is not intended to be used otherwise,
and no separate man\-page is provided\&. All facilities provided by \fITable\fP
inherited from \fITableBase\fP are described in this man\-page\&.
.PP 
.SH "ENUMERATIONS"
The following enumerations are defined in the class \fBFBB::Tablebuf\fP\&.
.PP 
\fBenum FillDirection\fP
.br 
This enumeration has 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 \fBTable\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 will be found in the second
row of the first column\&.

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

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBTablebuf(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 \fBTable\fP object\&.  The \fBdirection\fP parameter specifies the way new
elements are added to the \fBTable\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 
\fBTableBuf(TableSupport &tableSupport, 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 \fBTableSupport\fP object\&. A
\fBTableSupport\fP object offers additional formatting features used by the
table defining elements like horizontal lines between rows, additional
separators, etc, etc\&. The \fBTableSupport\fP object is passed as a non\-const
reference as the \fBTable\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 &out, TableBuf &tablebuf)\fP:
.br 
This operator inserts a \fBTableBuf\fP into a \fIstd::ostream\fP
object\&. Note that the \fITableBuf\fP object inserted into \fIout\fP is a non\-const
object, as the table may have to be completed by adding empty elements for
missing ones\&. The \fIout\fP stream should not be equal to the \fIstd::ostream\fP
object that is used to wrap in a \fITableBuf\fP object\&. 
.IP o 
\fBTableBuf &operator<<(TableBuf &obj, Align const &align)\fP:
.br 
This operator is used to change 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
\fBalign\fP(3bobcat) for more information about the \fIAlign\fP class\&. Unlike the
insertion operators available for \fITable\fP type objects, the insertion
operator for \fITableBuf\fP objects is only used to define column or
cell\-alignment\&.

.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBvoid clear()\fP:
.br 
The content of the table are erased\&. All existing elements are
removed, and the table will be empty\&.
.IP o 
\fBsize_t nRows()\fP:
.br 
The currently available number of rows in the table is returned\&. Its
value is only defined after calling \fBdef()\fP\&.
.IP o 
\fBTableBuf &setAlign(Align const &align)\fP:
.br 
The alignment type of either a column or an element of the \fBTableBuf\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\&.
.IP o 
\fBTableBuf &def()\fP:
.br 
After inserting elements into a \fITableBuf\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 \fBTableBuf\fP object to a
rectangular object, for which all column widths and alignments have been
determined \fIdef\fP may be called\&. It is automatically called by
\fIoperator<<(ostream, TableBuf)\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 
\fBsetFieldSeparator(char fs)\fP:
.br 
The default field separator is the `backspace\(cq\& (\fI\eb\fP)
character\&. After inserting a field separator the next table element will be
defined\&. Inserting two field separators inserts an table empty element and
starts the definition of the next element\&. This field separator character can
be redefined by this function\&.  Calling \fIsetFieldSeparator\fP without argument
disables the use of a field separator character, and only leaves the use of
the \fIfs\fP manipulator to switch to the next field\&.
.IP o 
\fBsetRowSeparator(char rs)\fP:
.br 
The default row separator is the newline character (\fI\en\fP)\&.  After
inserting a row separator the next element to enter into the table will be the
leftmost element of the next row\&.  Inserting two row separators adds an empty
row to the table\&.  Calling \fIsetRowSeparator\fP without argument disables the
use of a row separator character, and only leaves the use of the \fIrs\fP
manipulator to switch to the next field\&.

.PP 
.SH "MANPULATORS"
.IP o 
\fBTable &def(Table &table)\fP:
.br 
This manipulator can be inserted into a a \fITableBuf\fP\(cq\&s wrapping
\fIostream\fP to call the table\(cq\&s \fBdef()\fP member\&.
.IP o 
\fBFBB::fs\fP:
.br 
This manipulator can be inserted into a \fITableBuf\fP\(cq\&s wrapping 
\fIostream\fP to switch to the next field of the table\&. It is an alternative to
using the field separator character\&.
.IP o 
\fBFBB::rs\fP:
.br 
This manipulator can be inserted into a \fITableBuf\fP\(cq\&s wrapping 
\fIostream\fP to switch to the next row of the table\&. It is an alternative to
using the row separator character\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
#include <iostream>
#include <ostream>
#include <string>
#include <algorithm>
#include <iterator>

#include <bobcat/tablebuf>
#include <bobcat/tablelines>

using namespace std;
using namespace FBB;

int main()
{
    TableLines tablelines;
                        
    tablelines << 0;            // set separator widths
    for (size_t sep = 0; sep != 8; ++sep)
        tablelines << 3;


    TableBuf tab(tablelines, 8, TableBuf::ROWWISE);

    ostream out(&tab);

    copy(istream_iterator<string>(cin), istream_iterator<string>(),
            ostream_iterator<string>(out, \(dq\&\eb\(dq\&));

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


.fi 

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

.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBalign\fP(3bobcat), \fBmanipulator\fP(3bobcat),
\fBtablelines\fP(3bobcat), \fBtablesupport\fP(3bobcat), \fBtable\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_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.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