Flags.h

Go to the documentation of this file.

// -*- C++ -*-
/* GG is a GUI for SDL and OpenGL.
   Copyright (C) 2007 T. Zachary Laine

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public License
   as published by the Free Software Foundation; either version 2.1
   of the License, or (at your option) any later version.
   
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.
    
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
   02111-1307 USA

   If you do not wish to comply with the terms of the LGPL please
   contact the author as other terms are available for a fee.
    
   Zach Laine
   whatwasthataddress@hotmail.com */

#ifndef _GG_Flags_h_
#define _GG_Flags_h_

#include <boost/lexical_cast.hpp>
#include <boost/serialization/access.hpp>
#include <boost/serialization/nvp.hpp>

#include <iosfwd>
#include <map>
#include <set>
#include <stdexcept>


namespace GG {

namespace detail {
    inline int OneBits(unsigned int num)
    {
        int retval = 0;
        const int NUM_BITS = sizeof(num) * 8;
        for (int i = 0; i < NUM_BITS; ++i) {
            if (num & 1)
                ++retval;
            num >>= 1;
        }
        return retval;
    }
}


template <class T>
struct is_flag_type : boost::mpl::false_ {};


#define GG_FLAG_TYPE(name)                                              \
    class name;                                                         \
                                                                        \
    template <>                                                         \
    struct is_flag_type<name> : boost::mpl::true_ {};                   \
                                                                        \
    class name                                                          \
    {                                                                   \
    public:                                                             \
        name() : m_value(0) {}                                          \
        explicit name(unsigned int value) :                             \
            m_value(value)                                              \
            {                                                           \
                if (1 < detail::OneBits(value))                         \
                    throw std::invalid_argument(                        \
                        "Non-bitflag passed to " #name " constructor"); \
            }                                                           \
        bool operator==(name rhs) const                                 \
            { return m_value == rhs.m_value; }                          \
        bool operator!=(name rhs) const                                 \
            { return m_value != rhs.m_value; }                          \
        bool operator<(name rhs) const                                  \
            { return m_value < rhs.m_value; }                           \
    private:                                                            \
        unsigned int m_value;                                           \
        friend class Flags<name>;                                       \
                                                                        \
        friend class boost::serialization::access;                      \
        template <class Archive>                                        \
        void serialize(Archive& ar, const unsigned int version)         \
            { ar & BOOST_SERIALIZATION_NVP(m_value); }                  \
    };                                                                  \
                                                                        \
    template <>                                                         \
    FlagSpec<name>& FlagSpec<name>::instance();                         \
                                                                        \
    inline std::ostream& operator<<(std::ostream& os, name n)           \
    {                                                                   \
        os << FlagSpec<name>::instance().ToString(n);                   \
        return os;                                                      \
    }                                                                   \
                                                                        \
    inline std::istream& operator>>(std::istream& is, name& n)          \
    {                                                                   \
        std::string str;                                                \
        is >> str;                                                      \
        n = FlagSpec<name>::instance().FromString(str);                 \
        return is;                                                      \
    }


#define GG_FLAGSPEC_IMPL(name)                          \
    template <>                                         \
    FlagSpec<name>& FlagSpec<name>::instance()          \
    {                                                   \
        static FlagSpec retval;                         \
        return retval;                                  \
    }


template <class FlagType>
class GG_API FlagSpec
{
public:
    // If you have received an error message directing you to the line below, it means you probably have tried to use
    // this class with a FlagsType that is not a type generated by GG_FLAG_TYPE.  Use that to generate new flag types.
    BOOST_MPL_ASSERT((is_flag_type<FlagType>));

    typedef typename std::set<FlagType>::iterator iterator;
    typedef typename std::set<FlagType>::const_iterator const_iterator;
 

    GG_ABSTRACT_EXCEPTION(Exception);

    GG_CONCRETE_EXCEPTION(UnknownFlag, GG::FlagSpec, Exception);

    GG_CONCRETE_EXCEPTION(UnknownString, GG::FlagSpec, Exception);

    static FlagSpec& instance();
 

    bool contains(FlagType flag) const
        { return find(flag) != end(); }
    bool permanent(FlagType flag) const
        { return m_permanent.find(flag) != m_permanent.end(); }
    const_iterator find(FlagType flag) const
        { return m_flags.find(flag); }
    const_iterator begin() const
        { return m_flags.begin(); }
    const_iterator end() const
        { return m_flags.end(); }
    const std::string& ToString(FlagType flag) const
        {
            typename std::map<FlagType, std::string>::const_iterator it = m_strings.find(flag);
            if (it == m_strings.end())
                throw UnknownFlag("Could not find string corresponding to unknown flag");
            return it->second;
        }
    FlagType FromString(const std::string& str) const
        {
            for (typename std::map<FlagType, std::string>::const_iterator it = m_strings.begin();
                 it != m_strings.end();
                 ++it) {
                if (it->second == str)
                    return it->first;
            }
            throw UnknownString("Could not find flag corresponding to unknown string");
            return FlagType(0);
        }
 

    void insert(FlagType flag, const std::string& name, bool permanent = false)
        {
            bool insert_successful = m_flags.insert(flag).second;
            assert(insert_successful);
            if (permanent)
                m_permanent.insert(flag);
            m_strings[flag] = name;
        }
    bool erase(FlagType flag)
        {
            bool retval = true;
            if (permanent(flag)) {
                retval = false;
            } else {
                m_flags.erase(flag);
                m_permanent.erase(flag);
                m_strings.erase(flag);
            }
            return retval;
        }

private:
    FlagSpec() {}

    std::set<FlagType>              m_flags;
    std::set<FlagType>              m_permanent;
    std::map<FlagType, std::string> m_strings;
};


template <class FlagType>
class Flags;

template <class FlagType>
std::ostream& operator<<(std::ostream& os, Flags<FlagType> flags);

template <class FlagType>
class Flags
{
private:
    struct ConvertibleToBoolDummy {int _;};

public:
    // If you have received an error message directing you to the line below, it means you probably have tried to use
    // this class with a FlagsType that is not a type generated by GG_FLAG_TYPE.  Use that to generate new flag types.
    BOOST_MPL_ASSERT((is_flag_type<FlagType>));
 

    GG_ABSTRACT_EXCEPTION(Exception);

    GG_CONCRETE_EXCEPTION(UnknownFlag, GG::Flags, Exception);
 

    Flags() : m_flags(0) {}
    Flags(FlagType flag) :
        m_flags(flag.m_value)
        {
            if (!FlagSpec<FlagType>::instance().contains(flag))
                throw UnknownFlag("Invalid flag with value " + boost::lexical_cast<std::string>(flag.m_value));
        }
 

    operator int ConvertibleToBoolDummy::* () const
        { return m_flags ? &ConvertibleToBoolDummy::_ : 0; }
    bool operator==(Flags<FlagType> rhs) const
        { return m_flags == rhs.m_flags; }
    bool operator!=(Flags<FlagType> rhs) const
        { return m_flags != rhs.m_flags; }
    bool operator<(Flags<FlagType> rhs) const
        { return m_flags < rhs.m_flags; }
 

    Flags<FlagType>& operator|=(Flags<FlagType> rhs)
        {
            m_flags |= rhs.m_flags;
            return *this;
        }
    Flags<FlagType>& operator&=(Flags<FlagType> rhs)
        {
            m_flags &= rhs.m_flags;
            return *this;
        }
    Flags<FlagType>& operator^=(Flags<FlagType> rhs)
        {
            m_flags ^= rhs.m_flags;
            return *this;
        }

private:
    unsigned int m_flags;

    friend std::ostream& operator<<<>(std::ostream& os, Flags<FlagType> flags);

    friend class boost::serialization::access;
    template <class Archive>
    void serialize(Archive& ar, const unsigned int version);
};

template <class FlagType>
std::ostream& operator<<(std::ostream& os, Flags<FlagType> flags)
{
    unsigned int flags_data = flags.m_flags;
    bool flag_printed = false;
    for (unsigned int i = 0; i < sizeof(flags_data) * 8; ++i) {
        if (flags_data & 1) {
            if (flag_printed)
                os << " | ";
            os << FlagSpec<FlagType>::instance().ToString(FlagType(1 << i));
            flag_printed = true;
        }
        flags_data >>= 1;
    }
    return os;
}

template <class FlagType>
Flags<FlagType> operator|(Flags<FlagType> lhs, Flags<FlagType> rhs)
{
    Flags<FlagType> retval(lhs);
    retval |= rhs;
    return retval;
}

template <class FlagType>
Flags<FlagType> operator|(Flags<FlagType> lhs, FlagType rhs)
{ return lhs | Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator|(FlagType lhs, Flags<FlagType> rhs)
{ return Flags<FlagType>(lhs) | rhs; }

template <class FlagType>
typename boost::enable_if<
    is_flag_type<FlagType>,
    Flags<FlagType>
>::type
operator|(FlagType lhs, FlagType rhs)
{ return Flags<FlagType>(lhs) | Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator&(Flags<FlagType> lhs, Flags<FlagType> rhs)
{
    Flags<FlagType> retval(lhs);
    retval &= rhs;
    return retval;
}

template <class FlagType>
Flags<FlagType> operator&(Flags<FlagType> lhs, FlagType rhs)
{ return lhs & Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator&(FlagType lhs, Flags<FlagType> rhs)
{ return Flags<FlagType>(lhs) & rhs; }

template <class FlagType>
typename boost::enable_if<
    is_flag_type<FlagType>,
    Flags<FlagType>
>::type
operator&(FlagType lhs, FlagType rhs)
{ return Flags<FlagType>(lhs) & Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator^(Flags<FlagType> lhs, Flags<FlagType> rhs)
{
    Flags<FlagType> retval(lhs);
    retval ^= rhs;
    return retval;
}

template <class FlagType>
Flags<FlagType> operator^(Flags<FlagType> lhs, FlagType rhs)
{ return lhs ^ Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator^(FlagType lhs, Flags<FlagType> rhs)
{ return Flags<FlagType>(lhs) ^ rhs; }

template <class FlagType>
typename boost::enable_if<
    is_flag_type<FlagType>,
    Flags<FlagType>
>::type
operator^(FlagType lhs, FlagType rhs)
{ return Flags<FlagType>(lhs) ^ Flags<FlagType>(rhs); }

template <class FlagType>
Flags<FlagType> operator~(Flags<FlagType> flags)
{
    Flags<FlagType> retval;
    const FlagSpec<FlagType>& spec = FlagSpec<FlagType>::instance();
    for (typename FlagSpec<FlagType>::const_iterator it = spec.begin(); it != spec.end(); ++it) {
        if (!(*it & flags))
            retval |= *it;
    }
    return retval;
}

template <class FlagType>
typename boost::enable_if<
    is_flag_type<FlagType>,
    Flags<FlagType>
>::type
operator~(FlagType flag)
{ return ~Flags<FlagType>(flag); }

} // namespace GG

template <class FlagType>
template <class Archive>
void GG::Flags<FlagType>::serialize(Archive& ar, const unsigned int version)
{ ar & BOOST_SERIALIZATION_NVP(m_flags); }

#endif // _GG_Flags_h_

---