updating doxygen

doc/doxygen.cfg

@@ -715,7 +715,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = .* *.cpp
+EXCLUDE_PATTERNS       = .* *.cpp */external/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

include/cereal/access.hpp

@@ -1,3 +1,5 @@
+/*! \file access.hpp
+    \brief Access control, default construction, and serialization disambiguation */
 /*
   Copyright (c) 2013, Randolph Voorhies, Shane Grant
   All rights reserved.

include/cereal/archives/json.hpp

@@ -43,13 +43,32 @@
 #include <vector>
 #include <string>
 
-#include <iostream>
-
 namespace cereal
 {
   // ######################################################################
   //! An output archive designed to save data to JSON
-  /*! \note Not working yet!
+  /*! This archive uses RapidJSON to build serialie data to JSON.
+
+      JSON archives provides a human readable output but at decreased
+      performance (both in time and space) compared to binary archives.
+
+      JSON benefits greatly from name-value pairs, which if present, will
+      name the nodes in the output.  If these are not present, each level
+      of the output will be given an automatically generated delimited name.
+
+      The precision of the output archive controls the number of decimals output
+      for floating point numbers and should be sufficiently large (i.e. at least 20)
+      if there is a desire to have binary equality between the numbers output and
+      those read in.  In general you should expect a loss of precision when going
+      from floating point to text and back.
+
+      JSON archives do not output the size information for any dynamically sized structure
+      and instead infer it from the number of children for a node.  This means that data
+      can be hand edited for dynamic sized structures and will still be readable.  This
+      is accomplished through the cereal::SizeTag object, which will cause the archive
+      to output the data as a JSON array (e.g. marked by [] instead of {}), which indicates
+      that the container is variable sized and may be edited.
+
       \ingroup Archives */
   class JSONOutputArchive : public OutputArchive<JSONOutputArchive>
   {
@@ -98,11 +117,15 @@ namespace cereal
           saveValue( base64string );
         }
 
-      //! Write the name of the upcoming node
+      //! Write the name of the upcoming node and prepare object/array state
+      /*! Since writeName is called for every value that is output, regardless of
+          whether it has a name or not, it is the place where we will do a deferred
+          check of our node state and decide whether we are in an array or an object. */
       void writeName()
       {
         NodeType const & nodeType = itsNodeStack.top();
 
+        // Start up either an object or an array, depending on state
         if(nodeType == NodeType::StartArray)
         {
           itsWriter.StartArray();
@@ -114,6 +137,7 @@ namespace cereal
           itsWriter.StartObject();
         }
 
+        // Array types do not output names
         if(nodeType == NodeType::InArray) return;
 
         if(itsNextName == nullptr)
@@ -126,9 +150,9 @@ namespace cereal
           saveValue(itsNextName);
           itsNextName = nullptr;
         }
-
       }
 
+      //! Starts a new node in the JSON output
       void startNode()
       {
         writeName();
@@ -139,6 +163,11 @@ namespace cereal
       //! Designates the most recently added node as finished
       void finishNode()
       {
+        // if we ended up serializing an empty object or array, writeName
+        // will never have been called - so start and then immediately end
+        // the object/array.
+        //
+        // We'll also end any object/arrays we happen to be in
         switch(itsNodeStack.top())
         {
           case NodeType::StartArray:
@@ -157,6 +186,7 @@ namespace cereal
         itsNameCounter.pop();
       }
 
+      //! Designates that the current node should be output as an array, not an object
       void makeArray()
       {
         itsNodeStack.top() = NodeType::StartArray;
@@ -180,16 +210,9 @@ namespace cereal
         saveValue( base64string );
       };
 
-      void setOutputType(bool outputType)
-      {
-        itsOutputType = outputType;
-      }
-
     private:
       WriteStream itsWriteStream;          //!< Rapidjson write stream
       JSONWriter itsWriter;                //!< Rapidjson writer
-      std::ostringstream itsOS;            //!< Used to format strings internally
-      bool itsOutputType;                  //!< Controls whether type information is printed
       char const * itsNextName;            //!< The next name
       std::stack<uint32_t> itsNameCounter; //!< Counter for creating unique names for unnamed nodes
       std::stack<NodeType> itsNodeStack;
@@ -197,7 +220,15 @@ namespace cereal
 
   // ######################################################################
   //! An input archive designed to load data from JSON
-  /*! \note Not working yet!
+  /*! This archive uses RapidJSON to read in a JSON archive.
+
+      Input JSON should have been produced by the JSONOutputArchive.  Data can
+      only be added to dynamically sized containers (marked by JSON arrays) -
+      the input archive will determine their size by looking at the number of child nodes.
+
+      The order of the items in the JSON archive must match what is expected in the
+      serialization functions.
+
       \ingroup Archives */
   class JSONInputArchive : public InputArchive<JSONInputArchive>
   {
@@ -207,6 +238,7 @@ namespace cereal
     typedef JSONValue::ConstValueIterator ValueIterator;
     typedef rapidjson::Document::GenericValue GenericValue;
 
+    //! An internal iterator that handles both array and object types
     class Iterator
     {
       public:
@@ -229,15 +261,6 @@ namespace cereal
           return *this;
         }
 
-        GenericValue const & name()
-        {
-          switch(itsType)
-          {
-            case Member: return itsMemberIt->name;
-            default: throw cereal::Exception("Invalid Iterator Type!");
-          }
-        }
-
         GenericValue const & value()
         {
           switch(itsType)
@@ -258,7 +281,7 @@ namespace cereal
       //! Construct, outputting to the provided stream
       /*! @param stream The stream to output to.  Can be a stringstream, a file stream, or
                         even cout! */
-      JSONInputArchive(std::istream & is) :
+      JSONInputArchive(std::istream & stream) :
         InputArchive<JSONInputArchive>(this),
         itsReadStream(is)
       {
@@ -266,11 +289,7 @@ namespace cereal
         itsValueStack.push_back(itsDocument.MemberBegin());
       }
 
-      void setNextName(char const * name)
+      //! Starts a new node, going into its proper iterator
-      {
-        itsNextName = name;
-      }
-
       void startNode()
       {
         if(itsValueStack.back().value().IsArray())
@@ -279,14 +298,13 @@ namespace cereal
           itsValueStack.push_back(itsValueStack.back().value().MemberBegin());
       }
 
+      //! Finishes the most recently started node
       void finishNode()
       {
         itsValueStack.pop_back();
         ++itsValueStack.back();
       }
 
-      void loadValue(bool & val)        { val = itsValueStack.back().value().GetBool();   ++itsValueStack.back(); }
-
       template<class T>
         typename std::enable_if<std::is_signed<T>::value && sizeof(T) < sizeof(int64_t), void>::type
         loadValue(T & val)
@@ -304,6 +322,7 @@ namespace cereal
           ++itsValueStack.back();
         }
 
+      void loadValue(bool & val)        { val = itsValueStack.back().value().GetBool();   ++itsValueStack.back(); }
       void loadValue(int64_t & val)     { val = itsValueStack.back().value().GetInt64();  ++itsValueStack.back(); }
       void loadValue(uint64_t & val)    { val = itsValueStack.back().value().GetUint64(); ++itsValueStack.back(); }
       void loadValue(float & val)       { val = itsValueStack.back().value().GetDouble(); ++itsValueStack.back(); }
@@ -338,13 +357,13 @@ namespace cereal
         std::memcpy( data, decoded.data(), decoded.size() );
       };
 
+      //! Loads the size for a SizeTag
       void loadSize(size_t & size)
       {
         size = (itsValueStack.rbegin() + 1)->value().Size();
       }
 
     private:
-      char const * itsNextName;
       ReadStream itsReadStream;               //!< Rapidjson write stream
       std::vector<Iterator> itsValueStack;    //!< Stack of values
       rapidjson::Document itsDocument;        //!< Rapidjson document
@@ -499,14 +518,19 @@ namespace cereal
   // ######################################################################
 
   //! Serializing NVP types to JSON
-  template <class Archive, class T> inline
+  template <class T> inline
-  CEREAL_ARCHIVE_RESTRICT(JSONInputArchive, JSONOutputArchive)
+  void save( JSONOutputArchive & ar, NameValuePair<T> const & t )
-  serialize( Archive & ar, NameValuePair<T> & t )
   {
     ar.setNextName( t.name );
     ar( t.value );
   }
 
+  template <class T> inline
+  void load( JSONInputArchive & ar, NameValuePair<T> & t )
+  {
+    ar( t.value );
+  }
+
   //! Saving for arithmetic to JSON
   template<class T> inline
   typename std::enable_if<std::is_arithmetic<T>::value, void>::type

include/cereal/archives/xml.hpp

@@ -65,7 +65,8 @@ namespace cereal
       The precision of the output archive controls the number of decimals output
       for floating point numbers and should be sufficiently large (i.e. at least 20)
       if there is a desire to have binary equality between the numbers output and
-      those read in.
+      those read in.  In general you should expect a loss of precision when going
+      from floating point to text and back.
 
       XML archives can optionally print the type of everything they serialize, which
       adds an attribute to each node.
@@ -259,7 +260,7 @@ namespace cereal
   }; // XMLOutputArchive
 
   // ######################################################################
-  //! An output archive designed to save data to XML
+  //! An output archive designed to load data from XML
   /*! This archive uses RapidXML to build an in memory XML tree of the
       data in the stream it is given before loading any types serialized.
 

include/cereal/cereal.hpp

@@ -1,3 +1,5 @@
+/*! \file cereal.hpp
+    \brief Main cereal functionality */
 /*
   Copyright (c) 2013, Randolph Voorhies, Shane Grant
   All rights reserved.

include/cereal/external/rapidxml/rapidxml.hpp

@@ -4,7 +4,6 @@
 // Copyright (C) 2006, 2009 Marcin Kalicinski
 // Version 1.13
 // Revision $DateTime: 2009/05/13 01:46:17 $
-//! \file rapidxml.hpp This file contains rapidxml parser and DOM implementation
 
 // If standard library is disabled, user must provide implementations of required functions and typedefs
 #if !defined(RAPIDXML_NO_STDLIB)

include/cereal/external/rapidxml/rapidxml_iterators.hpp

@@ -4,7 +4,6 @@
 // Copyright (C) 2006, 2009 Marcin Kalicinski
 // Version 1.13
 // Revision $DateTime: 2009/05/13 01:46:17 $
-//! \file rapidxml_iterators.hpp This file contains rapidxml iterators
 
 #include "rapidxml.hpp"
 

include/cereal/external/rapidxml/rapidxml_print.hpp

@@ -4,7 +4,6 @@
 // Copyright (C) 2006, 2009 Marcin Kalicinski
 // Version 1.13
 // Revision $DateTime: 2009/05/13 01:46:17 $
-//! \file rapidxml_print.hpp This file contains rapidxml printer implementation
 
 #include "rapidxml.hpp"
 

include/cereal/external/rapidxml/rapidxml_utils.hpp

@@ -4,7 +4,6 @@
 // Copyright (C) 2006, 2009 Marcin Kalicinski
 // Version 1.13
 // Revision $DateTime: 2009/05/13 01:46:17 $
-//! \file rapidxml_utils.hpp This file contains high-level rapidxml utilities that can be useful
 //! in certain simple scenarios. They should probably not be used if maximizing performance is the main objective.
 
 #include "rapidxml.hpp"

include/cereal/types/common.hpp

@@ -1,5 +1,5 @@
 /*! \file common.hpp
-    \brief Support common types
+    \brief Support common types - always included automatically
     \ingroup OtherTypes */
 /*
   Copyright (c) 2013, Randolph Voorhies, Shane Grant

sandbox_json.cpp

@@ -244,20 +244,48 @@ struct AAA
     }
 };
 
+class Stuff
+{
+  public:
+    Stuff() = default;
+
+    void fillData()
+    {
+      data = { {"imaginary", {{0, -1.0f},
+                              {0, -2.9932f},
+                              {0, -3.5f}}},
+               {"real", {{1.0f, 0},
+                         {2.2f, 0},
+                         {3.3f, 0}}} };
+    }
+
+  private:
+    std::map<std::string, std::vector<std::complex<float>>> data;
+
+    friend class cereal::access;
+
+    template <class Archive>
+    void serialize( Archive & ar )
+    {
+      ar( CEREAL_NVP(data) );
+    }
+};
+
 // ######################################################################
 int main()
 {
   std::cout << std::boolalpha << std::endl;
-  std::cout << std::setprecision(40);
 
   {
     std::ofstream os("file.json");
-    cereal::JSONOutputArchive oar( os );
+    cereal::JSONOutputArchive oar( os, 5 );
 
-    auto f = std::make_shared<Fixture>();
+    //auto f = std::make_shared<Fixture>();
-    auto f2 = f;
+    //auto f2 = f;
-    oar( f );
+    //oar( f );
-    oar( f2 );
+    //oar( f2 );
+    Stuff s; s.fillData();
+    oar( cereal::make_nvp("best data ever", s) );
   }
 
   {
@@ -266,17 +294,17 @@ int main()
     std::cout << "---------------------" << std::endl << str << std::endl << "---------------------" << std::endl;
   }
 
-  {
+  //{
-    std::ifstream is("file.json");
+  //  std::ifstream is("file.json");
-    cereal::JSONInputArchive iar( is );
+  //  cereal::JSONInputArchive iar( is );
 
-    std::shared_ptr<Fixture> f, f2;
+  //  std::shared_ptr<Fixture> f, f2;
-    iar( f, f2 );
+  //  iar( f, f2 );
-    assert( f->array[0] == 1 );
+  //  assert( f->array[0] == 1 );
-    assert( f->array[1] == 2 );
+  //  assert( f->array[1] == 2 );
-    assert( f->array[2] == 3 );
+  //  assert( f->array[2] == 3 );
-    assert( f->array[3] == 4 );
+  //  assert( f->array[3] == 4 );
-  }
+  //}
 
   return 0;
 }