5.23

1 files changed, 0 insertions, 684 deletions

diff --git a/zenxml/summary.dox b/zenxml/summary.dox
deleted file mode 100644
index abe0537d..00000000
--- a/zenxml/summary.dox
+++ /dev/null
@@ -1,684 +0,0 @@
-// **************************************************************************
-// * This file is part of the zen::Xml project. It is distributed under the *
-// * Boost Software License: http://www.boost.org/LICENSE_1_0.txt           *
-// * Copyright (C) Zenju (zenju AT gmx DOT de) - All Rights Reserved        *
-// **************************************************************************
-
-/**
-\mainpage Overview
-
-\li \ref sec_Rationale
-\li \ref sec_Quick_Start
-\li \ref sec_Supported_Platforms
-\li \ref sec_Flexible_Programming_Model
-\li \ref sec_Structured_XML_element_access
-\li \ref sec_Access_XML_attributes
-\li \ref sec_Automatic_conversion_built_in
-\li \ref sec_Automatic_conversion_string
-\li \ref sec_Automatic_conversion_STL
-\li \ref sec_Support_user_defined
-\li \ref sec_Structured_user_types
-\li \ref sec_Type_Safety
-
-\section sec_Rationale Rationale
-
-zen::Xml is an XML library serializing structured user data in a convenient way.
-Using compile-time information gathered by techniques of template metaprogramming it minimizes the manual overhead required and frees the user from implementing fundamental type conversions
-by himself. Basic data types such as
-- \b all built-in arithmetic numbers, 
-- \b all kinds of string classes and "string-like" types,
-- \b all types defined as STL containers
-
-are handled automatically. Thereby a large number of recurring problems is solved by the library:
-- generic number to string conversions
-- generic char to wchar_t conversions (UTF) for custom string classes in a platform independent manner
-- serialization of arbitrary STL container types
-- simple integration: header-only, no extra dependencies, fully portable
-- support arbitrary string classes everywhere: for file names, XML element names, attribute names, values, ...
-- XML library built on C++11 with focus on elegance, minimal code size, flexibility and performance
-- easily extensible API: allow for internationalization, fine-granular error handling, and custom file I/O
-
-The design follows the philosophy of the Loki library: \n
-http://loki-lib.sourceforge.net/index.php?n=Main.Philosophy
-
-\section sec_Quick_Start Quick Start
-
-1. Download zen::Xml: http://sourceforge.net/projects/zenxml
-
-2. Setup one of the following preprocessor macros for your project to identify the platform (this is only required if you use C-stream-based file IO)
-\code
-    ZEN_WIN
-    ZEN_LINUX	
-	ZEN_MAC
-\endcode
-
-3. For optimal performance define this global macro in release build: (following convention of the <tt>assert</tt> macro)
-\code
-    NDEBUG
-\endcode
-
-4. Include the main header:
-\code
-#include <zenxml/xml.h>
-\endcode
-
-5. Start serializing user data:
-
-\code
-size_t a = 10;
-double b = 2.0;
-int    c = -1;
-\endcode
-
-\code
-zen::XmlDoc doc; //empty XML document
-
-zen::XmlOut out(doc); //the simplest way to fill the document is to use a data output proxy
-out["elem1"](a); //
-out["elem2"](b); //map data types to XML elements
-out["elem3"](c); //
-
-try
-{
-    save(doc, "file.xml"); //throw zen::XmlFileError
-}
-catch (const zen::XmlFileError& e) { /* handle error */ }
-\endcode
-
-The following XML file will be created:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <elem1>10</elem1>
-    <elem2>2.000000</elem2>
-    <elem3>-1</elem3>
-</Root>
-\endverbatim
-
-Load an XML file and map its content to user data:
-\code
-zen::XmlDoc doc; //empty XML document
-
-try
-{
-    load("file.xml", doc); //throw XmlFileError, XmlParsingError
-}
-catch (const zen::XmlError& e) { /* handle error */ }
-
-zen::XmlIn in(doc); //the simplest way to read the document is to use a data input proxy
-in["elem1"](a); //
-in["elem2"](b); //map XML elements into user data
-in["elem3"](c); //
-
-//check for mapping errors, i.e. missing elements or conversion errors: you may consider these as warnings only
-if (in.errorsOccured())
-{
-   std::vector<std::wstring> failedElements = in.getErrorsAs<std::wstring>();
-   /* generate error message showing the XML element names that failed to convert */
-}
-\endcode
-
-
-\section sec_Supported_Platforms Supported Platforms
-
-zen::Xml is written in a platform independent manner and runs on any rudimentary C++11 compliant compiler.
-It has been tested successfully under:
-
-- Windows:
-   -# Visual C++ 2010 - 32 bit
-   -# Visual C++ 2010 - 64 bit
-   -# MinGW: GCC 4.5.2 - 32 bit
-
-- Linux:
-   -# GCC 4.5.2 - 32 bit
-   -# GCC 4.5.2 - 64 bit
-
-- Mac OS X:
-   -# Clang 3.2 - 64 bit
-
-<b>Note:</b> In order to enable C++11 features in GCC it is required to specify either of the following compiler options:
-\verbatim
--std=c++11
--std=c++0x
--std=gnu++0x
-\endverbatim
-
-
-\section sec_Flexible_Programming_Model Flexible Programming Model
-
-Depending on what granularity of control is required in a particular application, zen::Xml allows the user to choose between full control or simplicity.
-\n\n
-The library is structured into the following parts, each of which can be used in isolation:
-\n\n
-\b \<File\> \n
-|\n
-| io.h\n
-|\n
-<b>\<Byte Stream\></b>\n
-|\n
-| parser.h\n
-|\n
-<b>\<Document Object Model\></b>\n
-|\n
-| bind.h\n
-|\n
-<b>\<C++ user data\></b>
-\n\n
-
-- Save an XML document to memory
-\code
-zen::XmlDoc doc;
-    ... //fill it
-std::string stream = serialize(doc); //throw ()
-/* you now have a binary XML stream */
-
-saveStream(stream, "file.xml"); //throw XmlFileError
-//if all you need is to store XmlDoc in a file direcly you can use zen::save() instead
-\endcode
-
-- Load XML document from memory
-\code
-//get XML byte stream:
-std::string stream = loadStream("file.xml"); //throw XmlFileError
-
-zen::XmlDoc doc;
-//parse byte stream into an XML document:
-parse(stream, doc); //throw XmlParsingError
-//if all you need is to load an XmlDoc from a file you can use zen::load() directly
-\endcode
-
-- Fine-granular error checking with the data input proxy
-\code
-zen::XmlIn in(doc);
-//map XML elements into user data
-if (!in["elem1"](a))
-   throw MyCustomException();
-if (!in["elem2"](b))
-   throw MyCustomException();
-if (!in["elem3"](c))
-   throw MyCustomException();
-
-//if (in.errorsOccured()) ...  <- not required here: contains the same conversion errors checked manually before
-\endcode
-
-- Access the Document Object Model directly (without input/output proxy)
-\n\n
-The full power of type conversions which is available via the input/output proxy classes zen::XmlIn and zen::XmlOut is also available for the document object model!
-\code
-using namespace zen;
-
-XmlDoc doc;
-
-XmlElement& child = doc.root().addChild("elem1");
-child.setValue(1234);
-
-save(doc, "file.xml"); //throw XmlFileError
-\endcode
-\n
-\code
-using namespace zen;
-
-XmlDoc doc;
-load("file.xml", doc); //throw XmlFileError, XmlParsingError
-
-XmlElement* child = doc.root().getChild("elem1");
-if (child)
-{
-    int value = -1;
-    if (!child->getValue(value))
-        ... //handle conversion error
-}
-else
-    ... //XML element not found
-\endcode
-
-
-\section sec_Structured_XML_element_access Structured XML element access
-
-\code
-//write a value into one deeply nested XML element - note the different types used seamlessly: char[], wchar_t[], char, wchar_t, int
-zen::XmlOut out(doc);
-out["elemento1"][L"элемент2"][L"要素3"][L"στοιχείο4"]["elem5"][L"元素6"][L'元']['z'](-1234);
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <elemento1>
-        <элемент2>
-            <要素3>
-                <στοιχείο4>
-                    <elem5>
-                        <元素6>
-                            <元>
-                                <z>-1234</z>
-                            </元>
-                        </元素6>
-                    </elem5>
-                </στοιχείο4>
-            </要素3>
-        </элемент2>
-    </elemento1>
-</Root>
-\endverbatim
-
-
-\section sec_Access_XML_attributes Access XML attributes
-
-\code
-zen::XmlDoc doc;
-
-zen::XmlOut out(doc);
-out["elem"].attribute("attr1",   -1); //
-out["elem"].attribute("attr2",  2.1); //write data into XML attributes
-out["elem"].attribute("attr3", true); //
-
-save(doc, "file.xml"); //throw XmlFileError
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <elem attr1="-1" attr2="2.1" attr3="true"/>
-</Root>
-\endverbatim
-
-
-\section sec_Automatic_conversion_built_in Automatic conversion for built-in arithmetic types
-
-All built-in arithmetic types and <tt>bool</tt> are detected at compile time and a proper conversion is applied. 
-Common conversions for integer-like types such as <tt>int</tt>, <tt>long</tt>, <tt>long long</tt>, ect. as well as floating point types are optimized for maximum performance.
-
-\code
-zen::XmlOut out(doc);
-
-out["int"]   (-1234);
-out["double"](1.23);
-out["float"] (4.56f);
-out["ulong"] (1234UL);
-out["bool"]  (false);
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <int>-1234</int>
-    <double>1.23</double>
-    <float>4.56</float>
-    <ulong>1234</ulong>
-    <bool>false</bool>
-</Root>
-\endverbatim
-
-
-\section sec_Automatic_conversion_string Automatic conversion for string-like types
-
-The document object model of zen::Xml internally stores all names and values as a std::string. Consequently everything that is not a std::string but is "string-like" is UTF-converted
-into a std::string representation. By default zen::Xml accepts all character arrays like <tt>char[]</tt>, <tt>wchar_t[]</tt>, <tt>char*</tt>, <tt>wchar_t*</tt>, single characters like 
-<tt>char</tt>, <tt>wchar_t</tt>, standard string classes like <tt>std::string</tt>, <tt>std::wstring</tt> and user-defined string classes.
-If the input string is based on <tt>char</tt>, it will simply be copied and thereby preserves any local encodings. If the input string is based on <tt>wchar_t</tt> it will
-be converted to an UTF-8 encoded <tt>std::string</tt>. The correct <tt>wchar_t</tt> encoding of the system will be detected at compile time, for example UTF-16 on Windows, 
-UTF-32 on most Linux distributions.
-
-<b>Note:</b> User-defined string classes are automatically supported if they fulfill the following <b>string concept</b> by defining:
-    -# A typedef named <tt>value_type</tt> for the underlying character type: must be \p char or \p wchar_t
-    -# A member function <tt>c_str()</tt> returning something that can be converted into a <tt>const value_type*</tt>
-    -# A member function <tt>length()</tt> returning the number of characters returned by <tt>c_str()</tt>
-
-\code
-std::string  elem1 = "elemento1";
-std::wstring elem2 = L"элемент2";
-wxString     elem3 = L"要素3";
-MyString     elem4 = L"στοιχείο4";
-
-zen::XmlOut out(doc);
-
-out["string"]    (elem1);
-out["wstring"]   (elem2);
-out["wxString"]  (elem3);
-out["MyString"]  (elem4);
-out["char[6]"]   ("elem5");
-out["wchar_t[4]"](L"元素6");
-out["wchar_t"]   (L'元');
-out["char"]      ('z');
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <string>elemento1</string>
-    <wstring>элемент2</wstring>
-    <wxString>要素3</wxString>
-    <MyString>στοιχείο4</MyString>
-    <char[6]>elem5</char[6]>
-    <wchar_t[4]>元素6</wchar_t[4]>
-    <wchar_t>元</wchar_t>
-    <char>z</char>
-</Root>
-\endverbatim
-
-
-\section sec_Automatic_conversion_STL Automatic conversion for STL container types
-
-- User-defined STL compatible types are automatically supported if they fulfill the following <b>container concept</b> by defining:
-    -# A typedef named <tt>value_type</tt> for the underlying element type of the container
-    -# A typedef named <tt>iterator</tt> for a non-const iterator into the container
-    -# A typedef named <tt>const_iterator</tt> for a const iterator into the container
-\n\n
-    -# A member function <tt>begin()</tt> returning an iterator pointing to the first element in the container
-    -# A member function <tt>end()</tt> returning an iterator pointing just after the last element in the container
-    -# A member function <tt>insert()</tt> with the signature <tt>iterator insert(iterator position, const value_type& x)</tt>
-    -# A member function <tt>clear()</tt> removing all elements from the container
-
-- In order to support combinations of user types and STL containers such as <tt>std::vector<MyType></tt> or <tt>std::vector<std::list<MyType>></tt> it is sufficient to 
-only integrate <tt>MyType</tt> into zen::Xml. \n
-See \ref sec_Support_user_defined
-    
-\code
-std::deque   <float>         testDeque;
-std::list    <size_t>        testList;
-std::map     <double, char>  testMap;
-std::multimap<short, double> testMultiMap;
-std::set     <int>           testSet;
-std::multiset<std::string>   testMultiSet;
-std::vector  <wchar_t>       testVector;
-std::vector  <std::list<wchar_t>> testVectorList;
-std::pair    <char, wchar_t> testPair;
-
-/* fill container */
-
-zen::XmlOut out(doc);
-
-out["deque"]    (testDeque);
-out["list"]     (testList);
-out["map"]      (testMap);
-out["multimap"] (testMultiMap);
-out["set"]      (testSet);
-out["multiset"] (testMultiSet);
-out["vector"]   (testVector);
-out["vect_list"](testVectorList);
-out["pair" ]    (testPair);
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <deque>
-        <Item>1.234</Item>
-        <Item>5.678</Item>
-    </deque>
-    <list>
-        <Item>1</Item>
-        <Item>2</Item>
-    </list>
-    <map>
-        <Item>
-            <one>1.1</one>
-            <two>a</two>
-        </Item>
-        <Item>
-            <one>2.2</one>
-            <two>b</two>
-        </Item>
-    </map>
-    <multimap>
-        <Item>
-            <one>3</one>
-            <two>99</two>
-        </Item>
-        <Item>
-            <one>3</one>
-            <two>100</two>
-        </Item>
-        <Item>
-            <one>4</one>
-            <two>101</two>
-        </Item>
-    </multimap>
-    <set>
-        <Item>1</Item>
-        <Item>2</Item>
-    </set>
-    <multiset>
-        <Item>1</Item>
-        <Item>1</Item>
-        <Item>2</Item>
-    </multiset>
-    <vector>
-        <Item>Ä</Item>
-        <Item>Ö</Item>
-    </vector>
-    <vect_list>
-        <Item>
-            <Item>ä</Item>
-            <Item>ö</Item>
-            <Item>ü</Item>
-        </Item>
-        <Item>
-            <Item>ä</Item>
-            <Item>ö</Item>
-            <Item>ü</Item>
-        </Item>
-    </vect_list>
-    <pair>
-        <one>a</one>
-        <two>â</two>
-    </pair>
-</Root>
-\endverbatim
-
-
-\section sec_Support_user_defined Support for user-defined types
-
-User types can be integrated into zen::Xml by providing specializations of zen::readText() and zen::writeText() or zen::readStruc() and zen::writeStruc().
-The first pair should be used for all non-structured types that can be represented as a simple text string. This specialization is then used to convert the type to XML elements
-and XML attributes. The second pair should be specialized for structured types that require an XML representation as a hierarchy of elements. This specialization is used when converting
-the type to XML elements only.
-\n\n
-See section \ref sec_Type_Safety for a discussion of type categories.
-\n\n
-<b>Example: Specialization for an enum type</b>
-\code
-enum UnitTime
-{
-    UNIT_SECOND,
-    UNIT_MINUTE,
-    UNIT_HOUR
-};
-
-namespace zen
-{
-template <> inline
-void writeText(const UnitTime& value, std::string& output)
-{
-    switch (value)
-    {
-        case UNIT_SECOND: output = "second"; break;
-        case UNIT_MINUTE: output = "minute"; break;
-        case UNIT_HOUR:   output = "hour"  ; break;
-    }
-}
-
-template <> inline
-bool readText(const std::string& input, UnitTime& value)
-{
-    std::string tmp = input;
-    zen::trim(tmp);
-    if (tmp == "second")
-        value = UNIT_SECOND;
-    else if (tmp == "minute")
-        value = UNIT_MINUTE;
-    else if (tmp == "hour")
-        value = UNIT_HOUR;
-    else
-        return false;
-    return true;
-}
-}
-\endcode
-
-<b>Example: Brute-force specialization for an enum type</b>
-\code
-namespace zen
-{
-template <> inline
-void writeText(const EnumType& value, std::string& output)
-{
-    output = zen::numberTo<std::string>(static_cast<int>(value)); //treat enum like an integer
-}
-
-template <> inline
-bool readText(const std::string& input, EnumType& value)
-{
-    value = static_cast<EnumType>(zen::stringTo<int>(input)); //treat enum like an integer
-    return true;
-}
-}
-\endcode
-
-<b>Example: Specialization for a structured user type</b>
-\code
-struct Config
-{
-    int a;
-    std::wstring b;
-};
-
-namespace zen
-{
-template <> inline
-void writeStruc(const Config& value, XmlElement& output)
-{
-    XmlOut out(output);
-    out["number" ](value.a);
-    out["address"](value.b);
-}
-
-template <> inline
-bool readStruc(const XmlElement& input, Config& value)
-{
-    XmlIn in(input);
-    bool rv1 = in["number" ](value.a);
-    bool rv2 = in["address"](value.b);
-    return rv1 && rv2;
-}
-}
-
-int main()
-{
-    Config cfg = { 2,  L"Abc 3" };
-
-    std::vector<Config> cfgList;
-    cfgList.push_back(cfg);
-
-    zen::XmlDoc doc;
-    zen::XmlOut out(doc); //write to Xml via output proxy
-    out["config"](cfgList);
-    save(doc, "file.xml"); //throw XmlFileError
-}
-\endcode
-
-The resulting XML:
-\verbatim
-<?xml version="1.0" encoding="UTF-8"?>
-<Root>
-    <config>
-        <Item>
-            <number>2</number>
-            <address>Abc 3</address>
-        </Item>
-    </config>
-</Root>
-\endverbatim
-
-
-\section sec_Structured_user_types Structured user types
-
-Although it is possible to enable conversion of structured user types by specializing zen::readStruc() and zen::writeStruc() (see \ref sec_Support_user_defined), 
-this approach has one drawback: If a mapping error occurs when converting an XML element to structured user data, for example a child-element is missing,
-the input proxy class zen::XmlIn is only able to detect that the whole conversion failed. It cannot say which child-elements in particular failed to convert.
-\n\n
-Therefore it may be appropriate to convert structured types by calling subroutines in order to enable fine-granular logging:
-
-\code
-void readConfig(const zen::XmlIn& in, Config& cfg)
-{
-    in["number" ](value.a); //failed conversions will now be logged for each single item by XmlIn
-    in["address"](value.b); //instead of only once for the complete Config type!
-}
-
-
-void loadConfig(const wxString& filename, Config& cfg)
-{
-    zen::XmlDoc doc; //empty XML document
-
-    try
-    {
-        load(filename, doc); //throw XmlFileError, XmlParsingError
-    }
-    catch (const zen::XmlError& e) { /* handle error */ }
-
-    zen::XmlIn in(doc); 
- 
-    zen::XmlIn inConfig = in["config"]; //get input proxy for child element "config"
-  
-    readConfig(inConfig, cfg); //map child element to user data by calling subroutine
-
-    //check for mapping errors: errors occuring in subroutines are considered, too!
-    if (in.errorsOccured())
-       /* show mapping errors */
-}
-\endcode
-
-
-\section sec_Type_Safety Type Safety
-
-zen::Xml heavily uses methods of compile-time introspection in order to free the user from managing basic type conversions by himself. 
-Thereby it is important to find the right balance between automatic conversions and type safety so that program correctness is not compromised.
-In the context of XML processing three fundamental type categories can be recognized:
-
-- <b>string-like types</b>: <tt>std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...</tt>
-- <b>to-string-convertible types</b>: any string-like type, all built-in arithmetic numbers, <tt>bool</tt>
-- <b>structured types</b>: any to-string-convertible type, STL containers, <tt>std::pair</tt>, structured user types
-
-These categories can be seen as a sequence of inclusive sets:
-\verbatim
------------------------------
-| structured                |  Used as: XML element value
-| ------------------------- |           Conversion via: readStruc(), writeStruc() - may be specialized for user-defined types!
-| | to-string-convertible | |  Used as: XML element/attribute value
-| | ---------------       | |           Conversion via: readText(), writeText() - may be specialized for user-defined types!
-| | | string-like |       | |  Used as: XML element/attribute value or element name
-| | ---------------       | |           Conversion via: utfCvrtTo<>()
-| ------------------------- |
------------------------------
-\endverbatim
-
-A practical implication of this design is that conversions that do not make sense in a particular context simply lead to compile-time errors:
-\code
-zen::XmlOut out(doc);
-out[L'Z'](someValue); //fine: a wchar_t is acceptable as an element name
-out[1234](someValue); //compiler error: an integer is NOT "string-like"!
-\endcode
-\n
-\code
-int i = 0;
-std::vector<int> v;
-
-zen::XmlOut out(doc);
-out["elem1"](i); //fine: both i and v can be converted to an XML element
-out["elem2"](v); //
-
-out["elem"].attribute("attr1", i); //fine: an integer can be converted to an XML attribute
-out["elem"].attribute("attr2", v); //compiler error: a std::vector<int> is NOT "to-string-convertible"!
-\endcode
-
-  \author \b Zenju 
-  \n\n
-  <b>Email:</b> zenju AT gmx DOT de
-*/
\ No newline at end of file