FBB::TableSupport - Defines protocols for Table-support
classes
#include <bobcat/tableSupport>
Linking option: -lbobcat
FBB::TableSupport is used by FBB::Table and
FBB::TableBuf objects, handling some of their functionality. Users
may derive classes from TableSupport, overriding its virtual members
to determine the actual layout of tables. By default the virtual members of
TableSupport do not separate the columns of the table from each
other.
The Bobcat library offers the specialized class TableLines
extending the basic facilities of TableSupport, offering facilities
to separate rows by (partial) horizontal lines (cf.
tablelines(3bobcat) for details).
More specialized handling can be realized by deriving new classes
from FBB::TableSupport, overriding members so that they implement the
programmer’s intentions. An object of this derived class may be
presented to a FBB::Table or FBB::TableBuf constructor, to
activate the special handling.
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
The enum ColumnType defines the following values (see also
the description of the struct HLine, below):
- o
- SKIP:
a section of a row-separating line should remain empty. This value is
normally not used by applications;
- o
- USE:
a section of a row-separating line should be used (e.g., by writing a
(horizontal) line);
- o
- LEFT_FULL:
a (horizontal) line should be written over the total width of the separator
to the left of a series of columns
- o
- RIGHT_FULL:
a (horizontal) line should be written over the total width of the separator
to the right of a series of columns;
- o
- LEFT_MID:
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;
- o
- RIGHT_MID:
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;
The value SKIP should always be used by itself; remaining
values of the enum may be combined using the binary or (|)
operator.
- o
- struct HLine:
This struct has the following fields:
size_t d_row;
size_t d_begin;
size_t d_end;
size_t d_type;
It offers two constructors:
- o
- HLine(size_t row, size_t begin, size_t end):
- o
- HLine(ColumnType type, size_t row, size_t begin, size_t end):
Objects of type TableSupport::HLine may be inserted into a
TableSupport object to specify section(s) of a horizontal separator
between table rows that should be displayed or skipped.
- E.g., to specify that a separator should be written
- o
- in row 1,
- o
- from column 2 up to (not including) column 5,
- 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
- the following HLine object should be inserted into the
TableSupport ts object:
ts << HLine(LEFT_MID | RIGHT_FULL, 1, 2, 5);
Multiple HLine objects may be inserted, in any order, into
TableSupport objecta. When column ranges overlap then their
ColumTypes are merged.
- o
- const_iterator:
The const_iterator is defined in the class’s protected
section. It is an input-iterator returning iterators to struct
Field (see below) objects
- for table columns and column separators (see below at the begin and
end members)
- o
- struct Field:
A Field has two data members: width and type,
representing, respectively, the width and ColumnType of a column or
separating column. The type values of Field objects returned
by TableSupport members only contain single values (like
SKIP or LEFT_MID) (note that column types can be combined
when inserted into Table objects using HLine objects).
The default, copy and move constructors as well as the copy and
move assignment operators are available.
The following overloaded operators define separators between
columns. The first value inserted into a TableSupport object defines
the separator before column 0, the next one defines the separator before
column 1, etc, until inserting separator nColumns + 1, defining the
separator to the right of the table’s last column. Inserting
additional separators are ignored.
- o
- TableSupport &operator<<(TableSupport &support, size_t
width):
This operator defines a column-separator of width space characters.
Width may be zero, in which case no visible separator is used;
- o
- TableSupport &operator<<(TableSupport &support,
std::string const &text):
This operator defines a separator through text. The length of the
text defines the width of the separator. No separator is used when
text is empty;
- o
- TableSupport &operator<<(TableSupport &support, HLine
const &hsep):
This operator defines how a horizontal separator of a specified row should
be displayed (see the above description of HLine).
- o
- void hline(size_t row) const:
When inserting a table into a std::ostream Table and
TableBuf objects call this member just before the indicated row
(offset) is inserted into a std::ostream. It calls the virtual
member v_hline, passing it row. By default v_hline
performs no actions;
- o
- void hline() const:
When inserting a table into a std::ostream Table and
TableBuf objects call this member just after inserting the
table’s final row. It calls the virtual member v_hline
without arguments, which by default calls hline(nRows);
- o
- void setParam(std::ostream &ostr, size_t nRows, size_t
nColumns, std::vector<Align> const &align):
This member provides the TableSupport object with values that are
essential for its proper functioning. It is called by the Table and
TableBuf’s def member (and manipulator) to configure
the TableSupport with alignment specifications, where
ostr is a reference to the std::ostream to receive the table,
nRows specifies the table’s number of rows,
nColumns specifies the table’s number of columns,
align is a reference to a constant vector of (column) alignment
specifications;
- o
- void vline(size_t col) const:
When inserting the data elements of the rows of a table into a
std::ostream Table and TableBuf objects call this
member just before inserting the data elements of column col. Its
task is to write a column separator just before the data elements
themselves. It calls the virtual member v_vline passing it its
col parameter. By default v_vline inserts the column
separator of column col;
- o
- virtual void vline() const:
When inserting a table into a std::ostream Table and
TableBuf 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 v_vline without arguments, by default calling
vline(nColumns) and inserting a newline into the
ostream;
- o
- size_t width() const:
Returns the width of the table in number of characters. It may be called
before actually inserting the table into a stream.
The following members are available to classes derived from
TableSupport. Except for sep and sepWidth their values
are only defined after calling setParam which is called from the
def member or manipulator of Table or TableBuf
objects.
- o
- std::vector<Align> const &align() const:
A reference to a vector of Align objects, defining the alignments and
widths of the table’s columns is returned.
- o
- const_iterator begin(size_t row) const:
An iterator is returned containing information about the first column
element when displaying the horizontal separator before line row.
Use argument nRows() to obtain the information about the separator
beyond the last row. The `column elements’ of the table consist of
its separators and data columns.
Dereferencing the returned const_iterator returns a Field
struct containing information about the width and type of a column
element. Dereferencing the iterator returned by begin 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
end (see below);
- o
- size_t colWidth(size_t col) const:
The width of the indicated column is returned;
- o
- const_iterator end(size_t row) const:
An iterator indicating the end of the iterator range starting at
begin(row) is returned;
- o
- size_t nColumns() const:
The table’s number of columns is returned;
- o
- size_t nRows() const:
The table’s number of rows is returned;
- o
- std::ostream &out() const:
A reference to the stream into which the table is inserted is returned;
- o
- std::vector<std::string> const &sep():
A reference to the separators defined for the table’s columns is
returned. Element col refers to the separator to the left of the
table’s column col, element nColumns() refers to the
separator to the right of the rightmost column;
- o
- size_t sepWidth(size_t col) const:
The width of the indicated separator is returned. Element col refers
to the separator to the left of the table column col, element
nColumns() refers to the separator to the right of the rightmost
table column.
The following member functions can be overridden by derived
classes to redefine the way horizontal and vertical separators are
displayed.
- o
- virtual void v_hline(size_t row) const:
This member is called from hline(size_t row), receiving its
row parameter. Its task is to write a horizonal separator before
row row. By default nothing is inserted. It may insert the
horizontal separator by iterating over the range defined by the
begin and end members, deciding what to do on the basis of
the Field objects made available by dereferencing the iterators.
Alternatively, to let v_hline insert a horizontal line spanning the
full width of the table row the following implementation can be used:
void Derived::v_hline(size_t row) const
{
out() << setfill(’-’) << setw(width()) << "-" <<
setfill(’ ’);
}
- o
- virtual void v_hline() const:
This member is called from hline(). Its task is to write a (partial)
horizontal line beyond the table’s last line. By default it calls
hline(nRows);
- o
- virtual void v_vline(size_t col) const:
This member is called from vline(size_t col), receiving its
col parameter. Its task is to write a separator before data column
col. By default it inserts separator[col] if available (if
that separator is not available then no separator is inserted before
column col);
- o
- virtual void v_vline() const:
This member is called from vline() at the end of each of the
table’s rows. Its task is to write a column separator, and to
terminate the table’s line for which it is called. By default it
inserts the final column separator (if defined) and a newline (\n)
character.
bobcat/tableSupport - defines the class interface
- o
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_6.02.02-x.dsc: detached signature;
- o
- bobcat_6.02.02-x.tar.gz: source archive;
- o
- bobcat_6.02.02-x_i386.changes: change log;
- o
- libbobcat1_6.02.02-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_6.02.02-x_*.deb: debian package containing the
libraries, headers and manual pages;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).