Provided by: libbobcat-dev_4.08.06-1build1_amd64 bug

NAME

       FBB::Table  - Generates row- or column-wise filled tables from information inserted into a
       std::ostream

SYNOPSIS

       #include <bobcat/tablebuf>
       Linking option: -lbobcat

DESCRIPTION

       FBB::Tablebuf objects are std::streambuf 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 FBB::TableSupport object, described  in  a  separate  man-page
       (TableSupport(3bobcat)).  When  no  FBB::TableSupport  object is used, a plain row-wise or
       column-wise table is constructed which can be inserted into a std::ostream.  Displaying  a
       table (e.g., at the standard output stream) involves the following steps:

       o      Optionally, a  TableSupport object is created;

       o      A Tablebuf object is created (maybe passing it a TableSupport object);

       o      The Tablebuf object is used to initialize a std::ostream

       o      The   elements  of  the  table  are  filled  by  inserting  information  into  that
              std::ostream

       o      The Tablebuf itself contains the formatted table and may itself be inserted into  a
              std::ostream like std::cout.

       Tables defined by TableBuf 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 separators are defined. By  default
       the  separators are empty, but each separator may be given a (fixed) width or content. The
       separator before column col is addressed as separator  col,  the  rightmost  separator  is
       addressed as separator nColummns.

       Likewise,  rows  can  be separated from each other using separators. These separating rows
       are also empty by default. The row-separator before row row is addressed as  row-separator
       row.  The row-separator following the final row is addressed as row-separator nRows, where
       nRows is the value returned by the nRows member function.

       Non-default (i.e., non-empty) separators are defined using FBB::TableSupport objects  (cf.
       tablesupport(3bobcat)).

       TableBuf’s sister-class Table can be used to insert elements into a table in a more direct
       way. With TableBuf field separators are used to switch  to  the  next  table-element,  and
       (with  row-wise  filled tables) a row separator can be used to switch to the next row when
       it’s only partially defined. Instead,  with  Table  objects  each  new  insertion  defines
       another table element, and no wrapping std::ostream object is required.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       std::streambuf - allowing TableBuf objects to be wrapped in std::ostream objects.

       FBB::TableBase - This class implements common elements of the  table  implementation  (the
       FBB::TableBuf  class  is also derived from TableBase). The TableBase class is not intended
       to be used otherwise, and no separate man-page is provided.  All  facilities  provided  by
       Table inherited from TableBase are described in this man-page.

ENUMERATIONS

       The following enumerations are defined in the class FBB::Tablebuf.

       enum FillDirection
       This enumeration has two values:

       o      ROWWISE:
              When  this  value is specified at construction time, elements are added row-wise to
              the table. I.e., the second element inserted into the Table will be  found  in  the
              second column of the first row.

       o      COLUMNWISE:
              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.

       enum WidthType
       This enumeration holds two values:

       o      COLUMNWIDTH:
              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
              WidthType used by Table objects.

       o      EQUALWIDTH:
              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),

CONSTRUCTORS

       o      Tablebuf(size_t   nColumns,   Table::FillDirection   direction,    Table::WidthType
              widthType = Table::COLUMNWIDTH):
              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 Table object.  The
              direction parameter specifies the way new elements are added to the  Table  object:
              row-wise  or  column-wise.  Finally, the widthType 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.

       o      TableBuf(TableSupport      &tableSupport,      Table::FillDirection      direction,
              Table::WidthType widthType = Table::COLUMNWIDTH):
              This constructor operates identically to the previous constructor, but  expects  an
              additional  reference  to  a  TableSupport  object.  A  TableSupport  object offers
              additional formatting features used by the table defining elements like  horizontal
              lines  between  rows,  additional  separators, etc, etc. The TableSupport object is
              passed as a non-const reference as the Table object must be able to manipulate  its
              data. See tablesuppport(3bobcat) for more information about TableSupport.

OVERLOADED OPERATORS

       o      std::ostream &operator<<(std::ostream &out, TableBuf &tablebuf):
              This operator inserts a TableBuf into a std::ostream object. Note that the TableBuf
              object inserted into out is a non-const  object,  as  the  table  may  have  to  be
              completed  by  adding empty elements for missing ones. The out stream should not be
              equal to the std::ostream object that is used to wrap in a TableBuf object.

       o      TableBuf &operator<<(TableBuf &obj, Align const &align):
              This operator is used to change the default alignment of  either  a  column  or  an
              element.  It  is  a  wrapper  around  the  member  setAlign()  (see  below  for its
              description). By default, all elements are right-aligned.  See  align(3bobcat)  for
              more  information  about  the Align class. Unlike the insertion operators available
              for Table type objects, the insertion operator for TableBuf objects is only used to
              define  column  or  cell-alignment.   The  overloaded  assignment  operator  is not
              available.

MEMBER FUNCTIONS

       o      void clear():
              The contents of the table are erased. All existing elements are  removed,  and  the
              table will be empty.

       o      size_t nRows():
              The  currently available number of rows in the table is returned. Its value is only
              defined after calling def().

       o      TableBuf &setAlign(Align const &align):
              The alignment type of either a column or an  element  of  the  TableBuf  object  is
              defined   using   setAlign.  The  standard  alignments  std::left,  std::right  and
              std::internal may be specified, but in addition the alignment  FBB::center  may  be
              used if elements should be centered into their column. A construction like
              tab << Align(2, FBB::center)
              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
              tab << Align(2, 3, FBB::center)
              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.

       o      TableBuf &def():
              After  inserting  elements into a TableBuf 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 TableBuf object to a rectangular object, for which all column
              widths and alignments have been determined def may be called. It  is  automatically
              called  by  operator<<(ostream,  TableBuf).  In  other  situations it may be called
              explicitly to force  the  insertion  of  another  row  in  a  table  using  ROWWISE
              insertions.  With  COLUMNWISE insertions its working is complex, since new elements
              added to a COLUMNWISE filled table will reshuffle its  elements  over  the  table’s
              columns.

       o      setFieldSeparator(char fs):
              The  default  field  separator is the `backspace’ (\b) 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
              setFieldSeparator without argument disables the use of a field separator character,
              and only leaves the use of the fs manipulator to switch to the next field.

       o      setRowSeparator(char rs):
              The default row separator is the newline character (\n).   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  setRowSeparator  without  argument  disables  the  use  of a row separator
              character, and only leaves the use of the rs manipulator  to  switch  to  the  next
              field.

PROTECTED MEMBER FUNCTION

       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  Tablebuf  can,  in accordance with Liskov’s Substitution
       Principle, be used as a std:streambuf; but it also offers a facility for classes  deriving
       from Tablebuf. This facility is listed here.

       o      int pSync():
              The contents of the Tablebuf’s internal buffer is flushed.

MANPULATORS

       o      Table &def(Table &table):
              This  manipulator  can be inserted into a a TableBuf’s wrapping ostream to call the
              table’s def() member.

       o      FBB::fs:
              This manipulator can be inserted into a TableBuf’s wrapping ostream  to  switch  to
              the  next  field  of  the  table. It is an alternative to using the field separator
              character.

       o      FBB::rs:
              This manipulator can be inserted into a TableBuf’s wrapping ostream  to  switch  to
              the  next  row  of  the  table.  It  is  an  alternative to using the row separator
              character.

EXAMPLE

       #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, "\b"));

           cout << tab << ’\n’;            // complete the table and insert
       }

FILES

       bobcat/tablebuf - defines the class interface;

SEE ALSO

       bobcat(7),        align(3bobcat),        manipulator(3bobcat),        tablelines(3bobcat),
       tablesupport(3bobcat), table(3bobcat)

BUGS

       Note  that  def()  will  reshuffle elements over the table’s columns when new elements are
       added to the table subsequent to calling def()

DISTRIBUTION FILES

       o      bobcat_4.08.06-x.dsc: detached signature;

       o      bobcat_4.08.06-x.tar.gz: source archive;

       o      bobcat_4.08.06-x_i386.changes: change log;

       o      libbobcat1_4.08.06-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.06-x_*.deb: debian package holding the libraries,  headers  and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This  is  free  software,  distributed  under  the terms of the GNU General Public License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).