.TH "FBB::OFoldStream" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "Fold long lines"

.PP 
.SH "NAME"
FBB::OFoldStream \- Folds long lines
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/ofoldstream>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::OFoldStream\fP folds long lines written to it\&. The
\fIOFoldStream\fP writes the (folded) lines to a second \fIostream\fP which is
either used by or opened by the \fIOFoldStream\fP object\&.
.PP 
\fIOFoldStream\fP objects never fold lines in the middle of series of
non\-blank characters but will always break a line at white space
characters\&. The resulting lines will always appear to the right of a
configurable left margin and to the left of a configurable right margin\&. There
is a somewhat pathological exception to this: if a word is too long to fit in
between the margins then the word will exceed the right hand margin\&.
.PP 
The indentation used for the left margins is configurable to either blanks
(the default) or tabs\&. When tabs are used the width of a tab character is
configurable, using a default of 8 positions in the destination stream\&.
.PP 
\fIOFoldStream\fP is implemented as a wrapper class around \fIstd::ostream\fP
and \fIFBB::OFoldBuf\fP and a more complete description of the folding
process can be found in the \fBofoldbuf\fP(3bobcat) man page\&.
.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"
std::ostream,
.br 
(and privately from FBB::OFoldBuf)
.PP 
.SH "ENUMERATION"
The enumeration \fITabsOrBlanks\fP is used to select tabs or blanks when
writing the indentation\&. The default is blanks\&. When tabs are selected the
display width of tabs characters can be configured as well (using the default
of 8 positions for each tab\-character)\&. The enumeration has two values:
.IP o 
\fBBLANKS\fP:
.br 
The default, indicating that the left margin is specified and written
as a number of blanks;
.IP o 
\fBTABS\fP:
.br 
Indicating that the left margin is specified and written as a number
of tab\-characters\&.

.PP 
The enumeration \fITrailingBlanks\fP is used to configure the
\fIOFoldStream\fP object with respect to any trailing blanks that may appear
on the final line\&. It is the same enumeration type as used with
\fIOFoldBuf\fP (cf\&. \fBofoldbuf\fP(3bobcat)) having two values:
.IP o 
\fBIGNORE_TRAILING_BLANKS\fP:
.br 
This indicates that trailing blanks appearing at the final line if it
is not terminated by a newline should not be written to the destination
\fIstd::ostream\fP\&. This is the default used by \fIOFoldStream\fP objects\&.
.IP o 
\fBKEEP_TRAILING_BLANKS\fP:
.br 
This indicates that trailing blanks at the final line if it is not
terminated by a newline should be written to the destination \fIstd::ostream\fP

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBOFoldStream()\fP:
.br 
This constructor initializes an \fIOFoldStream\fP object but does not
associate it with a destination stream\&. It uses the values 0, 80, \fIBLANKS\fP,
and \fIIGNORE_TRAILING_BLANKS\fPfor, resp\&. its left margin, right margin
left\-margin characters and \fITrailingBlanks\fP handling mode\&.
.IP 
.IP o 
\fBOFoldStream(char const *fname,
size_t leftIndent = 0, size_t rightMargin = 80,
TabsOrBlanks tob = BLANKS,
TrailingBlanks tb = IGNORE_TRAILING_BLANKS)\fP:
.br 
This constructor initializes an \fIOFoldStream\fP object and opens (using
\fIstd::ios::out\fP) the destination stream using the name specified as its
\fIfname\fP argument\&.
.IP 
.IP o 
\fBOFoldStream(std::ostream &stream,
size_t leftIndent = 0, size_t rightMargin = 80,
TabsOrBlanks tob = BLANKS,
TrailingBlanks tb = IGNORE_TRAILING_BLANKS)\fP:
.br 
This constructor initializes an \fIOFoldStream\fP object and uses as its
destination stream the \fIstd::ostream stream\fP\&.

.PP 
The destructor writes any buffered information to the destination stream
and will then flush the destination stream\&.
.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fBstd::ostream\fP are available, as \fBFBB::OFoldStream\fP
inherits from this class\&.
.IP o 
\fBvoid close()\fP:
.br 
This member flushes any pending information to the destination stream
and then closes the destination stream\&.
.IP 
.IP o 
\fBvoid open(char const *fname, openmode mode = std::ios::out)\fP:
.br 
This member associates the \fIOFilterStream\fP object with an
\fIstd::ofstream\fP object whose filename is provided and that should receive
the folded information\&.
.IP 
.IP o 
\fBvoid open(std::ostream &out)\fP:
.br 
This member associates the \fIOFilterStream\fP object with the provided
\fIostream\fP object\&.
.IP 
.IP o 
\fBvoid setMargins(size_t leftMargin, size_t rightMargin)\fP:
.br 
This member can be used to modify the left\- and right folding
margins\&. Note that the left margin may also be modified using the \fIFBB::lm\fP
and \fIFBB::mlm\fP manipulators\&.
.IP 
.IP o 
\fBvoid setTrailingBlanks(TrailingBlanks tb)\fP:
.br 
This member can be used to modify the currently used
\fITrailingBlanks\fP parameter\&.
.IP 
.IP o 
\fBvoid useBlanks()\fP:
.br 
This member can be used to select blanks  to be used when inserting
left margins\&.
.IP 
.IP o 
\fBvoid useTabs(size_t tabWidth = 8)\fP:
.br 
This member can be used to select tab\-characters to be used when
inserting left margins\&. The second parameter is used to specify the display
width of a tab\-character\&.

.PP 
.SH "STATIC MEMBER FUNCTIONS"

.PP 
.IP o 
\fBsize_t leftMargin(std::ostream const &os)\fP:
.br 
This member returns the current left margin setting of the
\fIOFoldStream\fP object passed to it as its argument\&. The member defines a
\fIstd::ostream\fP parameter since in many cases the \fIOFoldStream\fP object will
be used in functions themselves defining \fIstd::ostream\fP
parameters\&. Internally, the \fIstd::ostream\fP\(cq\&s \fIstd::streambuf\fP is down cast
to an \fIOFoldBuf\fP and an \fIFBB::Exception\fP exception is thrown if that
cast fails\&.
.IP o 
\fBsize_t rightMargin(std::ostream const &os)\fP:
.br 
This member returns the current right margin setting of the
\fIOFoldStream\fP object passed to it as its argument\&. The member\(cq\&s parameter is
down cast in the same way as \fIleftMargin()\fP\(cq\&s argument: an \fIFBB::Exception\fP
exception is thrown if that cast fails\&.

.PP 
.SH "EXAMPLE"
.nf 
#include <iostream>
#include <string>
#include <bobcat/ofoldstream>

using namespace std;
using namespace FBB;

void margins(ostream &out)
{
    cout << OFoldStream::leftMargin(out) << \(dq\&, \(dq\& <<
            OFoldStream::rightMargin(out) << endl;
}

int main()
{
    OFoldStream out(cout, 4, 40);

    out << lm(4);

    string line;
    while (getline(cin, line))
        out << line << \(cq\&\en\(cq\&;

    margins(out);
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/ofoldstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7),  \fBlm\fP(3bobcat), \fBmlm\fP(3bobcat),
\fBofoldbuf\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\&.06\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.06\&.02\-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