/** @file

    $Id$

    $Date$
    $Author$

    @copy © Marc Wäckerlin
    @license LGPL, see file <a href="license.html">COPYING</a>

    $Log$
    Revision 1.1  2004/10/07 09:31:30  marc
    new feature


*/
#ifndef __MRW__STRING__HPP__
#define __MRW__STRING__HPP__

#include <string>
#include <sstream>


namespace mrw {
  
  /** @defgroup StdExt Extensions for C++ Standard Libraries
    
      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
      simplicity. This means, to convert an integer to a string,
      something like this is not simple enough:

      @code
        int i;
        std::string s;
          [...]
        std::stringstream ss;
        ss<<"length is: "<<i<<"mm";
        ss>>s;
      @endcode

      Why can't it simply be:

      @code
        int i;
        std::string s;
          [...]
        s<<"length is: "<<i<<"mm";
      @endcode

      Or:

      @code
        int i;
        std::string s;
          [...]
        s += i; // convert i to string and append it
      @endcode

      Because we are using the great and powerful C++ language, it can
      be! That's why you need this module.

      In addition to the shift in and shift out operator for strings,
      you also get a shhift in and shift out operator for all STL
      container classes:

      @code
        std::list<int> l;
        l<<1<<2<<<3<<4;
        int i1, i2, i3, i4;
        l>>i1>>i2>>i3>>i4;
      @endcode

      And the possibility to add strings to integers and vice versa:
      
      @code
        std::string s("x");
        s = 1+s+2; // s=="1x2"
      @endcode

      @warning Please note that global namespace is polluted with some
      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
  */
  //@{


  /** @brief convert any value to a std::string 

      @code
      std::string s = mrw::string(15);
      @endcode

      @param o a value to be converted to std::string
      @pre #include <mrw/string.hpp>
      @pre T must support operator<< to a stream

  */
  template <typename T> std::string string(const T& o) throw(std::bad_exception) {
    std::stringstream ss;
    ss<<o;
    return ss.str();
  }

  /** @brief convert std::string to any value

      @code
      int i = mrw::to<int>("15");
      @endcode

      @param s the string where a value of type @c T is extracted from
      @pre #include <mrw/string.hpp>
      @pre T must support operator>> from a stream
  */
  template <typename T> T to(const std::string& s) throw(std::bad_exception) {
    T o;
    std::stringstream ss(s);
    ss>>o;
    return o;
  }

  //@}

}

/** @addtogroup StdExt
 */
//@{

/** @brief append any value to a string

    @code
    std::string s;
    s<<"length is: "<<i<<"mm";
    @endcode

    @param s the string, where o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
    @pre T must support operator<< to a stream
*/
template <typename T> std::string& operator<<(std::string& s, const T& o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief extract any value from a string

    @code
    std::string s1("length: 15 mm");
    string s2, s3;
    int i(0);
    s1>>s2>>is3;
    // now: s1=="" s2=="length:" i==15 s3=="mm"
    @endcode

    @param s the string, from which o is extracted
    @param o the value to extract from s
    @note when something is extracted from a string, it is removed
    from the string, that means after every shift the string is
    shortened by the shifted element
    @pre #include <mrw/string.hpp>
    @pre T must support operator>> from a stream
*/
template <typename T> std::string& operator>>(std::string& s, T& o) throw(std::bad_exception) {
  std::stringstream ss(s);
  ss>>o;
  return (s=ss.tellg()>0?s.substr(ss.tellg()):"");
}

/** @brief add a @c unsigned short value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, unsigned short o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to a @c unsigned short value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(unsigned short o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}

/** @brief add an @c unsigned int value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, unsigned int o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to an @c unsigned int value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(unsigned int o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}

/** @brief add a @c unsigned long value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, unsigned long o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to a @c unsigned long value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(unsigned long o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}

/** @brief add a @c signed short value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, signed short o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to a @c signed short value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(signed short o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}

/** @brief add an @c signed int value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, signed int o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to an @c signed int value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(signed int o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}

/** @brief add a @c signed long value to a string

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(const std::string& s, signed long o) throw(std::bad_exception) {
  return s+mrw::string(o);
}

/** @brief append a string to a @c signed long value

    @code
    std::string s;
    s+"length is: "+i+"mm";
    @endcode

    @param s the string, where @c o is prepended
    @param o the value to prepend in front of @c s
    @pre #include <mrw/string.hpp>
*/
std::string operator+(signed long o, const std::string& s) throw(std::bad_exception) {
  return mrw::string(o)+s;
}


/** @brief add a @c unsigned short value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, unsigned short o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief add an @c unsigned int value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, unsigned int o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief add a @c unsigned long value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, unsigned long o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief add a @c signed short value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, signed short o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief add an @c signed int value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, signed int o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

/** @brief add a @c signed long value to a string

    @code
    std::string s;
    s += o;
    @endcode

    @param s the string, where @c o is appended
    @param o the value to append to @c s
    @pre #include <mrw/string.hpp>
*/
std::string& operator+=(std::string& s, signed long o) throw(std::bad_exception) {
  return s+=mrw::string(o);
}

//@}

#endif