Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

XMLStackDocument Class Template Reference

XMLStackDocument is a fast stack-based XML writer. More...

#include <XMLStack.h>

List of all members.

Public Types

typedef std::basic_string<
_E, _Tr, _A> 
_XMLStackString
typedef XMLStackDocument<_E,
_Tr, _A> 
_XMLStackDocument
typedef XMLStackNode<_E, _Tr,
_A> 
_XMLStackNode
typedef XMLStackElement<_E,
_Tr, _A> 
_XMLStackElement
typedef XMLStackText<_E, _Tr,
_A> 
_XMLStackText
typedef XMLStackCDATASection<
_E, _Tr, _A> 
_XMLStackCDATASection
typedef XMLStackComment<_E,
_Tr, _A> 
_XMLStackComment
typedef XMLStackProcessingInstruction<
_E, _Tr, _A> 
_XMLStackProcessingInstruction
typedef XMLStackRawXML<_E,
_Tr, _A> 
_XMLStackRawXML

Public Methods

 XMLStackDocument (unsigned long InitialBufferSize=1024)
 Constructor which takes an optional XML buffer size. More...

 XMLStackDocument (const _XMLStackDocument &Instance)
 Copy constructor.

 ~XMLStackDocument ()
 Destructor.

void pop (void)
 Pops the top node off the stack. More...

void popAll (void)
 Repeatedly calls pop() until no more nodes exist on the stack. More...

_XMLStackElementpushElement (const _XMLStackString &Name)
 Pushes an element node on the stack. More...

_XMLStackElementpushElement (const _XMLStackString &Name, const _XMLStackString &NamespaceURI)
 Pushes an element node on the stack and declares the passed in namespace. More...

_XMLStackTextpushText (const _XMLStackString &Data)
 Pushes a text node on the stack. More...

_XMLStackCDATASectionpushCDATASection (const _XMLStackString &Data)
 Pushes a CDATA section node on the stack. More...

_XMLStackCommentpushComment (const _XMLStackString &Data)
 Pushes a comment node on the stack. More...

_XMLStackProcessingInstructionpushProcessingInstruction (const _XMLStackString &Target)
 Pushes a processing instruction node on the stack. More...

_XMLStackRawXMLpushRawXML (const _XMLStackString &PushXML, const _XMLStackString &PopXML)
 Pushes a raw XML node on the stack. More...

_XMLStackNodetop (void)
 Returns the node on top of the stack. More...

const _XMLStackNodetop (void) const
 Returns the node on top of the stack. More...

const _XMLStackStringxml (void) const
 Returns the contents of the XML buffer. More...

void clear (void)
 Clears the stack, erasing all XML and deleting all nodes. More...

unsigned long stackSize (void) const
 Returns the number of nodes currently on the stack. Zero if empty.

void reserveXMLBufferSize (unsigned long Capacity)
 Creates a buffer for the XML at least as large as Capacity. More...

_XMLStackDocumentoperator= (const _XMLStackDocument &Instance)
 Makes a copy of the passed in XMLStackDocument instance.


Friends

class  XMLStackNode< _E, _Tr, _A >
class  XMLStackElement< _E, _Tr, _A >
class  XMLStackAttribute< _E, _Tr, _A >
class  XMLStackProcessingInstruction< _E, _Tr, _A >
class  XMLStackText< _E, _Tr, _A >
class  XMLStackCDATASection< _E, _Tr, _A >
class  XMLStackRawXML< _E, _Tr, _A >
class  XMLStackComment< _E, _Tr, _A >


Detailed Description

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>> class XMLStackDocument

XMLStackDocument is a fast stack-based XML writer.

This class creates XML by pushing and popping various node types onto an internal stack. As nodes are pushed and popped, an internal buffer holds the XML created by the nodes.

The XML is created in a std::basic_string class. The classes are written as templates so that they can support either ANSI or Unicode type strings. Two typedefs are been defined for convenience: AXMLStackDocument (for ANSI strings) and WXMLStackDocument (for Unicode).

Author(s):
Scott Moore
Version:
1.0
Date:
July 2001

Here's a sample XML file and the XMLStack code used to create it:

<?xml version="1.0" encoding="UTF-16"?>
<Book Status="BackOrdered">
  <Title>Net Etiquette</Title>
  <PubId>736</PubId>
  <Price Currency="USD">19.99</Price>
  <Author>
    <LastName>White</LastName>
    <FirstName>Johnson</FirstName>
  </Author>
</Book>


WXMLStackDocument Doc;  // Unicode version

Doc.pushProcessingInstruction(L"xml") = L"version='1.0' encoding='UTF-16'";
Doc.pop();  // pops the processing instruction

Doc.pushElement(L"Book");
Doc.top().createAttribute(L"Status") = L"BackOrdered";

Doc.pushElement(L"Title") = L"Net Etiquette";
Doc.pop();  // pops <Title>

Doc.pushElement(L"PubId") = 736;
Doc.pop();  // pops <PubId>

Doc.pushElement(L"Price").createAttribute(L"Currency") = L"USD";
Doc.top().setValue(19.99, 2);  // Assign 19.99 to <Price>
Doc.pop();  // pops <Price>

Doc.pushElement(L"Author");
Doc.pushElement(L"LastName") = L"White";
Doc.pop();  // pops <LastName>

Doc.pushElement(L"FirstName").setValue(L"Johnson");
Doc.popAll(); // Pops off all remaining nodes

Here's another example which demostrates the namespace capabilities:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:TS="http://www.time.gov/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <TS:GetCurrentTimeRequest>
      <TimeZone>Eastern</TimeZone>
    </TS:GetCurrentTimeRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


AXMLStackDocument Doc;  // ANSI version

Doc.pushElement("SOAP-ENV:Envelope", 
  "http://schemas.xmlsoap.org/soap/envelope/");
Doc.top().createAttribute("SOAP-ENV:encodingStyle") =
  "http://schemas.xmlsoap.org/soap/encoding/";
Doc.top().createAttribute("xmlns:TS") = "http://www.time.gov/";

Doc.pushElement("SOAP-ENV:Header");
Doc.pop();

Doc.pushElement("SOAP-ENV:Body");

// Don't pass the namespace URI because it was already declared in an
// ancestor element.  We only need to place the namespace prefix TS
// in front of the node name to place it in the "http://www.time.gov/"
// namespace.
Doc.pushElement("TS:GetCurrentTimeRequest");

Doc.pushElement("TimeZone") = "Eastern";
Doc.popAll(); // Pops off all remaining nodes

Definition at line 2000 of file XMLStack.h.


Member Typedef Documentation

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackCDATASection<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackCDATASection
 

Definition at line 2008 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackComment<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackComment
 

Definition at line 2009 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackDocument<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackDocument<_E, _Tr, _A>
 

Definition at line 2004 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackElement<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackElement
 

Definition at line 2006 of file XMLStack.h.

Referenced by pushElement().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackNode<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackNode
 

Definition at line 2005 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackProcessingInstruction<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackProcessingInstruction
 

Definition at line 2010 of file XMLStack.h.

Referenced by pushProcessingInstruction().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackRawXML<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackRawXML
 

Definition at line 2011 of file XMLStack.h.

Referenced by pushRawXML().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef std::basic_string<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackString
 

Definition at line 2003 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
typedef XMLStackText<_E, _Tr, _A> XMLStackDocument<_E, _Tr, _A>::_XMLStackText
 

Definition at line 2007 of file XMLStack.h.

Referenced by pushText().


Constructor & Destructor Documentation

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
XMLStackDocument<_E, _Tr, _A>::XMLStackDocument<_E, _Tr, _A> ( unsigned long InitialBufferSize = 1024 ) [inline]
 

Constructor which takes an optional XML buffer size.

Parameters:
InitialBufferSize   The initial size of the XML buffer (in characters, not bytes). See reserveXMLBufferSize() for details.

Definition at line 2019 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
XMLStackDocument<_E, _Tr, _A>::XMLStackDocument<_E, _Tr, _A> ( const _XMLStackDocument<_E, _Tr, _A> & Instance ) [inline]
 

Copy constructor.

Definition at line 2027 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
XMLStackDocument<_E, _Tr, _A>::~XMLStackDocument<_E, _Tr, _A> ( ) [inline]
 

Destructor.

Definition at line 2033 of file XMLStack.h.


Member Function Documentation

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
void XMLStackDocument<_E, _Tr, _A>::clear ( void ) [inline]
 

Clears the stack, erasing all XML and deleting all nodes.

Note:
This will reset the internal XML buffer to a default size. Call reserveXMLBufferSize() to allocate additional buffer memory if desired.

Definition at line 2343 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackDocument<_E, _Tr, _A> & XMLStackDocument<_E, _Tr, _A>::operator= ( const _XMLStackDocument<_E, _Tr, _A> & Instance ) [inline]
 

Makes a copy of the passed in XMLStackDocument instance.

Definition at line 2371 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
void XMLStackDocument<_E, _Tr, _A>::pop ( void ) [inline]
 

Pops the top node off the stack.

Any XML that wasn't previously written to the buffer by the node will be written at this time.

Exceptions:
XMLStackException   Thrown if no nodes are on the stack.

Definition at line 2045 of file XMLStack.h.

Referenced by popAll(), and XMLStackElement::setValue().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
void XMLStackDocument<_E, _Tr, _A>::popAll ( void ) [inline]
 

Repeatedly calls pop() until no more nodes exist on the stack.

If no nodes exist on the stack, then this method does nothing.

Definition at line 2060 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackCDATASection & XMLStackDocument<_E, _Tr, _A>::pushCDATASection ( const _XMLStackString & Data ) [inline]
 

Pushes a CDATA section node on the stack.

Like text nodes, CDATA sections contain raw data. However, the special characters '<' and '&' do not need to be escaped. CDATA sections can be used to quote or escape blocks of text to keep that text from being interpreted as markup language. The only delimiter that CDATA recognizes is "]]>", which ends the CDATA section. Unfortunately, if this delimiter can possibly appear in your data, you will need to use a XMLStackText node, at least for part of the data.

Parameters:
Data   The text that will be placed in the XML.

Returns:
Returns the instance of the XMLStackCDATASection that was created.
Exceptions:
XMLStackException   Thrown if the delimiter "]]>" exists in Data or if the parent node cannot have child nodes.

Definition at line 2193 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackComment & XMLStackDocument<_E, _Tr, _A>::pushComment ( const _XMLStackString & Data ) [inline]
 

Pushes a comment node on the stack.

Comments cannot contain the character sequence "--".

Parameters:
Data   The text that will be placed in the XML between the comment delimiters .

Returns:
Returns the instance of the XMLStackComment that was created.
Exceptions:
XMLStackException   Thrown if the delimiter "--" exists in Data or if the parent node cannot have child nodes.

Definition at line 2222 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackElement & XMLStackDocument<_E, _Tr, _A>::pushElement ( const _XMLStackString & Name,
const _XMLStackString & NamespaceURI ) [inline]
 

Pushes an element node on the stack and declares the passed in namespace.

The element name must conform to the rules for valid element names. Only some basic checking is done to make sure the name is valid, and only when the _DEBUG preprocessor symbol is defined.

If a NamespaceURI is provided, no checking is performed to see if it was declared in an ancestor element; it will be written out regardless. If you want the element in a namespace but don't want the xmlns declaration again, only prefix the element name with the namespace qualifier (e.g., "NamespaceQualifier:ElementName"). Don't provide the NamespaceURI.

Parameters:
Name   The name of the XML tag, with any namespace prefix included if present.
NamespaceURI   String defining the namespace URI. If specified, the node is created in the context of the namespaceURI with the prefix specified on the node name. If the Name parameter does not have a prefix, this is treated as the default namespace.

Returns:
Returns the instance of the XMLStackElement that was created.
Exceptions:
XMLStackException   Thrown if Name is invalid or if the parent node does not allow children.

Definition at line 2127 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackElement & XMLStackDocument<_E, _Tr, _A>::pushElement ( const _XMLStackString & Name ) [inline]
 

Pushes an element node on the stack.

The element name must conform to the rules for valid element names. Only some basic checking is done to make sure the name is valid, and only when the _DEBUG preprocessor symbol is defined.

Parameters:
Name   The name of the element node

Returns:
Returns the instance of the XMLStackElement that was created.
Exceptions:
XMLStackException   Thrown if Name is invalid or if the parent node does not allow children.

Definition at line 2083 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackProcessingInstruction & XMLStackDocument<_E, _Tr, _A>::pushProcessingInstruction ( const _XMLStackString & Target ) [inline]
 

Pushes a processing instruction node on the stack.

Represents a processing instruction, which XML defines to keep processor-specific information in the text of the document.

Parameters:
Target   The application to which this processing instruction is directed

Returns:
Returns the instance of the XMLStackProcessingInstruction that was created.
Exceptions:
XMLStackException   Thrown if Target is empty or the parent node cannot have child nodes.

Definition at line 2253 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackRawXML & XMLStackDocument<_E, _Tr, _A>::pushRawXML ( const _XMLStackString & PushXML,
const _XMLStackString & PopXML ) [inline]
 

Pushes a raw XML node on the stack.

This node is used when you want to add raw XML to the buffer without any processing performed on it. Other nodes can be pushed on top of this node type (e.g., child nodes).

Parameters:
PushXML   This is the XML that is added to the buffer immediately (during the push operation). It can be empty.
PopXML   This XML is added to the buffer at the time this node is popped off the stack. It can be empty.

Returns:
Returns the instance of the XMLStackRawXML that was created.
Exceptions:
XMLStackException   Thrown if the parent node cannot have child nodes.

Definition at line 2287 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackText & XMLStackDocument<_E, _Tr, _A>::pushText ( const _XMLStackString & Data ) [inline]
 

Pushes a text node on the stack.

Text nodes contain raw data that is placed in the XML stream. Automatic conversion is performed for the reserved characters '<' and '&'.

Parameters:
Data   The text that will be placed in the XML.

Returns:
Returns the instance of the XMLStackText that was created.
Exceptions:
XMLStackException   Thrown if the parent node does not allow children.

Definition at line 2158 of file XMLStack.h.

Referenced by XMLStackElement::setValue().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
void XMLStackDocument<_E, _Tr, _A>::reserveXMLBufferSize ( unsigned long Capacity ) [inline]
 

Creates a buffer for the XML at least as large as Capacity.

This is optional and purely for performance. If you have a good idea of the final buffer size, setting this value early on will give better performance. Otherwise, the buffer will grow as needed.

Parameters:
Capacity   The size of the buffer (in characters, not bytes) to reserve. If Capacity is smaller than the current size, then this method does nothing.

Definition at line 2362 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
unsigned long XMLStackDocument<_E, _Tr, _A>::stackSize ( void ) const [inline]
 

Returns the number of nodes currently on the stack. Zero if empty.

Definition at line 2350 of file XMLStack.h.

Referenced by top().

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
const _XMLStackNode & XMLStackDocument<_E, _Tr, _A>::top ( void ) const [inline]
 

Returns the node on top of the stack.

Exceptions:
XMLStackException   Thrown if stackSize() == 0

Definition at line 2321 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
_XMLStackNode & XMLStackDocument<_E, _Tr, _A>::top ( void ) [inline]
 

Returns the node on top of the stack.

Exceptions:
XMLStackException   Thrown if stackSize() == 0

Definition at line 2308 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
const _XMLStackString & XMLStackDocument<_E, _Tr, _A>::xml ( void ) const [inline]
 

Returns the contents of the XML buffer.

Note:
If nodes are still on the stack, the XML will probably not be well-formed.

Definition at line 2335 of file XMLStack.h.


Friends And Related Function Documentation

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackAttribute< _E, _Tr, _A > [friend]
 

Definition at line 2414 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackCDATASection< _E, _Tr, _A > [friend]
 

Definition at line 2417 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackComment< _E, _Tr, _A > [friend]
 

Definition at line 2419 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackElement< _E, _Tr, _A > [friend]
 

Definition at line 2413 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackNode< _E, _Tr, _A > [friend]
 

Definition at line 2412 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackProcessingInstruction< _E, _Tr, _A > [friend]
 

Definition at line 2415 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackRawXML< _E, _Tr, _A > [friend]
 

Definition at line 2418 of file XMLStack.h.

template<class _E, class _Tr = std::char_traits<_E>, class _A = std::allocator<_E>>
friend class XMLStackText< _E, _Tr, _A > [friend]
 

Definition at line 2416 of file XMLStack.h.


The documentation for this class was generated from the following file:
Generated at Mon Aug 6 11:54:21 2001 for XMLStack by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001