documentation improved, new grouping

20 years ago · fc0254a342
parent 7089221d40
commit fc0254a342
13 changed files with 252 additions and 22 deletions
--- a/mrw/auto.hpp
+++ b/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
  */
  //@{
  
--- a/mrw/deque.hpp
+++ b/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
--- a/mrw/exec.cpp
+++ b/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 <unistd.h> // fork, exec
+#include <sys/wait.h> // waitpid
+#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
--- a/mrw/list.hpp
+++ b/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
--- a/mrw/map.hpp
+++ b/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
--- a/mrw/multimap.hpp
+++ b/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
--- a/mrw/multiset.hpp
+++ b/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
--- a/mrw/regexp.hpp
+++ b/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 {
  
  };
  //@}
+  //@}
 }
--- a/mrw/set.hpp
+++ b/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
--- a/mrw/stdext.hpp
+++ b/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');

  //@}
+  //@}
 }
--- a/mrw/string.hpp
+++ b/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!
-
-      @since 1.0.0
+  */
+  //@{
+  /** @defgroup stdextstring String extensions
+
+      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
--- a/mrw/tokenizer.hpp
+++ b/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;
  };
  //@}
+  //@}
 }

--- a/mrw/vector.hpp
+++ b/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