/usr/share/doc/libbobcat4-dev/man/tablebuf.3.html

<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::Table(3bobcat)</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    .XXfc {margin-left:auto;margin-right:auto;}
    .XXtc {text-align: center;}
    .XXtl {text-align: left;}
    .XXtr {text-align: right;}
    .XXvt {vertical-align: top;}
    .XXvb {vertical-align: bottom;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::Table(3bobcat)</h1>
<h2 id="author">Construct text tables<br/>(libbobcat-dev_4.08.02-x.tar.gz)</h2>
<h2 id="date">2005-2017</h2>


<p>
<h2 >NAME</h2>FBB::Table - Generates row- or column-wise filled tables from
information inserted into a std::ostream
<p>
<h2 >SYNOPSIS</h2>
    <strong >#include &lt;bobcat/tablebuf&gt;</strong><br/>
    Linking option: <em >-lbobcat</em> 
<p>
<h2 >DESCRIPTION</h2>
<p>
<strong >FBB::Tablebuf</strong> objects are <strong >std::streambuf</strong> objects that can be used
to create tables. The tables are filled either column-wise or row-wise. Many
of the table's characteristics may be fine-tuned by a separate
<strong >FBB::TableSupport</strong> object, described in a separate man-page
(<strong >TableSupport</strong>(3bobcat)). When no <strong >FBB::TableSupport</strong> object is used, a
plain row-wise or column-wise table is constructed which can be inserted into
a <strong >std::ostream</strong>. Displaying a table (e.g., at the standard output stream)
involves the following steps:
    <ul>
    <li> Optionally, a  <em >TableSupport</em> object is created;
    <li> A <em >Tablebuf</em> object is created (maybe passing it a <em >TableSupport</em>
object); 
    <li> The <em >Tablebuf</em> object is used to initialize a <em >std::ostream</em>
    <li> The elements of the table are filled by inserting information into
that <em >std::ostream</em>
    <li> The <em >Tablebuf</em> itself contains the formatted table and may itself
be inserted into a <em >std::ostream</em> like <em >std::cout</em>.
    </ul>
<p>
Tables defined by <em >TableBuf</em> 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 <em >separators</em> are defined. By default the separators are
empty, but each separator may be given a (fixed) width or content. The
separator before column <em >col</em> is addressed as separator <em >col</em>, the
rightmost separator is addressed as separator <em >nColummns</em>.
<p>
Likewise, rows can be separated from each other using separators. These
separating rows are also empty by default. The row-separator before row
<em >row</em> is addressed as row-separator <em >row</em>. The row-separator following the
final row is addressed as row-separator <em >nRows</em>, where <em >nRows</em> is the
value returned by the <em >nRows</em> member function.
<p>
Non-default (i.e., non-empty) separators are defined using
<em >FBB::TableSupport</em> objects (cf. <strong >tablesupport</strong>(3bobcat)).
<p>
<em >TableBuf</em>'s sister-class <em >Table</em> can be used to insert elements into a
table in a more direct way. With <em >TableBuf</em> <em >field separators</em> are used to
switch to the next table-element, and (with row-wise filled tables) a <em >row
separator</em> can be used to switch to the next row when it's only partially
defined. Instead, with <em >Table</em> objects each new insertion defines another
table element, and no wrapping <em >std::ostream</em> object is required.
<p>
<h2 >NAMESPACE</h2>
    <strong >FBB</strong><br/>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong >FBB</strong>.
<p>
<h2 >INHERITS FROM</h2>
<p>
<strong >std::streambuf</strong> - allowing <em >TableBuf</em> objects to be wrapped in
<em >std::ostream</em> objects.
<p>
<strong >FBB::TableBase</strong> - This class implements common elements of the
table implementation (the <em >FBB::TableBuf</em> class is also derived from
<em >TableBase</em>). The <em >TableBase</em> class is not intended to be used otherwise,
and no separate man-page is provided. All facilities provided by <em >Table</em>
inherited from <em >TableBase</em> are described in this man-page.
<p>
<h2 >ENUMERATIONS</h2>
    The following enumerations are defined in the class <strong >FBB::Tablebuf</strong>.
<p>
<strong >enum FillDirection</strong><br/>
    This enumeration has two values:
    <ul>
    <li> <strong >ROWWISE</strong>:<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 <strong >Table</strong>
will be found in the second column of the first row.
    <li> <strong >COLUMNWISE</strong>:<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.
    </ul>
<p>
<strong >enum WidthType</strong><br/>
    This enumeration holds two values:
    <ul>
    <li> <strong >COLUMNWIDTH</strong>:<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 <strong >WidthType</strong> used by <strong >Table</strong> objects. 
    <li> <strong >EQUALWIDTH</strong>:<br/>
        This value may be specified when all the table's columns should have
equal width (i.e., equal to the width of the widest table element), 
    </ul>
<p>
<h2 >CONSTRUCTORS</h2>
    <ul>
    <li> <strong >Tablebuf(size_t nColumns, Table::FillDirection direction,
            Table::WidthType widthType = Table::COLUMNWIDTH)</strong>:<br/>
        The table'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 <strong >Table</strong> object.  The <strong >direction</strong> parameter specifies the way new
elements are added to the <strong >Table</strong> object: row-wise or column-wise. Finally,
the <em >widthType</em> parameter is used to specify the way the width of the
table's columns is determined. Each column either defines its own width or all
columns have equal widths.
    <li> <strong >TableBuf(TableSupport &amp;tableSupport, Table::FillDirection direction,
            Table::WidthType widthType = Table::COLUMNWIDTH)</strong>:<br/>
        This constructor operates identically to the previous constructor, but
expects an additional reference to a <strong >TableSupport</strong> object. A
<strong >TableSupport</strong> object offers additional formatting features used by the
table defining elements like horizontal lines between rows, additional
separators, etc, etc. The <strong >TableSupport</strong> object is passed as a non-const
reference as the <strong >Table</strong> object must be able to manipulate its data. See
<strong >tablesuppport</strong>(3bobcat) for more information about <em >TableSupport</em>.
    </ul>
<p>
<h2 >OVERLOADED OPERATORS</h2>
<p>
<ul>
    <li> <strong >std::ostream &amp;operator&lt;&lt;(std::ostream &amp;out, TableBuf &amp;tablebuf)</strong>:<br/>
        This operator inserts a <strong >TableBuf</strong> into a <em >std::ostream</em>
object. Note that the <em >TableBuf</em> object inserted into <em >out</em> is a non-const
object, as the table may have to be completed by adding empty elements for
missing ones. The <em >out</em> stream should not be equal to the <em >std::ostream</em>
object that is used to wrap in a <em >TableBuf</em> object. 
    <li> <strong >TableBuf &amp;operator&lt;&lt;(TableBuf &amp;obj, Align const &amp;align)</strong>:<br/>
        This operator is used to change the default alignment of either a
column or an element. It is a wrapper around the member <em >setAlign()</em> (see
below for its description). By default, all elements are right-aligned. See
<strong >align</strong>(3bobcat) for more information about the <em >Align</em> class. Unlike the
insertion operators available for <em >Table</em> type objects, the insertion
operator for <em >TableBuf</em> objects is only used to define column or
cell-alignment.
    </ul>
    The overloaded assignment operator is not available.
<p>
<h2 >MEMBER FUNCTIONS</h2>
    <ul>
    <li> <strong >void clear()</strong>:<br/>
        The contents of the table are erased. All existing elements are
removed, and the table will be empty.
    <li> <strong >size_t nRows()</strong>:<br/>
        The currently available number of rows in the table is returned. Its
value is only defined after calling <strong >def()</strong>.
    <li> <strong >TableBuf &amp;setAlign(Align const &amp;align)</strong>:<br/>
        The alignment type of either a column or an element of the <strong >TableBuf</strong>
object is defined using <em >setAlign</em>. The standard alignments <em >std::left,
std::right</em> and <em >std::internal</em> may be specified, but in addition the
alignment <em >FBB::center</em> may be used if elements should be centered into
their column. A construction like
        <pre>
tab &lt;&lt; Align(2, FBB::center)
</pre>

    requests centering of all elements in the table's column having index
value 2 (i.e., the table's 3rd column), whereas a construction like
        <pre>
tab &lt;&lt; Align(2, 3, FBB::center)
</pre>

    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.
    <li> <strong >TableBuf &amp;def()</strong>:<br/>
        After inserting elements into a <em >TableBuf</em> object its number of
elements may or may not be an integral multiple of the number of columns
specified at construction time. To `complete' a <strong >TableBuf</strong> object to a
rectangular object, for which all column widths and alignments have been
determined <em >def</em> may be called. It is automatically called by
<em >operator&lt;&lt;(ostream, TableBuf)</em>. In other situations it may be called
explicitly to force the insertion of another row in a table using <em >ROWWISE</em>
insertions. With <em >COLUMNWISE</em> insertions its working is complex, since new
elements added to a <em >COLUMNWISE</em> filled table will reshuffle its elements
over the table's columns.
    <li> <strong >setFieldSeparator(char fs)</strong>:<br/>
        The default field separator is the `backspace' (<em >\b</em>)
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 <em >setFieldSeparator</em> without argument
disables the use of a field separator character, and only leaves the use of
the <em >fs</em> manipulator to switch to the next field.
    <li> <strong >setRowSeparator(char rs)</strong>:<br/>
        The default row separator is the newline character (<em >\n</em>).  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 <em >setRowSeparator</em> without argument disables the
use of a row separator character, and only leaves the use of the <em >rs</em>
manipulator to switch to the next field.
    </ul>
<p>
<h2 >PROTECTED MEMBER FUNCTION</h2>
<p>
The member listed in this section implements the tasks of the comparably
named virtual function in the class's private interface. This separates the
redefinable interface from the user-interface. The class <strong >Tablebuf</strong>
can, in accordance with Liskov's Substitution Principle, be used as a
<em >std:streambuf</em>; but it also offers a facility for classes deriving from
<strong >Tablebuf</strong>. This facility is listed here.
    <ul>
    <li> <strong >int pSync()</strong>:<br/>
        The contents of the <strong >Tablebuf</strong>'s internal buffer is flushed.
    </ul>
<p>
<h2 >MANPULATORS</h2>
    <ul>
    <li> <strong >Table &amp;def(Table &amp;table)</strong>:<br/>
        This manipulator can be inserted into a a <em >TableBuf</em>'s wrapping
<em >ostream</em> to call the table's <strong >def()</strong> member.
    <li> <strong >FBB::fs</strong>:<br/>
        This manipulator can be inserted into a <em >TableBuf</em>'s wrapping 
<em >ostream</em> to switch to the next field of the table. It is an alternative to
using the field separator character.
    <li> <strong >FBB::rs</strong>:<br/>
        This manipulator can be inserted into a <em >TableBuf</em>'s wrapping 
<em >ostream</em> to switch to the next row of the table. It is an alternative to
using the row separator character.
    </ul>
<p>
<h2 >EXAMPLE</h2>
<p>
<pre >
#include &lt;iostream&gt;
#include &lt;ostream&gt;
#include &lt;string&gt;
#include &lt;algorithm&gt;
#include &lt;iterator&gt;

#include &lt;bobcat/tablebuf&gt;
#include &lt;bobcat/tablelines&gt;

using namespace std;
using namespace FBB;

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


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

    ostream out(&amp;tab);

    copy(istream_iterator&lt;string&gt;(cin), istream_iterator&lt;string&gt;(),
            ostream_iterator&lt;string&gt;(out, "\b"));

    cout &lt;&lt; tab &lt;&lt; '\n';            // complete the table and insert
}

</pre>

<p>
<h2 >FILES</h2>
    <em >bobcat/tablebuf</em> - defines the class interface;<br/>
<p>
<h2 >SEE ALSO</h2>
    <strong >bobcat</strong>(7), <strong >align</strong>(3bobcat), <strong >manipulator</strong>(3bobcat),
    <strong >tablelines</strong>(3bobcat), <strong >tablesupport</strong>(3bobcat), <strong >table</strong>(3bobcat)
<p>
<h2 >BUGS</h2>
    Note that <em >def()</em> will reshuffle elements over the table's
columns when new elements are added to the table subsequent to calling
<em >def()</em>
<p>

<h2 >DISTRIBUTION FILES</h2>
    <ul>
    <li> <em >bobcat_4.08.02-x.dsc</em>: detached signature;
    <li> <em >bobcat_4.08.02-x.tar.gz</em>: source archive;
    <li> <em >bobcat_4.08.02-x_i386.changes</em>: change log;
    <li> <em >libbobcat1_4.08.02-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em >libbobcat1-dev_4.08.02-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em >http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2 >BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2 >COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2 >AUTHOR</h2>
    Frank B. Brokken (<strong >f.b.brokken@rug.nl</strong>).
<p>
</body>
</html>
libbobcat-dev 4.08.02-2build1 / usr / share / doc / libbobcat4-dev / man / tablebuf.3.html
