nlib
nn::nlib::exi::XmlStreamReader Class Referenceabstract

Abstract class that reads from an XML stream. More...

#include "nn/nlib/exi/XmlStreamReader.h"

Public Types

enum  XmlStreamConstants {
  NONE = -1,
  START_ELEMENT = 1,
  END_ELEMENT = 2,
  PROCESSING_INSTRUCTION = 3,
  CHARACTERS = 4,
  COMMENT = 5,
  START_DOCUMENT = 7,
  END_DOCUMENT = 8,
  CDATA = 12
}
 Values of XML stream events that occurred while reading an XML stream. More...
 

Public Member Functions

const ExiCharGetElementText () noexcept
 Reads a series of text events and returns a single text element. More...
 
const ExiCharGetLocalName () noexcept
 Gets the local name. More...
 
const ExiCharGetNamespaceUri () noexcept
 Gets the URI of the XML namespace. More...
 
const ExiCharGetPrefix () noexcept
 Gets the namespace prefix of the XML. More...
 
const ExiCharGetText () noexcept
 Gets text data. More...
 
XmlStreamConstants GetEventType () const noexcept
 Returns the value for the most recent XML stream event.
 
XML Attribute Operations
size_t GetAttributeCount () noexcept
 Gets the number of attributes. More...
 
const ExiCharGetAttributeLocalName (size_t index) noexcept
 Gets the local name of an attribute. More...
 
const ExiCharGetAttributeNamespaceUri (size_t index) noexcept
 Gets the namespace URI of an attribute. More...
 
const ExiCharGetAttributePrefix (size_t index) noexcept
 Gets the prefix of an attribute. More...
 
const ExiCharGetAttributeValue (size_t index) noexcept
 Gets the value of an attribute. More...
 
const ExiCharGetAttributeValue (const ExiChar *namespace_uri, const ExiChar *local_name) noexcept
 Gets the value of the attribute based on a particular namespace URI and local name. More...
 
XML Namespace Operations
size_t GetNamespaceCount () noexcept
 Gets the number of newly defined namespaces. More...
 
const ExiCharGetNamespacePrefix (size_t index) noexcept
 Gets the prefix of a namespace declaration. More...
 
const ExiCharGetNamespaceUri (size_t index) noexcept
 Gets the namespace URI of a namespace declaration. More...
 
Error Checking
int GetLineNo () const noexcept
 Gets the line number indicated by the XmlStreamReader. More...
 
int GetColumnNo () const noexcept
 Gets the column number indicated by the XmlStreamReader. More...
 
ExiErrorStatus::ErrorValue GetError () const noexcept
 Gets the error value.
 
ExiErrorStatusGetErrorStatus () const noexcept
 Gets an error status object.
 
 operator bool () const
 Returns true if an error has not occurred.
 
Getting XML Stream Events
XmlStreamConstants Next () noexcept
 Reads the next XML stream event from the stream. More...
 
bool HasNext () const noexcept
 Returns whether the next XML stream event can be obtained. More...
 
XML Stream Event Determination
bool HasName () const noexcept
 Returns whether data like a local name can be obtained. More...
 
bool HasText () const noexcept
 Returns whether text is ready to be obtained using GetText(). More...
 
bool IsCharacters () const noexcept
 Gets whether the data that was read is a text node. More...
 
bool IsEndElement () const noexcept
 Gets whether the data that was read is a closing tag. More...
 
bool IsStartElement () const noexcept
 Gets whether the data that was read is an opening tag. More...
 

XmlStreamReader Object Initialization and Finalization

Instantiates an object using a static member function.

Description
The XmlStreamReader constructor has not been made public. You must call the Create function. Objects created using the Create function can be deleted (using delete), but normally this is handled using UniquePtr.
static XmlStreamReaderCreate (InputStream *stream, const XmlStreamReaderSettings &settings, const ExiAllocatorEx &al) noexcept
 Creates an XmlStreamReader instance by specifying an objectwise allocator. More...
 
static XmlStreamReaderCreate (InputStream *stream, const XmlStreamReaderSettings &settings) noexcept
 Creates an instance of XmlStreamReader. More...
 
static XmlStreamReaderCreate (InputStream *stream) noexcept
 Creates an XmlStreamReader instance using default settings for XmlStreamReaderSettings. More...
 
static XmlStreamReaderCreate (InputStream *stream, const ExiAllocatorEx &al) noexcept
 Creates an XmlStreamReader instance by specifying an objectwise allocator. More...
 
virtual ~XmlStreamReader () noexcept
 Destructor.
 
void Close () noexcept
 Closes an XmlStreamReader. The original stream is not actually closed; it merely stops being referenced.
 

Detailed Description

Abstract class that reads from an XML stream.

Description
This class allows you to read XML using code like that of the Cursor API in the XMLStreamReader class in Java StAX.
Typically, XML is read using code like the following.
if (!r.get()) {
// Failed to generate an instance.
// Memory allocation from ExiAllocator may have failed.
return out_of_memory;
}
while(r->HasNext()) {
// Continuing to read XML using r->Next() triggers an event; code the operations that you want to take place for each event type.
switch(e) {
{
// Code the operation you want to occur for an opening tag.
// Attributes and namespace declarations can be extracted when the starting tag event is obtained.
}
break;
{
// Code the operation you want to occur for a closing tag.
}
break;
{
// Code the operation you want to occur for a text node.
}
break;
Include another case statement if there are other events you want to handle.
}
}
if (nlib_is_error(*r)) {
// An error occurred during the operation.
// After an error occurs, nothing happens even if you make calls to the XmlStreamReader API.
// Any crashes or other glitches that occur here are bugs in the exi library.
return error;
}
return ok;
Most of the string data that can be obtained is valid until the XmlStreamReader object is deleted. You do not necessarily need to perform a string copy if you are creating something like an associative array that uses the local names and other attributes of elements as keys.
In other words, as long as control is in the outer scope within the code below, you do not need to take a backup of the string data.
{
while(r->HasNext()) {
........
}
//String data obtained using functions like r->GetLocalName() is valid within this block
}

Definition at line 56 of file XmlStreamReader.h.

Member Enumeration Documentation

◆ XmlStreamConstants

Values of XML stream events that occurred while reading an XML stream.

Enumerator
NONE 

Indicates an invalid status. This tends to indicate that an error has occurred.

START_ELEMENT 

Reads an opening tag.

END_ELEMENT 

Reads a closing tag.

PROCESSING_INSTRUCTION 

Reads a PI (processing instruction).

CHARACTERS 

Reads a text node.

COMMENT 

Reads a comment.

START_DOCUMENT 

Reads the start of an XML document.

END_DOCUMENT 

Reads the end of an XML document.

CDATA 

Reads a CDATA section.

Definition at line 58 of file XmlStreamReader.h.

Member Function Documentation

◆ Create() [1/4]

nn::nlib::exi::XmlStreamReader::Create ( InputStream stream,
const XmlStreamReaderSettings settings,
const ExiAllocatorEx al 
)
staticnoexcept

Creates an XmlStreamReader instance by specifying an objectwise allocator.

Parameters
[in]streamOriginal output stream.
[in]settingsConfiguration options.
[in]alAllocator.
Returns
Returns the XmlStreamReader instance that was created.

◆ Create() [2/4]

nn::nlib::exi::XmlStreamReader::Create ( InputStream stream,
const XmlStreamReaderSettings settings 
)
inlinestaticnoexcept

Creates an instance of XmlStreamReader.

Parameters
[in]streamOriginal input stream.
[in]settingsConfiguration options.
Returns
Returns the XmlStreamReader instance that was created.
Description
The instance is created by obtaining memory from ExiAllocator. If successful, it returns a non-NULL pointer. Generally, the pointer that is returned is stored and used via UniquePtr.
If you are reading XML that was configured using non-default settings without any written encoding options, you must specify non-default options and create an instance. For more information, see XmlStreamReaderSettings.

Definition at line 78 of file XmlStreamReader.h.

◆ Create() [3/4]

nn::nlib::exi::XmlStreamReader::Create ( InputStream stream)
inlinestaticnoexcept

Creates an XmlStreamReader instance using default settings for XmlStreamReaderSettings.

Parameters
[in]streamOriginal input stream.
Returns
Returns the XmlStreamReader instance that was created.
Description
This is equivalent to the code below.
nn::nlib::exi::InputStream* stream = ....;

Definition at line 83 of file XmlStreamReader.h.

◆ Create() [4/4]

nn::nlib::exi::XmlStreamReader::Create ( InputStream stream,
const ExiAllocatorEx al 
)
inlinestaticnoexcept

Creates an XmlStreamReader instance by specifying an objectwise allocator.

Parameters
[in]streamOriginal output stream.
[in]alAllocator.
Returns
Returns the XmlStreamReader instance that was created.

Definition at line 87 of file XmlStreamReader.h.

◆ GetAttributeCount()

nn::nlib::exi::XmlStreamReader::GetAttributeCount ( )
inlinenoexcept

Gets the number of attributes.

Returns
Returns the number of attributes.
Description
If called after reading an opening tag, it gets the number of attributes that were read. If there are no attributes, or it wasn't called after reading an opening tag, it returns 0.

Definition at line 100 of file XmlStreamReader.h.

◆ GetAttributeLocalName()

nn::nlib::exi::XmlStreamReader::GetAttributeLocalName ( size_t  index)
inlinenoexcept

Gets the local name of an attribute.

Parameters
[in]indexSpecifies the index.
Returns
Returns the local name of the attribute.
Description
Returns the local name of the attribute corresponding to the index. Returns NULL if no attribute corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 104 of file XmlStreamReader.h.

◆ GetAttributeNamespaceUri()

nn::nlib::exi::XmlStreamReader::GetAttributeNamespaceUri ( size_t  index)
inlinenoexcept

Gets the namespace URI of an attribute.

Parameters
[in]indexSpecifies the index.
Returns
Returns the namespace URI of the attribute.
Description
Returns the namespace URI of the attribute corresponding to the index. Returns NULL if no attribute corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 108 of file XmlStreamReader.h.

◆ GetAttributePrefix()

nn::nlib::exi::XmlStreamReader::GetAttributePrefix ( size_t  index)
inlinenoexcept

Gets the prefix of an attribute.

Parameters
[in]indexSpecifies the index.
Returns
Returns the prefix of the attribute.
Description
Gets the prefix of the attribute corresponding to the index. Returns NULL if no attribute corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 112 of file XmlStreamReader.h.

◆ GetAttributeValue() [1/2]

nn::nlib::exi::XmlStreamReader::GetAttributeValue ( size_t  index)
inlinenoexcept

Gets the value of an attribute.

Parameters
[in]indexSpecifies the index.
Returns
Returns the value of the attribute.
Description
Gets the value of the attribute that corresponds to the index. Returns NULL if no attribute corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 120 of file XmlStreamReader.h.

◆ GetAttributeValue() [2/2]

nn::nlib::exi::XmlStreamReader::GetAttributeValue ( const ExiChar namespace_uri,
const ExiChar local_name 
)
inlinenoexcept

Gets the value of the attribute based on a particular namespace URI and local name.

Parameters
[in]namespace_uriNamespace URI. (NULL is not allowed.)
[in]local_nameLocal name. (NULL is not allowed.)
Returns
Returns the value of the attribute.
Description
Gets the value of the attribute with the specified namespace URI and local name. If there are no attributes, or it wasn't called after reading an opening tag, it returns NULL.

Definition at line 124 of file XmlStreamReader.h.

◆ GetColumnNo()

nn::nlib::exi::XmlStreamReader::GetColumnNo ( ) const
inlinenoexcept

Gets the column number indicated by the XmlStreamReader.

Returns
Returns the column number.
Description
This is only valid while parsing text-based XML. Returns an integer greater than or equal to 1. Returns 0 when parsing binary XML.

Definition at line 162 of file XmlStreamReader.h.

◆ GetElementText()

nn::nlib::exi::XmlStreamReader::GetElementText ( )
inlinenoexcept

Reads a series of text events and returns a single text element.

Returns
Returns text data.
Description
A series of text node events is written, for example, if XmlStreamWriter::WriteCharacters was called repeatedly during XML creation. In such cases, if you want to handle this text as a single string, get the text data by calling this function.
If there is no text, or an error occurs, it returnsNULL.

Definition at line 141 of file XmlStreamReader.h.

◆ GetLineNo()

nn::nlib::exi::XmlStreamReader::GetLineNo ( ) const
inlinenoexcept

Gets the line number indicated by the XmlStreamReader.

Returns
Returns the line number.
Description
This is only valid while parsing text-based XML. Returns an integer greater than or equal to 1. Returns 0 when parsing binary XML.

Definition at line 161 of file XmlStreamReader.h.

◆ GetLocalName()

nn::nlib::exi::XmlStreamReader::GetLocalName ( )
inlinenoexcept

Gets the local name.

Returns
Returns the local name.
Description
You can get the local name if either an opening tag or a closing tag has been read. Otherwise it returns NULL.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 145 of file XmlStreamReader.h.

◆ GetNamespaceCount()

nn::nlib::exi::XmlStreamReader::GetNamespaceCount ( )
inlinenoexcept

Gets the number of newly defined namespaces.

Returns
Returns the number of namespaces.
Description
If called after reading an opening tag, it gets the number of newly defined namespaces. If no namespaces are defined, or it wasn't called after reading an opening tag, it returns 0.

Definition at line 129 of file XmlStreamReader.h.

◆ GetNamespacePrefix()

nn::nlib::exi::XmlStreamReader::GetNamespacePrefix ( size_t  index)
inlinenoexcept

Gets the prefix of a namespace declaration.

Parameters
[in]indexSpecifies the index.
Returns
Returns the prefix of the namespace declaration.
Description
Returns the prefix string of the namespace declaration corresponding to the index. Returns NULL if no namespace declaration corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 133 of file XmlStreamReader.h.

◆ GetNamespaceUri() [1/2]

nn::nlib::exi::XmlStreamReader::GetNamespaceUri ( size_t  index)
inlinenoexcept

Gets the namespace URI of a namespace declaration.

Parameters
[in]indexSpecifies the index.
Returns
Returns the namespace URI of the namespace declaration.
Description
Returns the namespace URI of the namespace declaration that corresponds to the index. Returns NULL if no namespace declaration corresponds to the specified index.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 137 of file XmlStreamReader.h.

◆ GetNamespaceUri() [2/2]

nn::nlib::exi::XmlStreamReader::GetNamespaceUri ( )
inlinenoexcept

Gets the URI of the XML namespace.

Returns
Returns the URI of the XML namespace.
Description
You can get the URI of the XML namespace if either an opening tag or a closing tag has been read. Otherwise it returns NULL.
String data is valid as long as the XmlStreamReader object exists.

Definition at line 149 of file XmlStreamReader.h.

◆ GetPrefix()

nn::nlib::exi::XmlStreamReader::GetPrefix ( )
inlinenoexcept

Gets the namespace prefix of the XML.

Returns
Returns a string representing the namespace prefix of the XML.
Description
You can get the string representing the namespace prefix of the XML if either an opening tag or a closing tag has been read. Otherwise it returns NULL.
String data (memory in which strings are stored) is valid as long as the XmlStreamReader object exists.

Definition at line 153 of file XmlStreamReader.h.

◆ GetText()

nn::nlib::exi::XmlStreamReader::GetText ( )
inlinenoexcept

Gets text data.

Returns
Returns text data.
Description
This data is different from the data that can be obtained using the most recent XML stream event.

Definition at line 157 of file XmlStreamReader.h.

◆ HasName()

nn::nlib::exi::XmlStreamReader::HasName ( ) const
inlinenoexcept

Returns whether data like a local name can be obtained.

Returns
Returns true if an opening tag, closing tag, or PI has been obtained.

Definition at line 170 of file XmlStreamReader.h.

◆ HasNext()

nn::nlib::exi::XmlStreamReader::HasNext ( ) const
inlinenoexcept

Returns whether the next XML stream event can be obtained.

Returns
If the next XML stream event can be obtained, returns true.

Definition at line 174 of file XmlStreamReader.h.

◆ HasText()

nn::nlib::exi::XmlStreamReader::HasText ( ) const
inlinenoexcept

Returns whether text is ready to be obtained using GetText().

Returns
Returns true if a text, a CDATA section, comment, or PI has been obtained.

Definition at line 175 of file XmlStreamReader.h.

◆ IsCharacters()

nn::nlib::exi::XmlStreamReader::IsCharacters ( ) const
inlinenoexcept

Gets whether the data that was read is a text node.

Returns
Returns true if the data was text or a CDATA section, or false otherwise.

Definition at line 179 of file XmlStreamReader.h.

◆ IsEndElement()

nn::nlib::exi::XmlStreamReader::IsEndElement ( ) const
inlinenoexcept

Gets whether the data that was read is a closing tag.

Returns
Returns true if the data was a closing tag, or false otherwise.

Definition at line 180 of file XmlStreamReader.h.

◆ IsStartElement()

nn::nlib::exi::XmlStreamReader::IsStartElement ( ) const
inlinenoexcept

Gets whether the data that was read is an opening tag.

Returns
Returns true if the data was an opening tag, or false otherwise.

Definition at line 181 of file XmlStreamReader.h.

◆ Next()

nn::nlib::exi::XmlStreamReader::Next ( )
inlinenoexcept

Reads the next XML stream event from the stream.

Returns
Returns the value obtained for the XML stream event.

Definition at line 163 of file XmlStreamReader.h.


The documentation for this class was generated from the following files: