Function Template `punctuate`

Overview
Examples Example A Example B Example C Example D
Headers
Reference Synopsis Namespace punc punctuate for ranges punctuate for tuple-like types

Overview

The overloaded function template punctuate returns an object which when inserted into an output stream or extracted from an input stream instructs the stream to use a provided punctuation sequence to format instances of a specified type or collection of types.

The function arguments to punctuate are an opening character sequence, zero or more separator sequences, a closing sequence and an optional combination of constants from the namespace boost::io::punc. The first template argument to punctuate is a selector which must be specified explicitly; it indicates the type or collection of types to which the provided punctuation sequence applies. A type T matches a selector S if

T is the same as S, or
T is a specialization of a class template U and S is of the form U<boost::io::_,...,boost::io::_>.

If two punctuation sequences have been supplied for a T using selectors T and U<boost::io::_,...,boost::io::_>, the punctuation sequence supplied using selector T prevails.

Examples

Example A

This example formats a list of pairs using punctuation sequences specified with punctuate.

#include <list>
#include <iostream>
#include <string>
#include <utility>                          // std::pair
#include <boost/iostreams/format_lite.hpp> // punctuate and operator<<

int main()
{
    using namespace std;
    using namespace boost::io;
    
    // pseudocode initialization
    list< pair<string, string> > pairs =
        { { "hello", "goodbye" }, 
          { "morning", "evening" }, 
          { "yes", "no" } };
        
    cout << punctuate< pair<string, string> >("[ ", " : ", " ]")
         << punctuate< list<_> >("< ", ", ", " >")
         << pairs;
}

Output:

< [ hello : goodbye ], [ morning : evening ], [ yes : no ] >

Example B

This example formats a list of lists using punctuation sequences specified with punctuate. The outer list is formatted using the punctuation sequence specified with selector list<_>, while the inner lists are formatted using the punctuation sequence specified with selector list<string>.

#include <list>
#include <iostream>
#include <string>
#include <boost/iostreams/format_lite.hpp> // punctuate and operator<<

int main()
{
    using namespace std;
    using namespace boost::io;
    
    // pseudocode initialization
    list< list<string> > lists =
        { { "hello", "goodbye" }, 
          { "morning", "evening" }, 
          { "yes", "no" } };
        
    cout << punctuate< list<string> >("[ ", " : ", " ]")
         << punctuate< list<_> >("< ", ", ", " >")
         << lists;
}

Output:

< [ hello : goodbye ], [ morning : evening ], [ yes : no ] >

Example C

This example formats a list of tuples using a punctuation sequence specified with punctuate. The list is formatted using the default punctuation sequence, while the tuples are formatted using the punctuation sequence specified with selector tuple<int, float>.

#include <list>
#include <iostream>
#include <string>
#include <boost/tuple/tuple.hpp> 
#include <boost/iostreams/format_lite.hpp> // punctuate and operator<<

int main()
{
    using namespace std;
    using namespace boost::io;
    
    // pseudocode initialization
    list< tuple<int, float> > tuples =
        { { 1, 8.6 }, { 256, 0.03 }, { -7, 12.8 } };
        
    cout << punctuate< tuple<int, float> >("[", ",", "]")
         << tuples;
}

Output:

([1,8.6],[256,0.03],[-7,12.8])

Example D

This example formats a vector of lists using punctuation sequences and indentation options specified with punctuate. The vector is formatted with line breaks after the opening sequence, after each separator and before the closing sequence. The vector's elements are formatted with indentation increased by two spaces. Each list is formatted with line breaks before each separator.

#include <list>
#include <iostream>
#include <string>
#include <boost/tuple/tuple.hpp> 
#include <boost/iostreams/format_lite.hpp> // punctuate and operator<<

int main()
{
    using namespace std;
    using namespace boost::io;
    
    // pseudocode initialization
    vector< list<string> > vec =
        { { "one", "two", "three" },
          { "a", "b", "c" },
          { "milk", "coffee", "tea" } };

    int vector_punc = punc::indent_after_open | 
                      punc::break_after_sep |
                      punc::break_bfore_close |
                      (punc::spaces * 2);
    cout << punctuate< vector<_> >("(", ",", ")", vector_punc )
         << punctuate< list<_> >("( ", "  , ", " )", punc::break_before_sep)
         << tuples;
}

Output:

(
  ( one
    , two
    , three ),
  ( a
    , b
    , c ),
  ( milk
    , coffee
    , tea )
)

Headers

<boost/iostreams/punctuate.hpp>

Reference

Synopsis

namespace boost { namespace io {

    // Line-break and indentation flags

namespace punc {

const int tabs;
const int spaces;
const int flat;
const int break_after_open;
const int indent_after_open;
const int break_before_sep;
const int break_after_sep;
const int break_before_close;

} // End namespace punc

    // Punctuate for ranges or tuple-like types
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep, 
           const Ch* close,
           int flags = punc::flat );

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open,
           const std::basic_string<Ch>& sep,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

    // Punctuate for tuple-like types of length 0 or 1

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

    // Punctuate for tuple-like types of length >= 2

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep1, 
           const Ch* sep2, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& sep1,
           const std::basic_string<Ch>& sep2,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

    ...            

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep1, 
           ..., 
           const Ch* sepn, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& sep1,
           ...
           const std::basic_string<Ch>& sepn,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

} } // End namespace boost::io

Namespace `punc`

The namespace boost::io::punc contains the definitions of constants used to specify line-break and indentation options for formatted output.

namespace boost { namespace io {

namespace punc {

const int tabs;
const int spaces;
const int flat;
const int break_after_open;
const int indent_after_open;
const int break_before_sep;
const int break_after_sep;
const int break_before_close;

} // End namespace punc

} } // End namespace boost::io

The constants have the following interpretations:

Constant	Interpretation
`tabs`	Used to indicate the number of tabs characters to insert when indenting
`spaces`	Used to indicate the number of space characters to insert when indenting
`flat`	Indicates that no line-breaks should be inserted. It is equal to `0`, and so can be overridden by other options
`break_after_open`	Bit flag indicating that a line-break should be inserted after the opening punctuation sequence
`indent_after_open`	Bit flag indicating that the indentation level should be increased after the opening punctuation sequence and decreased before the closing punctuation sequence
`break_before_sep`	Bit flag indicating that a line-break should be inserted before each separating punctuation sequence
`break_after_sep`	Bit flag indicating that a line-break should be inserted after each separating punctuation sequence
`break_before_close`	Bit flag indicating that a line-break should be inserted before the closing punctuation sequence

To use the constants, take the bitwise OR of

zero or more of the bit flag constants break_after_open, indent_after_open, break_before_sep, break_after_sep and break_before_close;
A value of the form (tabs * n), for n in the range [0, 20]; and
A value of the form (spaces * n), for n in the range [0, 100).

For example, the value

int flags = punc::indent_after_open | 
            punc::break_after_sep |
            punc::break_bfore_close |
            (punc::spaces * 2);

Indicates that a line break should be inserted after the opening sequence, after each separator and before the closing sequence, and that the elements of a range or tuple-like object should be displayed with indentation increased by two tab characters.

Class Template `punctuate`

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep, 
           const Ch* close,
           int flags = punc::flat );

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open,
           const std::basic_string<Ch>& sep,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

Both functions return objects which when inserted into or extracted from a standard stream specify formatting options for types matching the specified selector.

Template Parameters

S	-	A selector indicating the type or collection of types to which the specified formatting options apply. (See Overview.)
Ch	-	A character type

Function Parameters

open	-	The opening punctuation sequence
sep	-	The separating punctuation sequence
close	-	The closing punctuation sequence
flags	-	A combination of constants from the namespace punc. (See Namespace `punc`.)

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

Both functions return objects which when inserted into or extracted from a standard stream specify formatting options for tuple-like types of length zero or one matching the specified selector.

Template Parameters

S	-	A selector indicating the type or collection of types to which the specified formatting options apply. (See Overview.)
Ch	-	A character type

Function Parameters

open	-	The opening punctuation sequence
close	-	The closing punctuation sequence
flags	-	A combination of constants from the namespace punc. (See Namespace `punc`.)

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep1, 
           const Ch* sep2, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& sep1,
           const std::basic_string<Ch>& sep2,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

    ...            

template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const Ch* open, 
           const Ch* sep1, 
           ..., 
           const Ch* sepn, 
           const Ch* close,
           int flags = punc::flat );
              
template<typename Selector, typename Ch>
[implementation-defined]
punctuate( const std::basic_string<Ch>& open, 
           const std::basic_string<Ch>& sep1,
           ...
           const std::basic_string<Ch>& sepn,
           const std::basic_string<Ch>& close,
           int flags = punc::flat );

Each function returns an object which when inserted into or extracted from a standard stream specifies formatting options for types matching the specified selector.

Template Parameters

S	-	A selector indicating the type or collection of types to which the specified formatting options apply. (See Overview.)
Ch	-	A character type

Function Parameters

open	-	The opening punctuation sequence
sepn	-	The `n`^th separating punctuation sequence
close	-	The closing punctuation sequence
flags	-	A combination of constants from the namespace punc. (See Namespace `punc`.)

Revised 20 May, 2004

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Sha'arei Tefila, an Orthodox Shul (Synagogue) in Salt Lake City, Utah Chabad Lubavitch of Utah

Function Template punctuate

Overview

Examples

Example A

Example B

Example C

Example D

Headers

Reference

Synopsis

Namespace punc

Class Template punctuate

Template Parameters

Function Parameters

Template Parameters

Function Parameters

Template Parameters

Function Parameters

Function Template `punctuate`

Namespace `punc`

Class Template `punctuate`