Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext
Stream Parsers (stream, wstream, etc.)
Description

The stream_parser is a primitive which allows to use pre-existing standard streaming operators for input parsing integrated with Spirit.Qi. It provides a wrapper parser dispatching the underlying input stream to the stream operator of the corresponding attribute type to be parsed. Any value a to be parsed using the stream_parser will result in invoking the standard streaming operator for its type A, for instance:

std::istream& operator>> (std::istream&, A&);
Header
// forwards to <boost/spirit/home/qi/stream.hpp>
#include <boost/spirit/include/qi_stream.hpp>

Also, see Include Structure.

Namespace

Name

boost::spirit::stream // alias: boost::spirit::qi::stream

boost::spirit::wstream // alias: boost::spirit::qi::wstream

Synopsis
template <typename Char, typename Attrib>
struct stream_parser;
Template parameters

Parameter

Description

Default

Char

The character type to use to generate the input. This type will be used while assigning the generated characters to the underlying input iterator.

char

Attrib

The type of the attribute the stream_parser is expected to parse its input into.

spirit::basic_hold_any<Char>

Model of

PrimitiveParser

Notation

s

A variable instance of any type with a defined matching streaming operator>>() or a Lazy Argument that evaluates to any type with a defined matching streaming operator>>().

Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in PrimitiveParser.

Expression

Description

stream

Call the streaming operator>>() for the type of the mandatory attribute. The input recognized by this operator will be the result of the stream parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be char.

wstream

Call the streaming operator>>() for the type of the mandatory attribute. The input recognized by this operator will be the result of the wstream parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be wchar_t.

All parsers listed in the table above are predefined specializations of the stream_parser<Char> basic stream parser type described below. It is possible to directly use this type to create stream parsers using an arbitrary underlying character type.

Expression

Semantics

stream_parser<
    Char, Attrib
>()

Call the streaming operator>>() for the type of the optional attribute, Attrib. The input recognized by this operator will be the result of the stream_parser<> parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be Char

Additional Requirements

All of the stream parsers listed above require the type of the value to parse (the associated attribute) to implement a streaming operator conforming to the usual I/O streams conventions (where attribute_type is the type of the value to recognize while parse):

template <typename Istream>
Istream& operator>> (Istream& os, attribute_type& attr)
{
    // type specific input parsing
    return os;
}

This operator will be called by the stream parsers to gather the input for the attribute of type attribute_type.

[Note] Note

If the stream parser is invoked inside a match (or phrase_match) stream manipulator the Istream passed to the operator>>() will have registered (imbued) the same standard locale instance as the stream the match (or phrase_match) manipulator has been used with. This ensures all facets registered (imbued) with the original I/O stream object are used during input parsing.

Attributes

Expression

Attribute

stream

spirit::hold_any

wstream

spirit::whold_any

stream_parser<Char, Attrib>()

Attrib

[Important] Important

The attribute type spirit::hold_any exposed by some of the stream parsers is semantically and syntactically equivalent to the type implemented by Boost.Any. It has been added to Spirit as it has better performance and a smaller footprint than Boost.Any.

Complexity

O(N), where N is the number of characters consumed by the stream parser

Example
[Note] Note

The test harness for the example(s) below is presented in the Basics Examples section.

A class definition used in the examples:

// a simple complex number representation z = a + bi
struct complex
{
    complex (double a = 0.0, double b = 0.0)
      : a(a), b(b)
    {}

    double a;
    double b;
};

// define streaming operator for the type complex
std::istream&
operator>> (std::istream& is, complex& z)
{
    char lbrace = '\0', comma = '\0', rbrace = '\0';
    is >> lbrace >> z.a >> comma >> z.b >> rbrace;
    if (lbrace != '{' || comma != ',' || rbrace != '}')
        is.setstate(std::ios_base::failbit);
    return is;
}

Using declarations and variables:

using boost::spirit::qi::stream;
using boost::spirit::qi::stream_parser;

Parse a simple string using the operator>>(istream&, std::string&);

std::string str;
test_parser_attr("abc", stream, str);
std::cout << str << std::endl;                  // prints: abc

Parse our complex type using the operator>>(istream&, complex&);

complex c;
test_parser_attr("{1.0,2.5}", stream_parser<char, complex>(), c);
std::cout << c.a << "," << c.b << std::endl;    // prints: 1.0,2.5


PrevUpHomeNext