# Poco::XML

# class XMLStreamParser

Library: XML
Package: XML
Header: Poco/XML/XMLStreamParser.h

## Description

The streaming XML pull parser and streaming XML serializer. The parser is a conforming, non-validating XML 1.0 implementation (see Implementation Notes for details). The application character encoding (that is, the encoding used in the application's memory) for both parser and serializer is UTF-8. The output encoding of the serializer is UTF-8 as well. The parser supports UTF-8, UTF-16, ISO-8859-1, and US-ASCII input encodings.

Attribute map:

Attribute map lookup. If attribute is not found, then the version without the default value throws an appropriate parsing exception while the version with the default value returns that value.

Note also that there is no attribute(ns, name) version since it would conflict with attribute(name, dv) (qualified attributes are not very common).

Attribute map is valid throughout at the "element level" until end_element and not just during EV_START_ELEMENT. As a special case, the map is still valid after peek() that returned end_element until this end_element event is retrieved with next().

Using parser:

    XMLStreamParser p(ifs, argv[1]);
    for (XMLStreamParser::EventType e: p)
    {
        switch (e)
        {
        case XMLStreamParser::EV_START_ELEMENT:
            cerr << p.line () << ':' << p.column () << ": start " << p.name () << endl;
            break;
        case XMLStreamParser::EV_END_ELEMENT:
            cerr << p.line () << ':' << p.column () << ": end " << p.name () << endl;
            break;
        case XMLStreamParser::EV_START_ATTRIBUTE:
            ...
        case XMLStreamParser::EV_END_ATTRIBUTE:
            ...
        case XMLStreamParser::EV_CHARACTERS:
            ...
        }
    }

## Member Summary

Member Functions: attribute, attributeMap, attributePresent, begin, column, content, element, end, event, getQName, inputName, line, localName, namespaceURI, next, nextExpect, peek, prefix, value

## Nested Classes

### struct AttributeValueType

### struct Iterator

## Types Aliases

### AttributeMapType

using AttributeMapType = std::map < QName, AttributeValueType >;

### FeatureType

using FeatureType = unsigned short;

If both receive_attributes_event and RECEIVE_ATTRIBUTE_MAP are specified, then RECEIVE_ATTRIBUTES_EVENT is assumed.

## Enumerations

### EventType

Parsing events.

EV_START_ELEMENT

EV_END_ELEMENT

EV_START_ATTRIBUTE

EV_END_ATTRIBUTE

EV_CHARACTERS

EV_START_NAMESPACE_DECL

EV_END_NAMESPACE_DECL

EV_EOF

## Constructors

### XMLStreamParser

XMLStreamParser(
std::istream & param488,
const std::string & inputName,
FeatureType = RECEIVE_DEFAULT
);

The parser constructor takes three arguments: the stream to parse, input name that is used in diagnostics to identify the document being parsed, and the list of events we want the parser to report.

Parse std::istream. Input name is used in diagnostics to identify the document being parsed.

If stream exceptions are enabled then std::ios_base::failure exception is used to report io errors (badbit and failbit). Otherwise, those are reported as the parsing exception.

### XMLStreamParser

XMLStreamParser(
const void * data,
std::size_t size,
const std::string & inputName,
FeatureType = RECEIVE_DEFAULT
);

Parse memory buffer that contains the whole document. Input name is used in diagnostics to identify the document being parsed.

## Destructor

### ~XMLStreamParser

~XMLStreamParser();

Destroys the XMLStreamParser.

## Member Functions

### attribute

const std::string & attribute(
const std::string & name
) const;

### attribute

template < typename T > T attribute(
const std::string & name
) const;

### attribute

std::string attribute(
const std::string & name,
const std::string & deflt
) const;

### attribute

template < typename T > T attribute(
const std::string & name,
const T & deflt
) const;

### attribute

const std::string & attribute(
const QName & qname
) const;

### attribute

template < typename T > T attribute(
const QName & qname
) const;

### attribute

std::string attribute(
const QName & qname,
const std::string & deflt
) const;

### attribute

template < typename T > T attribute(
const QName & qname,
const T & deflt
) const;

### attributeMap

const AttributeMapType & attributeMap() const;

### attributePresent

bool attributePresent(
const std::string & name
) const;

### attributePresent

bool attributePresent(
const QName & qname
) const;

### begin

Iterator begin();

### column

Poco::UInt64 column() const;

### content

void content(
Content
);

### content

Content content() const;

### element

std::string element();

### element

template < typename T > T element();

### element

std::string element(
const std::string & name
);

### element

std::string element(
const QName & qname
);

### element

template < typename T > T element(
const std::string & name
);

### element

template < typename T > T element(
const QName & qname
);

### element

std::string element(
const std::string & name,
const std::string & deflt
);

### element

std::string element(
const QName & qname,
const std::string & deflt
);

### element

template < typename T > T element(
const std::string & name,
const T & deflt
);

### element

template < typename T > T element(
const QName & qname,
const T & deflt
);

### end

Iterator end();

### event

EventType event();

Return the event that was last returned by the call to next() or peek().

### getQName

const QName & getQName() const;

### inputName

const std::string & inputName() const;

### line

Poco::UInt64 line() const;

### localName

const std::string & localName() const;

### namespaceURI

const std::string & namespaceURI() const;

### next

EventType next();

Call the next() function when we are ready to handle the next piece of XML.

### nextExpect

void nextExpect(
EventType
);

Get the next event and make sure that it's what's expected. If it is not, then throw an appropriate parsing exception.

### nextExpect

void nextExpect(
EventType,
const std::string & name
);

### nextExpect

void nextExpect(
EventType,
const QName & qname
);

### nextExpect

void nextExpect(
EventType,
const std::string & ns,
const std::string & name
);

### nextExpect

void nextExpect(
EventType,
const std::string & name,
Content
);

### nextExpect

void nextExpect(
EventType,
const QName & qname,
Content
);

### nextExpect

void nextExpect(
EventType,
const std::string & ns,
const std::string & name,
Content
);

### peek

EventType peek();

### prefix

const std::string & prefix() const;

### value

std::string & value();

### value

const std::string & value() const;

### value

template < typename T > T value() const;

## Variables

### RECEIVE_ATTRIBUTES_EVENT

static const FeatureType RECEIVE_ATTRIBUTES_EVENT = 0x0008;

### RECEIVE_ATTRIBUTE_MAP

static const FeatureType RECEIVE_ATTRIBUTE_MAP = 0x0004;

### RECEIVE_CHARACTERS

static const FeatureType RECEIVE_CHARACTERS = 0x0002;

### RECEIVE_DEFAULT

static const FeatureType RECEIVE_DEFAULT = RECEIVE_ELEMENTS | RECEIVE_CHARACTERS | RECEIVE_ATTRIBUTE_MAP;

### RECEIVE_ELEMENTS

static const FeatureType RECEIVE_ELEMENTS = 0x0001;

### RECEIVE_NAMESPACE_DECLS

static const FeatureType RECEIVE_NAMESPACE_DECLS = 0x0010;