.TH "FBB::TableSupport" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Table Support Base class"

.PP 
.SH "NAME"
FBB::TableSupport \- Defines protocols for Table\-support classes
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/tableSupport>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::TableSupport\fP is used by \fIFBB::Table\fP and \fIFBB::TableBuf\fP
objects, handling some of their functionality\&. Users may derive classes from
\fITableSupport\fP, overriding its virtual members to determine the actual
layout of tables\&. By default the virtual members of \fITableSupport\fP do not
separate the columns of the table from each other\&.
.PP 
The Bobcat library offers the specialized class \fITableLines\fP extending the
basic facilities of \fITableSupport\fP, offering facilities to separate
rows by (partial) horizontal lines (cf\&. \fBtablelines\fP(3bobcat) for details)\&.
.PP 
More specialized handling can be realized by deriving new classes from
\fBFBB::TableSupport\fP, overriding members so that they implement the
programmer\(cq\&s intentions\&. An object of this derived class may be presented to a
\fIFBB::Table\fP or \fIFBB::TableBuf\fP constructor, to activate the special
handling\&.
.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 
.SH "ENUMERATION"

.PP 
The enum \fIColumnType\fP defines the following values (see also the
description of the \fIstruct HLine\fP, below):
.IP o 
\fBSKIP\fP:
.br 
a section of a row\-separating line should remain empty\&. This
value is normally not used by applications;
.IP o 
\fBUSE\fP:
.br 
a section of a row\-separating line should be used (e\&.g\&., by
writing a (horizontal) line);
.IP o 
\fBLEFT_FULL\fP:
.br 
a (horizontal) line should be written over the total width
of the separator to the left of a series of columns
.IP o 
\fBRIGHT_FULL\fP:
.br 
a (horizontal) line should be written over the total width
of the separator to the right of a series of columns;
.IP o 
\fBLEFT_MID\fP:
.br 
a (horizontal) line should be written over the right\-half
part of the width of the separator to the left of a series of
columns; the left\-hand part remains blank;
.IP o 
\fBRIGHT_MID\fP:
.br 
a (horizontal) line should be written over the left\-half
part of the width of the separator to the right of a series of
columns; the right\-hand part remains blank;

.PP 
The value \fISKIP\fP should always be used by itself; remaining values of
the enum may be combined using the binary or (\fI|\fP) operator\&.
.PP 
.SH "PUBLIC TYPE `HLine\(cq\&"

.PP 
.IP o 
\fBstruct HLine\fP:
.br 
This struct has the following fields:
.nf 

    size_t d_row;
    size_t d_begin;
    size_t d_end;
    size_t d_type;
        
.fi 
It offers two constructors:
.IP o 
\fBHLine(size_t row, size_t begin, size_t end)\fP:
.br 
.IP o 
\fBHLine(ColumnType type, size_t row, size_t begin, size_t end)\fP:
.br 
Objects of type \fBTableSupport::HLine\fP may be inserted into a
\fITableSupport\fP object to specify section(s) of a horizontal separator
between table rows that should be displayed or skipped\&. 
.IP 
E\&.g\&., to specify that a separator should be written 
.IP o 
in row 1,
.IP o 
from column 2 up to (not including) column 5, 
.IP o 
extending the separator to the left by half of the width of the
separator between columns 1 and 2, and to the right by the full width
of the separator between columns 4 and 5

.IP 
the following \fIHLine\fP object should be inserted into the 
\fITableSupport ts\fP object: 
.nf 
ts << HLine(LEFT_MID | RIGHT_FULL, 1, 2, 5);
.fi 
Multiple \fIHLine\fP objects may be inserted, in any order, into
\fITableSupport\fP objecta\&. When column ranges overlap then their \fIColumType\fPs
are merged\&.

.PP 
.SH "PROTECTED TYPES"

.PP 
.IP o 
\fBconst_iterator\fP:
.br 
The \fIconst_iterator\fP is defined in the class\(cq\&s protected
section\&. It is an input\-iterator returning iterators to \fIstruct
Field\fP (see below) objects  
.IP 
for table columns and column
separators (see below at the \fIbegin\fP and \fIend\fP members)
.IP 
.IP o 
\fBstruct Field\fP:
.br 
A \fIField\fP has two data members: \fIwidth\fP and \fItype\fP, representing,
respectively, the width and \fIColumnType\fP of a column or separating
column\&. The \fItype\fP values of \fIField\fP objects returned by
\fITableSupport\fP members only contain single values (like \fISKIP\fP or
\fILEFT_MID\fP) (note that column types can be combined when inserted
into \fITable\fP objects using \fIHLine\fP objects)\&.

.PP 
.SH "CONSTRUCTORS"

.PP 
The default, copy and move constructors as well as the copy and move
assignment operators are available\&.
.PP 
.SH "OVERLOADED OPERATORS"

.PP 
The following overloaded operators define separators between columns\&. The
first value inserted into a \fITableSupport\fP object defines the separator
before column 0, the next one defines the separator before column 1, etc,
until inserting separator \fInColumns + 1\fP, defining the separator to the
right of the table\(cq\&s last column\&. Inserting additional separators are ignored\&.
.IP o 
\fBTableSupport &operator<<(TableSupport &support, size_t width)\fP:
.br 
This operator defines a column\-separator of \fIwidth\fP space
characters\&. \fIWidth\fP may be zero, in which case no visible separator
is used;
.IP o 
\fBTableSupport &operator<<(TableSupport &support,
std::string const &text)\fP:
.br 
This operator defines a separator through text\&. The length of the
\fItext\fP defines the width of the separator\&. No separator is used when
\fItext\fP is empty;
.IP o 
\fBTableSupport &operator<<(TableSupport &support, HLine const &hsep)\fP:
.br 
This operator defines how a horizontal separator of a specified row
should be displayed (see the above description of \fIHLine\fP)\&.

.PP 
.SH "PUBLIC MEMBER FUNCTIONS"
.IP o 
\fBvoid hline(size_t row) const\fP:
.br 
When inserting a table into a \fIstd::ostream\fP \fITable\fP and
\fITableBuf\fP objects call this member just before the indicated row
(offset) is inserted into a \fIstd::ostream\fP\&. It calls the virtual
member \fIv_hline\fP, passing it \fIrow\fP\&. By default \fIv_hline\fP
performs no actions;
.IP o 
\fBvoid hline() const\fP:
.br 
When inserting a table into a \fIstd::ostream\fP \fITable\fP and
\fITableBuf\fP objects call this member just after inserting the table\(cq\&s
final row\&. It calls the virtual member \fIv_hline\fP without arguments,
which by default calls \fIhline(nRows)\fP;
.IP o 
\fBvoid setParam(std::ostream &ostr, size_t nRows, size_t nColumns,
std::vector<Align> const &align)\fP:
.br 
This member provides the \fITableSupport\fP object with values that are
essential for its proper functioning\&.  It is called by the \fITable\fP
and \fITableBuf\fP\(cq\&s \fIdef\fP member (and manipulator) to configure the
\fITableSupport\fP with alignment specifications, where
.br 
\fIostr\fP is a reference to the \fIstd::ostream\fP to receive the
table,
.br 
\fInRows\fP specifies  the table\(cq\&s number of rows,
.br 
\fInColumns\fP specifies  the table\(cq\&s number of columns,
.br 
\fIalign\fP is a reference to a constant vector of (column) alignment
specifications;
.IP o 
\fBvoid vline(size_t col) const\fP:
.br 
When inserting the data elements of the rows of a table into a
\fIstd::ostream\fP \fITable\fP and \fITableBuf\fP objects call this member
just before inserting the data elements of column \fIcol\fP\&.  Its task
is to write a column separator just before the data elements
themselves\&. It calls the virtual member \fIv_vline\fP passing it its
\fIcol\fP parameter\&. By default \fIv_vline\fP inserts the column separator
of column \fIcol\fP;
.IP o 
\fBvirtual void vline() const\fP:
.br 
When inserting a table into a \fIstd::ostream\fP \fITable\fP and
\fITableBuf\fP objects call this member after inserting the data
elements of the rows of the table\&. It is called at the end of each
row\&. It calls the virtual member \fIv_vline\fP without arguments, by
default calling \fIvline(nColumns)\fP and inserting a newline into the
\fIostream\fP;
.IP o 
\fBsize_t width() const\fP:
.br 
Returns the width of the table in number of characters\&. It may be
called before actually inserting the table into a stream\&.

.PP 
.SH "PROTECTED MEMBER FUNCTIONS"

.PP 
The following members are available to classes derived from
\fITableSupport\fP\&. Except for \fIsep\fP and \fIsepWidth\fP their values are only
defined after calling \fIsetParam\fP which is called
from the \fIdef\fP member or manipulator of \fITable\fP or \fITableBuf\fP objects\&.
.PP 
.IP o 
\fBstd::vector<Align> const &align() const\fP:
.br 
A reference to a vector of \fIAlign\fP objects, defining the alignments
and widths of the table\(cq\&s columns is returned\&.
.IP o 
\fBconst_iterator begin(size_t row) const\fP:
.br 
An iterator is returned containing information about the first column
element when displaying the horizontal separator before line \fIrow\fP\&.
Use argument \fInRows()\fP to obtain the information about the separator
beyond the last row\&.  The `column elements\(cq\& of the table consist of
its separators and data columns\&.
.br 
Dereferencing the returned \fIconst_iterator\fP returns a \fIField\fP
struct containing information about the width and type of a column
element\&. Dereferencing the iterator returned by \fIbegin\fP provides
information about the leftmost column separator\&. By incrementing the
iterator all subsequent column elements are visited\&. Dereferencing the
iterator is defined until the iterator has reached the value returned
by \fIend\fP (see below);
.IP o 
\fBsize_t colWidth(size_t col) const\fP:
.br 
The width of the indicated column is returned;
.IP o 
\fBconst_iterator end(size_t row) const\fP:
.br 
An iterator indicating the end of the iterator range starting at
\fIbegin(row)\fP is returned;
.IP o 
\fBsize_t nColumns() const\fP:
.br 
The table\(cq\&s number of columns is returned;
.IP o 
\fBsize_t nRows() const\fP:
.br 
The table\(cq\&s number of rows is returned;
.IP o 
\fBstd::ostream &out() const\fP:
.br 
A reference to the stream into which the table is inserted is
returned;
.IP o 
\fBstd::vector<std::string> const &sep()\fP:
.br 
A reference to the separators defined for the table\(cq\&s columns is
returned\&. Element \fIcol\fP refers to the separator to the left of the
table\(cq\&s column \fIcol\fP, element \fInColumns()\fP refers to the separator
to the right of the rightmost column;
.IP o 
\fBsize_t sepWidth(size_t col) const\fP:
.br 
The width of the indicated separator is returned\&. Element \fIcol\fP
refers to the separator to the left of the table column \fIcol\fP,
element \fInColumns()\fP refers to the separator to the right of the
rightmost table column\&.

.PP 
.SH "VIRTUAL MEMBER FUNCTIONS"

.PP 
The following member functions can be overridden by derived classes to
redefine the way horizontal and vertical separators are displayed\&.
.IP o 
\fBvirtual void v_hline(size_t row) const\fP:
.br 
This member is called from \fIhline(size_t row)\fP, receiving its \fIrow\fP
parameter\&. Its task is to write a horizonal separator before row
\fIrow\fP\&.  By default nothing is inserted\&. It may insert the horizontal
separator by iterating over the range defined by the \fIbegin\fP and
\fIend\fP members, deciding what to do on the basis of the \fIField\fP
objects made available by dereferencing the iterators\&. Alternatively, 
to let \fIv_hline\fP insert
a horizontal line spanning the full width of the table row the
following implementation can be used:
.nf 

    void Derived::v_hline(size_t row) const
    {
        out() << setfill(\(cq\&\-\(cq\&) << setw(width()) << \(dq\&\-\(dq\& << 
                                                setfill(\(cq\& \(cq\&);
    }
       
.fi 
.IP o 
\fBvirtual void v_hline() const\fP:
.br 
This member is called from \fIhline()\fP\&.  Its task is to write a
(partial) horizontal line beyond the table\(cq\&s last line\&. By default it
calls \fIhline(nRows)\fP;
.IP o 
\fBvirtual void v_vline(size_t col) const\fP:
.br 
This member is called from \fIvline(size_t col)\fP, receiving its \fIcol\fP
parameter\&. Its task is to write a separator before data column
\fIcol\fP\&. By default it inserts \fIseparator[col]\fP if available (if
that separator is not available then no separator is inserted before
column \fIcol\fP);
.IP o 
\fBvirtual void v_vline() const\fP:
.br 
This member is called from \fIvline()\fP at the end of each of the
table\(cq\&s rows\&.  Its task is to write a column separator, and to
terminate the table\(cq\&s line for which it is called\&. By default it
inserts the final column separator (if defined) and a newline
(\fI\en\fP) character\&.

.PP 
.SH "EXAMPLE"
See the example in the \fBtable\fP(3bobcat) man\-page\&.
.PP 
.SH "FILES"
\fIbobcat/tableSupport\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBalign\fP(3bobcat), \fBcsvtable\fP(3bobcat),
\fBtable\fP(3bobcat), \fBtablebuf\fP(3bobcat), \fBtablelines\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.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