includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::TableSupport)(3bobcat)(_CurYrs_)
    (libbobcat-dev__CurVers_)(Table Support Base class)

manpagename(FBB::TableSupport)(Defines protocols for Table-support classes)

manpagesynopsis()
    bf(#include <bobcat/tableSupport>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    bf(FBB::TableSupport) is used by tt(FBB::Table) and tt(FBB::TableBuf)
objects, handling some of their functionality. Users may derive classes from
tt(TableSupport), overriding its virtual members to determine the actual
layout of tables. By default the virtual members of tt(TableSupport) do not
separate the columns of the table from each other.

The Bobcat library offers the specialized class tt(TableLines) extending the
basic facilities of tt(TableSupport), offering facilities to separate
rows by (partial) horizontal lines (cf. bf(tablelines)(3bobcat) for details).

   More specialized handling can be realized by deriving new classes from
bf(FBB::TableSupport), overriding members so that they implement the
programmer's intentions. An object of this derived class may be presented to a
tt(FBB::Table) or tt(FBB::TableBuf) constructor, to activate the special
handling.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

manpagesection(ENUMERATION)

    The enum tt(ColumnType) defines the following values (see also the
description of the tt(struct HLine), below):
    itemization(
    itb(SKIP)   a section of a row-separating line should remain empty. This
                value is normally not used by applications;
    itb(USE)    a section of a row-separating line should be used (e.g., by
                  writing a (horizontal) line);
    itb(LEFT_FULL) a (horizontal) line should be written over the total width
                of the separator to the left of a series of columns
    itb(RIGHT_FULL) a (horizontal) line should be written over the total width
                of the separator to the right of a series of columns;
    itb(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;
    itb(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 tt(SKIP) should always be used by itself; remaining values of
the enum may be combined using the binary or (tt(|)) operator.

manpagesection(PUBLIC TYPE `HLine')

    itemization(
    itb(struct HLine)
        This struct has the following fields:
        verb(
    size_t d_row;
    size_t d_begin;
    size_t d_end;
    size_t d_type;
        )
    It offers two constructors:
        itemization(
        itb(HLine(size_t row, size_t begin, size_t end))
        itb(HLine(ColumnType type, size_t row, size_t begin, size_t end))
        )
    Objects of type bf(TableSupport::HLine) may be inserted into a
tt(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 
    itemization(
    it() in row 1,
    it() from column 2 up to (not including) column 5, 
    it() 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 tt(HLine) object should be inserted into the 
tt(TableSupport ts) object: 
        verb(ts << HLine(LEFT_MID | RIGHT_FULL, 1, 2, 5);)
    Multiple tt(HLine) objects may be inserted, in any order, into
tt(TableSupport) objecta. When column ranges overlap then their tt(ColumType)s
are merged.
    )

manpagesection(PROTECTED TYPES)

    itemization(
    itb(const_iterator)
       The tt(const_iterator) is defined in the class's protected
        section. It is an input-iterator returning iterators to tt(struct
        Field) (see below) objects  

        for table columns and column
        separators (see below at the tt(begin) and tt(end) members)

    itb(struct Field)
       A tt(Field) has two data members: tt(width) and tt(type), representing,
        respectively, the width and tt(ColumnType) of a column or separating
        column. The tt(type) values of tt(Field) objects returned by
        tt(TableSupport) members only contain single values (like tt(SKIP) or
        tt(LEFT_MID)) (note that column types can be combined when inserted
        into tt(Table) objects using tt(HLine) objects).
    )

manpagesection(CONSTRUCTORS)

    The default, copy and move constructors as well as the copy and move
assignment operators are available.

manpagesection(OVERLOADED OPERATORS)

    The following overloaded operators define separators between columns. The
first value inserted into a tt(TableSupport) object defines the separator
before column 0, the next one defines the separator before column 1, etc,
until inserting separator tt(nColumns + 1), defining the separator to the
right of the table's last column. Inserting additional separators are ignored.
    itemization(
    itb(TableSupport &operator<<(TableSupport &support, size_t width))
       This operator defines a column-separator of tt(width) space
        characters. tt(Width) may be zero, in which case no visible separator
        is used;
    itb(TableSupport &operator<<(TableSupport &support,
                                                std::string const &text))
       This operator defines a separator through text. The length of the
        tt(text) defines the width of the separator. No separator is used when
        tt(text) is empty;
    itb(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 tt(HLine)).
    )

manpagesection(PUBLIC MEMBER FUNCTIONS)
    itemization(
    itb(void hline(size_t row) const)
       When inserting a table into a tt(std::ostream) tt(Table) and
        tt(TableBuf) objects call this member just before the indicated row
        (offset) is inserted into a tt(std::ostream). It calls the virtual
        member tt(v_hline), passing it tt(row). By default tt(v_hline)
        performs no actions;
    itb(void hline() const)
       When inserting a table into a tt(std::ostream) tt(Table) and
        tt(TableBuf) objects call this member just after inserting the table's
        final row. It calls the virtual member tt(v_hline) without arguments,
        which by default calls tt(hline(nRows));
    itb(void setParam(std::ostream &ostr, size_t nRows, size_t nColumns,
                        std::vector<Align> const &align))
       This member provides the tt(TableSupport) object with values that are
        essential for its proper functioning.  It is called by the tt(Table)
        and tt(TableBuf)'s tt(def) member (and manipulator) to configure the
        tt(TableSupport) with alignment specifications, where+nl()
       tt(ostr) is a reference to the tt(std::ostream) to receive the
        table,nl()
       tt(nRows) specifies  the table's number of rows,nl()
       tt(nColumns) specifies  the table's number of columns,nl()
       tt(align) is a reference to a constant vector of (column) alignment
        specifications;
    itb(void vline(size_t col) const)
       When inserting the data elements of the rows of a table into a
        tt(std::ostream) tt(Table) and tt(TableBuf) objects call this member
        just before inserting the data elements of column tt(col).  Its task
        is to write a column separator just before the data elements
        themselves. It calls the virtual member tt(v_vline) passing it its
        tt(col) parameter. By default tt(v_vline) inserts the column separator
        of column tt(col);
    itb(virtual void vline() const)
       When inserting a table into a tt(std::ostream) tt(Table) and
        tt(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 tt(v_vline) without arguments, by
        default calling tt(vline(nColumns)) and inserting a newline into the
        tt(ostream);
    itb(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.
    )

manpagesection(PROTECTED MEMBER FUNCTIONS)

    The following members are available to classes derived from
tt(TableSupport). Except for tt(sep) and tt(sepWidth) their values are only
defined after calling tt(setParam) which is called
from the tt(def) member or manipulator of tt(Table) or tt(TableBuf) objects.

    itemization(
    itb(std::vector<Align> const &align() const)
       A reference to a vector of tt(Align) objects, defining the alignments
        and widths of the table's columns is returned.
    itb(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 tt(row).
        Use argument tt(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.nl()
       Dereferencing the returned tt(const_iterator) returns a tt(Field)
        struct containing information about the width and type of a column
        element. Dereferencing the iterator returned by tt(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 tt(end) (see below);
    itb(size_t colWidth(size_t col) const)
       The width of the indicated column is returned;
    itb(const_iterator end(size_t row) const)
       An iterator indicating the end of the iterator range starting at
        tt(begin(row)) is returned;
    itb(size_t nColumns() const)
       The table's number of columns is returned;
    itb(size_t nRows() const)
        The table's number of rows is returned;
    itb(std::ostream &out() const)
       A reference to the stream into which the table is inserted is
        returned;
    itb(std::vector<std::string> const &sep())
       A reference to the separators defined for the table's columns is
        returned. Element tt(col) refers to the separator to the left of the
        table's column tt(col), element tt(nColumns()) refers to the separator
        to the right of the rightmost column;
    itb(size_t sepWidth(size_t col) const)
       The width of the indicated separator is returned. Element tt(col)
        refers to the separator to the left of the table column tt(col),
        element tt(nColumns()) refers to the separator to the right of the
        rightmost table column.
    )

manpagesection(VIRTUAL MEMBER FUNCTIONS)

    The following member functions can be overridden by derived classes to
redefine the way horizontal and vertical separators are displayed.
    itemization(
    itb(virtual void v_hline(size_t row) const)
       This member is called from tt(hline(size_t row)), receiving its tt(row)
        parameter. Its task is to write a horizonal separator before row
        tt(row).  By default nothing is inserted. It may insert the horizontal
        separator by iterating over the range defined by the tt(begin) and
        tt(end) members, deciding what to do on the basis of the tt(Field)
        objects made available by dereferencing the iterators. Alternatively, 
        to let tt(v_hline) insert
        a horizontal line spanning the full width of the table row the
        following implementation can be used:
       verb(
    void Derived::v_hline(size_t row) const
    {
        out() << setfill('-') << setw(width()) << "-" << 
                                                setfill(' ');
    }
       )
    itb(virtual void v_hline() const)
       This member is called from tt(hline()).  Its task is to write a
        (partial) horizontal line beyond the table's last line. By default it
        calls tt(hline(nRows));
    itb(virtual void v_vline(size_t col) const)
       This member is called from tt(vline(size_t col)), receiving its tt(col)
        parameter. Its task is to write a separator before data column
        tt(col). By default it inserts tt(separator[col]) if available (if
        that separator is not available then no separator is inserted before
        column tt(col));
    itb(virtual void v_vline() const)
       This member is called from tt(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
        (tt(\n)) character.
    )

manpagesection(EXAMPLE)
    See the example in the bf(table)(3bobcat) man-page.

manpagefiles()
    em(bobcat/tableSupport) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(align)(3bobcat), bf(csvtable)(3bobcat),
    bf(table)(3bobcat), bf(tablebuf)(3bobcat), bf(tablelines)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)