documentation improved, new grouping

mrw/auto.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.7  2004/12/20 07:40:35  marc
+    documentation improved, new grouping
+
     Revision 1.6  2004/10/11 16:48:29  marc
     better comment and operators -> and * for AutoPtr
 
@@ -54,6 +57,34 @@ namespace mrw {
       (except @c malloca that only works for a subset of problems: if
       you and not a system call allocates memory), @c open and so on.
       These classes can take over the resource ownership.
+
+      The following ressource handler are predefined:
+       - mrw::AutoPtr<> is the same as std::auto_ptr, but can be stored
+         in STL containers
+         @code
+         mrw::AutoPtr<ClassName> xyz(new ClassName(a, b, c));
+         @endcode
+       - mrw::MMapHandle frees an @c mmap handle with @c munmap
+       - mrw::Auto<>::Free frees @c malloc allocated memory with @c free
+         @code
+         mrw::Auto<char*>::Free xxx((char*)malloc(15));
+         @endcode
+       - mrw::SmartPointer<> is a shared pointer that deletes memory
+         when all owners have died
+         @code
+         mrw::SmartPointer<ClassName> xyz(new ClassName(a, b, c));
+         @endcode
+       - mrw::Pipe handles UNIX pipes and closes them on exit
+       - mrw::AutoFile automatically closes open files
+       - mrw::AutoMapper calls @c munmap on memory mapped files
+       - mrw::AutoBfd automatically calls @c bfd_close
+
+     If this is not enough, you can @c typedef your own ressource
+     handler from the template class mrw::AutoResource<>. For example,
+     mrw::AutoFile is defined as:
+     @code
+     typedef mrw::AutoResource<int, int(*)(int), &close, int, -1> mrw::AutoFile;
+     @endcode
   */
   //@{
   

mrw/deque.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:35  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @defgroup StdExtdeque deque
+ */
+//@{
 
 /** @brief push a value to a deque
 
@@ -58,7 +67,7 @@ std::deque<T, A>& operator<<(std::deque<T, A>& l, const T& o) throw(std::bad_exc
     @note when something is extracted from a deque, it is removed
     from the deque, that means after every shift the deque is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/deque.hpp>
 */
 template <typename T, typename A>
 std::deque<T, A>& operator>>(std::deque<T, A>& l, T& o) throw(std::exception) {
@@ -72,6 +81,8 @@ std::deque<T, A>& operator>>(std::deque<T, A>& l, T& o) throw(std::exception) {
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/exec.cpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.9  2004/12/20 07:40:35  marc
+    documentation improved, new grouping
+
     Revision 1.8  2004/12/18 21:00:09  marc
     everything is ok, when pipes are non blocking on parent's side and blocking on client's side, and select is not used (not necessary for non blocking IO)
 
@@ -38,8 +41,8 @@
 #include <mrw/exec.hpp>
 #include <mrw/unistd.hpp>
 #include <mrw/exception.hpp>
-#include <mrw/stdext.hpp> // max
+#include <sys/wait.h> // waitpid
-#include <sys/wait.h> // waitpid#include <unistd.h> // fork, exec
+#include <unistd.h> // fork, exec
 #include <string.h> // memcpy
 #include <assert.h> // assert
 
@@ -252,7 +255,7 @@ mrw::Exec& mrw::Exec::execute(const std::string& input, bool exc)
     stdOut.close_in();
     stdErr.close_in();
     stdIn.connect_cin();
-    stdOut.connect_cout(); // if cin is non blocking, child terminates here?!?
+    stdOut.connect_cout();
     stdErr.connect_cerr();
     execvp(_cmd->path(), _cmd->args());
     exit(1); // execute failed

mrw/list.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:35  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,23 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @defgroup StdExtSTL STL extensions
+
+    The STL extensions give you the possibility to fill up a container
+    by shifting in values, and to extract values by shifting them out.
+    @code
+    std::list<std::string> l;
+    l<<"hello"<<"world"<<"this"<<is"<<"cool";
+    for (std::string s; l.size();) {
+      l>>s;
+      std::cout<<"list contains: "<<s<<std::endl;
+    }
+    @endcode
+*/
+//@{
+/** @defgroup StdExtliststl list
+ */
+//@{
 
 /** @brief push a value to a list
 
@@ -58,7 +78,7 @@ std::list<T, A>& operator<<(std::list<T, A>& l, const T& o) throw(std::bad_excep
     @note when something is extracted from a list, it is removed
     from the list, that means after every shift the list is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/list.hpp>
 */
 template <typename T, typename A>
 std::list<T, A>& operator>>(std::list<T, A>& l, T& o) throw(std::exception) {
@@ -72,6 +92,8 @@ std::list<T, A>& operator>>(std::list<T, A>& l, T& o) throw(std::exception) {
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/map.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:35  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @defgroup StdExtmap map
+ */
+//@{
 
 /** @brief insert a value in a map
 
@@ -66,7 +75,7 @@ std::map<K, T, C, A>& operator<<(std::map<K, T, C, A>& l, const std::pair<K, T>&
     @note when something is extracted from a map, it is removed
     from the map, that means after every shift the map is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/map.hpp>
 */
 template <typename K, typename T, class C, typename A>
 std::map<K, T, C, A>& operator>>(std::map<K, T, C, A>& l, std::pair<K, T>& o)
@@ -81,6 +90,8 @@ std::map<K, T, C, A>& operator>>(std::map<K, T, C, A>& l, std::pair<K, T>& o)
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/multimap.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @addtogroup StdExtmultimap multimap
+ */
+//@{
 
 /** @brief insert a value in a multimap
 
@@ -62,7 +71,7 @@ std::multimap<K, T, C, A>& operator<<(std::multimap<K, T, C, A>& l, const std::p
     @note when something is extracted from a multimap, it is removed
     from the multimap, that means after every shift the multimap is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/multimap.hpp>
 */
 template <typename K, typename T, class C, typename A>
 std::multimap<K, T, C, A>& operator>>(std::multimap<K, T, C, A>& l, std::pair<K, T>& o)
@@ -77,6 +86,8 @@ std::multimap<K, T, C, A>& operator>>(std::multimap<K, T, C, A>& l, std::pair<K,
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/multiset.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @defgroup StdExtmultiset multiset
+ */
+//@{
 
 /** @brief insert a value in a multiset
 
@@ -58,7 +67,7 @@ std::multiset<T, C, A>& operator<<(std::multiset<T, C, A>& l, const T& o) throw(
     @note when something is extracted from a multiset, it is removed
     from the multiset, that means after every shift the multiset is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/multiset.hpp>
 */
 template <typename T, class C, typename A>
 std::multiset<T, C, A>& operator>>(std::multiset<T, C, A>& l, T& o) throw(std::exception) {
@@ -72,6 +81,8 @@ std::multiset<T, C, A>& operator>>(std::multiset<T, C, A>& l, T& o) throw(std::e
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/regexp.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.4  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.3  2004/12/17 16:27:58  marc
     error in documentation syntax
 
@@ -28,6 +31,9 @@
 namespace mrw {
 
   /** @defgroup regexp Regular Expressions
+   */
+  //@{
+  /** @defgroup regexpregexp Regular Expressions
 
       A simple wrapper around the C POSIX regular expression library
       with a C++ Interface.
@@ -141,4 +147,5 @@ namespace mrw {
   
   };
   //@}
+  //@}
 }

mrw/set.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @defgroup StdExtset set
+ */
+//@{
 
 /** @brief insert a value in a set
 
@@ -64,7 +73,7 @@ std::set<T, C, A>& operator<<(std::set<T, C, A>& l, const T& o)
     @note when something is extracted from a set, it is removed
     from the set, that means after every shift the set is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/set.hpp>
 */
 template <typename T, class C, typename A>
 std::set<T, C, A>& operator>>(std::set<T, C, A>& l, T& o)
@@ -79,6 +88,8 @@ std::set<T, C, A>& operator>>(std::set<T, C, A>& l, T& o)
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif

mrw/stdext.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.4  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.3  2004/12/17 16:27:28  marc
     error in documentation: group forgotten
 
@@ -23,14 +26,35 @@
 
 #include <string>
 #include <iostream>
+#include <algorithm>
 
 namespace mrw {
 
-/** @addtogroup StdExt
+  /** @addtogroup StdExt
- */
+   */
-//@{
+  //@{
+
+  /** @defgroup stdextReadline Read Line
+
+      The global functions mrw::getline read exactly one line from a
+      stream, without the need of a buffer. It is therefore guaranteed
+      that a whole line is read, regardless of the length of the
+      line. The result is returned as std::string.
+
+      @code
+      // first syntax returns a string:
+      std::string line(mrw::readline(std::cin));
+      // second syntax returns the stream:
+      while (mrw::readline(std::cin, line))
+        std::cout<<"Read: "<<line<<std::endl;
+      @endcode
+  */
+  //@{
+
+  /** @brief Deprecated! Do not use any more!
 
-  /** @brief get the lower of two values
+      @deprecated Use @c std::min from @c
+                  #include&nbsp;&lt;algorithm&gt; instead!
 
       Get the lower of two values.
       If both values are equal, @c a is returned.
@@ -42,10 +66,15 @@ namespace mrw {
       @pre @c T must support <code>bool operator>(conbst T&, constT&)</code>
   */
   template<typename T> const T& min(const T& a, const T& b) {
-    return a > b ? b : a;
+    /// calls @c std::min(a,&nbsp;b);
+    /// @deprecated will be removed in next major release
+    return std::min(a, b);
   }
   
-  /** @brief get the higher of two values
+  /** @brief Deprecated! Do not use any more!
+
+      @deprecated Use @c std::max from @c
+                  #include&nbsp;&lt;algorithm&gt; instead!
 
       Get the higher of two values.
       If both values are equal, @c a is returned.
@@ -57,12 +86,15 @@ namespace mrw {
       @pre @c T must support <code>bool operator<(conbst T&, constT&)</code>
   */
   template<typename T> const T& max(const T& a, const T& b) {
-    return a < b ? b : a;
+    /// calls @c std::max(a,&nbsp;b);
+    /// @deprecated will be removed in next major release
+    return std::max(a, b);
   }
 
   /** @brief read one line from a stream
 
       Reads one line from a stream, up to delimiter @c d.
+      The delimiter is not appended to the string.
 
       @param is the stream to read from
       @param d the end of line delimiter
@@ -74,6 +106,7 @@ namespace mrw {
   /** @brief read one line from a stream
 
       Reads one line from a stream, up to delimiter @c d.
+      The delimiter is not appended to the string.
 
       @param is the stream to read from
       @param s the string to place the line in
@@ -85,4 +118,5 @@ namespace mrw {
   std::istream& getline(std::istream& is, std::string& s, char d = '\n');
 
   //@}
+  //@}
 }

mrw/string.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.3  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.2  2004/12/16 13:09:47  marc
     inlines forgotten
 
@@ -28,6 +31,33 @@ namespace mrw {
   
   /** @defgroup StdExt Extensions for C++ Standard Libraries
 
+      @section stdextfeatures Features
+
+      @subsection stdextstringfeatures Extensions to std::string
+
+       - Shift operator to shift any kind of values into a string
+         without the need for a stingstream.
+       - Addition operators to add, means concatenate, any kind of
+         value (e.g. integer) to a string without the need for a
+         stringstream.
+       - Function mrw::string to convert any type of variable to a
+         string without the need for a stringstream.
+       - Function mrw::to<> to convert a string to any type of
+         variable without the need for a stringstream.
+
+      @subsection stdextstlfeatures Extensions to STL containers
+
+       - Shift operator to shift elements from and to all STL
+         containers.
+
+      @subsection stdextstreams Extensions for stream handling
+
+       - Function mrw::getline to read a whole line from a stream (file)
+         without the need of a buffer and without having to check
+         whether the buffer was large enough.
+
+      @section stdextmotivation Motivation
+    
       There are some feature I am often missing in standard C++. They
       are relatively easy to obtain, but they could be even simpler. I
       am mainly a convinced C++ programmer, because I love
@@ -86,11 +116,36 @@ namespace mrw {
       operators. If you don't want this, just don't include any of
       these include files files. There's no impact from this module,
       if you don't include a header, since all code is inline.
-
+  */
-      @warning This code is still experimental and subject to frequent
+  //@{
-      changes! Do not rely your projects on it yet!
+  /** @defgroup stdextstring String extensions
-
+
-      @since 1.0.0
+      The string extensions give you a lot of new powerful operations:
+       - convert anything to string:
+         @code
+         std::string s = mrw::string(15);
+         @endcode
+       - convert a string to something else:
+         @code
+         double d = mrw::to<double>("3.1415926535898");
+         @endcode
+       - shift values into a string:
+         @code
+         std::string s;
+         s<<"length is: "<<i<<"mm";
+         @endcode
+       - read values from a string:
+         @code
+         std::string s("1 2 4 8");
+         int i1, i2, i3, i4;
+         s>>i1>>i2>>i3>>i4;
+         @endcode
+       - add all kind of integer and floating point numbers to a string:
+         @code
+         std::string s("hello");
+         s += 4;
+         s = 13.5 + s + 24.8;
+         @endcode
   */
   //@{
 
@@ -131,12 +186,16 @@ namespace mrw {
   }
 
   //@}
+  //@}
 
 }
 
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup stdextstring
+ */
+//@{
 
 /** @brief append any value to a string
 
@@ -469,6 +528,7 @@ inline std::string& operator+=(std::string& s, signed long o)
   return s+=mrw::string(o);
 }
 
+//@}
 //@}
 
 #endif

mrw/tokenizer.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/12/17 16:26:58  marc
     initial version
 
@@ -21,6 +24,9 @@
 namespace mrw {
 
   /** @addtogroup regexp
+   */
+  //@{
+  /** @defgroup regexptokenizer Tokenizer
 
       There is a Tokenizer which splits strings according to a list of
       delimiters and allows to iterate over the individual tokens:
@@ -167,5 +173,6 @@ namespace mrw {
     bool _greedy;
   };
   //@}
+  //@}
 }
 

mrw/vector.hpp

@@ -9,6 +9,9 @@
     @license LGPL, see file <a href="license.html">COPYING</a>
 
     $Log$
+    Revision 1.2  2004/12/20 07:40:36  marc
+    documentation improved, new grouping
+
     Revision 1.1  2004/10/07 09:31:30  marc
     new feature
 
@@ -24,6 +27,12 @@
 /** @addtogroup StdExt
  */
 //@{
+/** @addtogroup StdExtSTL
+ */
+//@{
+/** @defgroup StdExtvector vector
+ */
+//@{
 
 /** @brief push a value to a vector
 
@@ -58,7 +67,7 @@ std::vector<T, A>& operator<<(std::vector<T, A>& l, const T& o) throw(std::bad_e
     @note when something is extracted from a vector, it is removed
     from the vector, that means after every shift the vector is
     shortened by the shifted element
-    @pre #include <mrw/string.hpp>
+    @pre #include <mrw/vector.hpp>
 */
 template <typename T, typename A>
 std::vector<T, A>& operator>>(std::vector<T, A>& l, T& o) throw(std::exception) {
@@ -72,6 +81,8 @@ std::vector<T, A>& operator>>(std::vector<T, A>& l, T& o) throw(std::exception)
   return l;
 }
 
+//@}
+//@}
 //@}
 
 #endif