/** @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__LIST__HPP__
#define __MRW__LIST__HPP__

#include <list>
#include <mrw/exception.hpp>
#include <mrw/string.hpp>

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

/** @brief push a value to a list

    @code
    std::list<int> test;
    test<<1<<2<<3<<4<<5<<6<<7<<8;
    @endcode

    @param l a list of values
    @param o a value to be inserted into list @c l
    @pre #include <mrw/list.hpp>
*/
template <typename T, typename A>
std::list<T, A>& operator<<(std::list<T, A>& l, const T& o) throw(std::bad_exception) {
  l.push_back(o);
  return l;
}

/** @brief extract the first value of a list

    @code
    std::list<int> test;
    test<<1<<2<<3<<4<<5<<6<<7<<8;
    int i1(0), i2(0), i3(0), i4(0);
    test>>i1>>i2>>i3>>i4;
    // now: i1==1 i2==2 i3==3 i4==4 test=={5, 6, 7, 8}
    @endcode

    @param l a list of values
    @param o a value to be extracted from list @c l
    @throw mrw::length_error, if list was empty on entry
    @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>
*/
template <typename T, typename A>
std::list<T, A>& operator>>(std::list<T, A>& l, T& o) throw(std::exception) {
  typename std::list<T, A>::iterator it(l.begin());
  if (it==l.end())
    throw mrw::length_error(std::string(__FILE__ ":")+__LINE__+
                            ": std::list<>& operator>>(std::list<>&, T&),"
                            " list is empty");
  o = *it;
  l.erase(it);
  return l;
}

//@}

#endif