OpenPRA Documentation

scram::xml::StreamElement ​

Writer of data formed as an XML element to a stream. More...

#include <xml_stream.h>

Public Functions ​

Name
StreamElement(const char * name, detail::Indenter * indenter, detail::FileStream * out)<br>Constructs a root streamer for the XML element data ready to accept attributes, elements, text.
~StreamElement()<br>Puts the closing tag.
template <typename T > <br>StreamElement &SetAttribute(const char * name, T && value)<br>Sets the attributes for the element.
template <typename T > <br>StreamElement &AddText(T && text)<br>Adds text to the element.
StreamElementAddChild(const char * name)<br>Adds a child element to the element.

Detailed Description ​

cpp
class scram::xml::StreamElement;

Writer of data formed as an XML element to a stream.

Note: The stream is not designed to mix XML text and elements due to the absence of the use case or need.

Warning:

  • The names of elements and attributes are NOT validated to be proper XML NCName. It is up to the caller to sanitize the names (<, >, &, ", ', :, etc.).
  • The API works with C strings, but this class does not manage the string lifetime. It doesn't own any strings. The provider of the strings must make sure the lifetime of the string is long enough for streaming. It is the most common case that strings are literals, so there's no need to worry about dynamic lifetime.

Precondition: All strings are UTF-8 encoded.

This class relies on the RAII to put the closing tags. It is designed for stack-based use so that its destructor gets called at scope exit. One element at a time must be operated. The output will be malformed if two child elements at the same scope are being streamed. To prevent this from happening, the parent element is put into an inactive state while its child element is alive.

Public Functions Documentation ​

function StreamElement ​

cpp
inline StreamElement(
    const char * name,
    detail::Indenter * indenter,
    detail::FileStream * out
)

Constructs a root streamer for the XML element data ready to accept attributes, elements, text.

Parameters:

  • name Non-empty string name for the element.
  • indenter The indentation provider.
  • out The destination stream.

Exceptions:

function ~StreamElement ​

cpp
inline ~StreamElement()

Puts the closing tag.

Warning: The output will be malformed if the child outlives the parent. It can happen if the destructor is called explicitly, or if the objects are allocated on the heap with different lifetimes.

Precondition: No child element is alive.

function SetAttribute ​

cpp
template <typename T >
inline StreamElement & SetAttribute(
    const char * name,
    T && value
)

Sets the attributes for the element.

Parameters:

  • name Non-empty name for the attribute.
  • value The value of the attribute.

Exceptions:

Template Parameters:

  • T Streamable type supporting operator<<.

Return: The reference to this element.

Postcondition: &, <, " chars are escaped in the value text.

function AddText ​

cpp
template <typename T >
inline StreamElement & AddText(
    T && text
)

Adds text to the element.

Parameters:

  • text Non-empty text.

Exceptions:

Template Parameters:

  • T Streamable type supporting operator<<.

Return: The reference to this element.

Postcondition:

  • No more elements or attributes can be added.
  • More text can be added.
  • &, <, " chars are escaped in the text.

function AddChild ​

cpp
inline StreamElement AddChild(
    const char * name
)

Adds a child element to the element.

Parameters:

  • name Non-empty name for the child element.

Exceptions:

  • StreamError Invalid setup or state for element addition.

Return: A streamer for child element.

Precondition: The child element will be destroyed before the parent.

Postcondition: The parent element is inactive while the child element is alive.

Updated on 2025-11-11 at 16:51:08 +0000