--- name: "ofoldstreambuf" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "4.08.06-1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/ofoldstreambuf" --- # ofoldstreambuf(3bobcat) Folds long lines written to ostream ## NAME FBB::OFoldStreambuf - Folds long lines written to ostream ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION **FBB::OFoldStreambuf** is a specialization of *FBB::OFilterStreambuf* folding long lines written to an *std::ostream* object. The *OFoldStreambuf* writes the (folded) lines to a second *ostream* (the *destination stream* which is either used by or opened by the *OFoldStreambuf* object). Internally the *OFoldStreambuf* defines its actions using a little finite state automation distinguishing three states (INDENT, WS and NON\_WS) and three character categories (*\\n*, other white space characters (space), and non-space characters). The nine combinations resulting from these two sets are discussed below. *OFoldStreambuf* objects will never fold lines in the middle of series of non-blank characters (called a \`word’ below) but will always break a line at a white space character. 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. 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. What follows is a description of the *Finite State Automaton* (FSA) defining what happens when various character types appear at its three states. The phrase \`... is written’ means that the described information is written to the *ostream* used or opened by the *OFoldStreambuf* object. *OFoldStreambuf*’s initial state is *INDENT*: | | | | | --- | --- | --- | | State | char. | description | | | | space | the indentation is set; | | | | the space character is added to the indentation; | | | | next state: WS | | | non-ws | the character is added to the currently stored word; | | | | next state: NON\_WS | | WS | \\n | a new line character is written; | | | | | next state: INDENT | | | space | white space character is added to the currently | | | | stored space characters; | | | non-ws | the character is added to the currently stored word; | | | | next state: NON\_WS | | NON\_WS | \\n | stored white space and word are written; | | | | a new line is written; | | | | space | stored white space and word are written; | | | | white space character is added to the currently | | | | stored space characters; | | | | next state: WS | | | non-ws | the character is added to the currently stored word; | | | ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM FBB::OFilterStreambuf ## ENUMERATION The enumeration *TabsOrBlanks* 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: - o **BLANKS**:\ The default, indicating that the left margin is specified and written as a number of blanks; - o **TABS**:\ Indicating that the left margin is specified and written as a number of tab-characters. The enumeration *TrailingBlanks* is used to configure the *OFoldStreambuf* object with respect to any trailing blanks that may appear on the final line. These trailing blanks can appear on the final line it it is not properly terminated with a newline character but instead ends in white space. By default these white space characters are ignored, but they may be kept as well. The enumeration has two values: - o **IGNORE\_TRAILING\_BLANKS**:\ 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 *std::ostream*. This is the default used by *OFoldStreambuf* objects. - o **KEEP\_TRAILING\_BLANKS**:\ This indicates that trailing blanks at the final line if it is not terminated by a newline should be written to the destination *std::ostream* ## CONSTRUCTORS - o **OFoldStreambuf(size\_t leftIndent = 0, size\_t rightMargin = 80,** **TabsOrBlanks tob = BLANKS,** **TrailingBlanks tb = IGNORE\_TRAILING\_BLANKS)**:\ This constructor initializes an *OFoldStreambuf* object but does not associate it with a destination stream. It can also be used as the default constructor. - - o **OFoldStreambuf(char const \*fname,** **size\_t leftIndent = 0, size\_t rightMargin = 80,** **TabsOrBlanks tob = BLANKS,** **TrailingBlanks tb = IGNORE\_TRAILING\_BLANKS)**:\ This constructor initializes an *OFoldStreambuf* object and opens (using *std::ios::out*) the destination stream using the name specified as its *fname* argument. - - o **OFoldStreambuf(std::ostream &stream,** **size\_t leftIndent = 0, size\_t rightMargin = 80,** **TabsOrBlanks tob = BLANKS,** **TrailingBlanks tb = IGNORE\_TRAILING\_BLANKS)**:\ This constructor initializes an *OFoldStreambuf* object and uses as its destination stream the *std::ostream stream*. The destructor writes any buffered information to the destination stream and will then flush the destination stream. ## MEMBER FUNCTIONS All members of **FBB::OFilterStreambuf**, in particular its *out()* and *open()* members are available, as **FBB::OFoldStreambuf** inherits from this class. - o **void setMargins(size\_t leftMargin, size\_t rightMargin)**:\ This member can be used to modify the left- and right folding margins. Note that the left margin may also be modified using the *FBB::lm* and *FBB::mlm* manipulators. - - o **void setTrailingBlanks(TrailingBlanks tb)**:\ This member can be used to modify the currently used *TrailingBlanks* parameter. - - o **void useBlanks()**:\ This member can be used to select blanks to be used when inserting left margins. - - o **void useTabs(size\_t tabWidth = 8)**:\ 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. ## STATIC MEMBER FUNCTIONS - o **size\_t leftMargin(std::ostreambuf const \*buffer)**:\ This member returns the current left margin setting of the *OFoldStreambuf* object passed to it as its argument. The member defines a *std::streambuf* parameter which is down cast to an *OFoldStreambuf* and an *FBB::Exception* exception is thrown if that cast fails. - o **size\_t rightMargin(std::ostreambuf const \*buffer)**:\ This member returns the current right margin setting of the *OFoldStreambuf* object passed to it as its argument. The member’s parameter is down cast in the same way as *leftMargin()*’s argument: an *FBB::Exception* exception is thrown if that cast fails. ## 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 **OFoldStreambuf** can, in accordance with Liskov’s Substitution Principle, be used as a *std:streambuf*; but it also offers a facility for classes deriving from **OFoldStreambuf**. This facility is listed here. - o **int pSync()**:\ The contents of the **OFoldStreambuf**’s internal buffer is flushed. ## EXAMPLE ``` #include #include #include #include using namespace std; using namespace FBB; int main() { OFoldStreambuf fb(cout, 4, 40); ostream out(&fb); out << lm(4); string line; while (getline(cin, line)) out << line << ’\n’; } ``` ## FILES *bobcat/ofoldstreambuf* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**lm**(3bobcat)](/lm/3bobcat.md), [**mlm**(3bobcat)](/mlm/3bobcat.md), [**ofilterstreambuf**(3bobcat)](/ofilterstreambuf/3bobcat.md), [**ofoldstream**(3bobcat)](/ofoldstream/3bobcat.md) ## BUGS None Reported. ## 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**).